Self-hosting Stubby CMS: The Ultimate Deployment Guide

Updated on

Learn how to self-host Stubby CMS on popular cloud platforms like Vercel, DigitalOcean, Railway, or Render. This comprehensive guide walks you through the technical requirements and deployment steps to get your own instance of this powerful headless CMS up and running.

Why Self-Host Stubby CMS?

Self-hosting gives you full control over your data, infrastructure, and costs. As an open-source, Next.js-based headless CMS, Stubby is designed to be lightweight, developer-friendly, and easy to scale on modern hosting providers.

Step 1: Clone the Source Code

To begin, you need a local copy of the Stubby CMS repository. We recommend forking the official repository so you can easily manage updates and custom configurations.

# Clone the official repository
git clone https://github.com/stubbycms/stubby.git
cd stubby

Once cloned, you can push this to your own private or public GitHub repository to enable CI/CD features on platforms like Vercel.

Step 2: Install Project Dependencies

Stubby CMS uses modern JavaScript tooling. Navigate to the root directory and install the necessary packages using your preferred package manager:

yarn install
# or
npm install

Step 3: Configure Environment Variables

Environment variables are critical for connecting your CMS to its database and external services. Rename the .env.example template to .env.local and update the values.

# Host Configuration
NEXT_PUBLIC_HOST="https://your-domain.com"
NEXT_PUBLIC_ROOT_DOMAIN="your-domain.com"

# Image Storage (CDN)
NEXT_PUBLIC_CDN_URL="https://your-bunny-cdn-url.io"
BUNNY_API_KEY="your-bunny-api-key"

# PostgreSQL Database
POSTGRES_DB_URL="postgresql://user:password@host:port/db-name?sslmode=require"

# Authentication (NextAuth)
NEXTAUTH_URL="https://your-domain.com"
NEXTAUTH_SECRET="your-generated-secret"

Key Variables Explained:

  • NEXT_PUBLIC_HOST: Your production URL.
  • POSTGRES_DB_URL: Your connection string. We recommend Neon.tech or Vercel Postgres for managed serverless databases.
  • NEXTAUTH_SECRET: A random string used to hash tokens. You can generate one using openssl rand -base64 32.
 
Always keep your .env files out of version control. Most hosting platforms provide a dedicated UI to input these "Secret" variables.

Step 4: Database Setup and Schema Migration

Stubby CMS leverages Prisma ORM for database management. Once your PostgreSQL instance is live and the connection string is added to your environment variables, sync your schema:

npx prisma db push

Seeding the Admin Account

To log in for the first time, you must seed the database with an initial user:

  1. Rename prisma/seed.ts.example to seed.ts.
  2. Edit seed.ts to set your desired admin email and password.
  3. Execute the seed command:
npx prisma db seed
 
Security Warning: Delete the seed.ts file immediately after successful seeding to prevent unauthorized access or accidental credential leaks.

Step 5: Local Development Testing

Before deploying to production, verify that the application runs correctly on your machine:

npm run dev

Visit http://localhost:3000 to ensure the dashboard and authentication flow are working as expected.

Step 6: Deploying to Production

Since Stubby CMS is a Next.js application, it is compatible with any platform that supports Node.js.

  1. Connect Repository: Import your GitHub repository into the Vercel Dashboard.
  2. Environment Variables: Paste the contents of your .env.local into the Vercel "Environment Variables" section.
  3. Build Settings: Vercel automatically detects Next.js settings. Click Deploy.

Deploying to DigitalOcean App Platform

  1. Create a new "App" and link your repository.
  2. Select the Next.js component.
  3. Add your environment variables in the configuration tab.
  4. DigitalOcean will handle the build and provide a secure SSL endpoint.

Deploying to Railway or Render

Both platforms offer excellent support for Docker or direct Node.js deployments. Ensure you provide the POSTGRES_DB_URL and set the start command to npm run start.

Step 7: Configuring Image Hosting (Bunny.net)

By default, Stubby CMS is optimized for Bunny.net for image processing and global delivery.

  1. Create a Pull Zone and Storage Zone on Bunny.net.
  2. Add your BUNNY_API_KEY to your environment variables.
  3. This ensures your blog images are served via a high-performance CDN, improving your site's Core Web Vitals and SEO.

FAQ: Self-Hosting Stubby CMS

Can I use a different database?

Stubby CMS is optimized for PostgreSQL. While Prisma supports other databases, we recommend PostgreSQL for full compatibility with our schema.

Is self-hosting free?

The software itself is free and open-source. Your hosting costs will depend on your provider (e.g., Vercel's free tier or a $5/month DigitalOcean Droplet).

How do I update my self-hosted instance?

To update, pull the latest changes from the official Stubby CMS repository, run npm install to update dependencies, and run npx prisma db push if there are schema changes.

Conclusion

Self-hosting Stubby CMS is a straightforward process that provides you with a high-performance, MDX-based content management system. By following this guide, you have set up a professional-grade stack including Next.js, PostgreSQL, and a global CDN.

Previous
Code Blocks
Next
Accordion