Install Backend

Backend Installation Guide

This guide will walk you through setting up the Stelo CMS backend on your development machine and deploying it to production.

Prerequisites

Before starting, ensure you have:

• Node.js 18+ (recommended: use nvm)
• npm or pnpm (recommended)
• Git for version control
• Docker (for local PostgreSQL)
• Digital Ocean account (for production)

Development Setup

1. Clone the Template Repository

# Clone the Stelo CMS template
git clone https://github.com/your-username/template-stelo-cms.git client-project-cms
cd client-project-cms

# Remove the original git history
rm -rf .git
git init
git add .
git commit -m "Initial commit from Stelo CMS template"

2. Install Dependencies

# Using pnpm (recommended)
pnpm install

# Or using npm
npm install

3. Environment Configuration

Copy the environment template and configure your variables:

cp .env.example .env.local

Edit .env.local with your configuration:

# Database
DATABASE_URL="postgresql://postgres:password@localhost:5432/stelo_cms"

# NextAuth.js
NEXTAUTH_SECRET="your-super-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"

# Digital Ocean Spaces (for file uploads)
DO_SPACES_ENDPOINT="https://fra1.digitaloceanspaces.com"
DO_SPACES_BUCKET="your-bucket-name"
DO_SPACES_ACCESS_KEY="your-access-key"
DO_SPACES_SECRET_KEY="your-secret-key"

# Optional: Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# Optional: Email provider (for notifications)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"

4. Database Setup

Option A: Local PostgreSQL with Docker

# Start PostgreSQL container
docker run --name stelo-postgres \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=stelo_cms \
  -p 5432:5432 \
  -d postgres:17-alpine

# Verify connection
docker exec -it stelo-postgres psql -U postgres -d stelo_cms -c "SELECT version();"

Option B: Digital Ocean Managed Database

1. Create a PostgreSQL database in Digital Ocean
2. Update DATABASE_URL in .env.local with the connection string
3. Ensure your IP is added to trusted sources

5. Database Migration

# Generate Prisma client
pnpm prisma generate

# Run database migrations
pnpm prisma db push

# Seed the database with initial data
pnpm prisma db seed

6. Start Development Server

# Start the development server
pnpm dev

# The CMS will be available at:
# http://localhost:3000

7. Create Admin User

Visit http://localhost:3000/admin/setup to create your first admin user, or use the seed script:

# Run the admin setup script
pnpm run setup:admin

Production Deployment

1. Prepare Digital Ocean Infrastructure

VPS Setup

# Create a new droplet (2GB Memory / 50GB Disk / Ubuntu 24.04)
# Note the IP address for later configuration

Database Setup

# Create a PostgreSQL database cluster
# Note the connection details for environment variables

Storage Setup

# Create a Digital Ocean Space
# Generate access keys for file uploads

2. Install Coolify on VPS

# SSH into your VPS
ssh root@your-vps-ip

# Install Coolify
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash

# Access Coolify at http://your-vps-ip:8000

3. Configure Deployment

Create Application in Coolify

1. Source: Connect your Git repository
2. Build Pack: Node.js
3. Environment Variables: Add production variables

Environment Variables (Production)

# Database (Digital Ocean Managed)
DATABASE_URL="postgresql://username:password@host:port/database?sslmode=require"

# NextAuth.js
NEXTAUTH_SECRET="production-secret-key"
NEXTAUTH_URL="https://cms.your-domain.com"

# Digital Ocean Spaces
DO_SPACES_ENDPOINT="https://fra1.digitaloceanspaces.com"
DO_SPACES_BUCKET="client-assets"
DO_SPACES_ACCESS_KEY="production-access-key"
DO_SPACES_SECRET_KEY="production-secret-key"

# Email
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="noreply@your-domain.com"
SMTP_PASSWORD="production-password"

4. Build Configuration

Create Dockerfile in your project root:

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json pnpm-lock.yaml* ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Generate Prisma client
RUN npx prisma generate

# Build the application
RUN npm run build

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Automatically leverage output traces to reduce image size
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT 3000

CMD ["node", "server.js"]

5. Deploy Application

1. Push to Git: Commit and push your changes
2. Deploy in Coolify: Click “Deploy” in your Coolify dashboard
3. Run Migrations: Execute database migrations in production

# SSH into your production container
docker exec -it your-container-name bash

# Run production migrations
npx prisma migrate deploy

# Create admin user
npm run setup:admin

6. Domain Configuration

SSL Certificate

Coolify automatically handles SSL certificates via Let’s Encrypt.

DNS Configuration

Point your domain to your VPS IP:

Type: A
Name: cms.your-domain.com
Value: your-vps-ip
TTL: 300

Security Configuration

1. Firewall Setup

# On your VPS
ufw allow ssh
ufw allow 80
ufw allow 443
ufw allow 8000  # Coolify
ufw --force enable

2. Environment Security

• Use strong, unique passwords
• Enable 2FA where possible
• Regularly rotate API keys
• Monitor access logs

3. Database Security

• Use connection pooling
• Enable SSL connections
• Regular backups
• Monitor query performance

Troubleshooting

Common Issues

Database Connection Errors

# Check database connectivity
npx prisma studio

# Reset database schema
npx prisma migrate reset

Build Failures

# Clear build cache
rm -rf .next
rm -rf node_modules
pnpm install
pnpm build

Environment Variable Issues

# Verify environment variables
printenv | grep DATABASE_URL
printenv | grep NEXTAUTH_SECRET

Monitoring & Logs

Application Logs

# View Coolify logs
docker logs your-container-name

# View real-time logs
docker logs -f your-container-name

Database Monitoring

# Check database performance
npx prisma studio

Next Steps

After successful installation:

1. Configure Entities - Set up your content structure
2. Setup Permissions - Configure user roles
3. Install Frontend - Deploy your client site

Maintenance

Regular Tasks

• Weekly: Check application logs and performance
• Monthly: Update dependencies and security patches
• Quarterly: Database maintenance and optimization
• Annually: Rotate API keys and certificates