Introduction

Configuration

This guide covers configuring your CellCMS project, including environment variables, asset storage, monitoring, and security best practices.

Environment Variables

Project Configuration

Variable	Required	Default	Description
`JWT_SECRET`	Yes	—	JWT signing secret. Generate with `openssl rand -base64 64`
`CORS_ORIGIN`	No	`https://studio.cellcms.com`	Allowed CORS origin
`STORAGE_TYPE`	No	`s3`	Asset storage backend (`s3`)
`S3_BUCKET`	No	—	S3/R2 bucket name
`S3_REGION`	No	—	S3 region
`S3_ENDPOINT`	No	—	Custom S3 endpoint (R2)
`S3_ACCESS_KEY_ID`	No	—	S3 access key
`S3_SECRET_ACCESS_KEY`	No	—	S3 secret key

API Variables

Variable	Default	Description
`DATABASE_URL`	—	PostgreSQL connection string
`JWT_SECRET`	—	JWT signing secret
`JWT_ACCESS_EXPIRES_IN`	`15m`	Access token lifetime
`JWT_REFRESH_EXPIRES_IN`	`7d`	Refresh token lifetime
`PORT`	`4000`	API server port
`HOST`	`0.0.0.0`	API server bind address
`CORS_ORIGIN`	`https://studio.cellcms.com`	Allowed CORS origin
`STORAGE_TYPE`	`s3`	Asset storage backend

PostgreSQL Configuration

Connection Pool

The API uses a connection pool with these defaults:

Setting	Value	Description
`max`	20	Maximum connections
`idleTimeoutMillis`	30,000	Close idle connections after 30s
`connectionTimeoutMillis`	5,000	Fail if connection takes >5s

For high-traffic projects, increase max by setting it in the DATABASE_URL or modifying the pool configuration.

Migrations

Migrations are applied automatically when your project is provisioned. For manual migration:

# Apply the initial schema
psql $DATABASE_URL < migrations/001_initial-schema.sql

# Or use the migration runner
pnpm migrate:up

To rollback:

pnpm migrate:down

Asset Storage

CellCMS stores assets in S3-compatible cloud storage.

S3 Configuration

STORAGE_TYPE=s3
S3_BUCKET=my-cellcms-assets
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=AKIA...
S3_SECRET_ACCESS_KEY=...

Cloudflare R2:

STORAGE_TYPE=s3
S3_BUCKET=cellcms-assets
S3_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

Monitoring

Health Check

The /api/v1/health endpoint returns:

{
  "status": "ok",
  "timestamp": "2025-01-15T10:00:00.000Z",
  "connections": 3
}

Use this for uptime monitoring and alerting.

Logging

CellCMS uses structured JSON logging (Pino) in production for easy integration with log aggregation services.

Security Checklist

Before going live:

Set a strong JWT_SECRET (generated with openssl rand -base64 64)
Change the default admin password
Set CORS_ORIGIN to your actual Studio domain
Review API token permissions (use read-only for frontends)
Set up database backups
Use S3 storage for assets

Graceful Shutdown

The API server handles SIGTERM and SIGINT signals gracefully:

Stops accepting new connections
Finishes in-flight requests
Closes the database connection pool
Exits cleanly

Getting Started — Quick start guide
Authentication — JWT and token configuration
Assets & Images — Storage configuration
Troubleshooting — Common issues

Getting Started

Schema Definition