Installation

This page covers everything you need to know about installing FlameCMS — from system requirements to manual setup without the CLI.

System Requirements

Note: FlameCMS does not support MySQL, MariaDB, or SQLite. PostgreSQL is the only supported database engine because FlameCMS relies on PostgreSQL-specific features such as jsonb, uuid, and LISTEN/NOTIFY.

CLI Installation (Recommended)

The create-flamecms scaffolding tool is the fastest way to get started:

npx create-flamecms@latest my-cms
cd my-cms
npm run dev

The CLI creates a fully configured project, generates your .env file, installs dependencies, and runs the initial database migration.

CLI Options

You can pass flags to skip interactive prompts:

npx create-flamecms@latest my-cms \
  --db "postgresql://user:pass@localhost:5432/mydb" \
  --locale en \
  --no-graphql \
  --package-manager pnpm

Manual Installation

If you prefer to set up the project yourself:

1. Install the core package

mkdir my-cms && cd my-cms
npm init -y
npm install flamecms
npm install -D typescript @types/node tsx

2. Create tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist",
    "rootDir": "./",
    "paths": {
      "flamecms": ["./node_modules/flamecms"]
    }
  },
  "include": ["**/*.ts"],
  "exclude": ["node_modules", "dist"]
}

3. Create the configuration file

// flamecms.config.ts
import { defineConfig } from 'flamecms'

export default defineConfig({
  site: {
    name: 'My CMS',
    url: process.env.SITE_URL || 'http://localhost:3001',
  },
  database: {
    url: process.env.DATABASE_URL!,
  },
  server: {
    port: 3001,
    host: '0.0.0.0',
  },
  plugins: [],
})

4. Add scripts to package.json

{
  "scripts": {
    "dev":    "flamecms dev",
    "build":  "flamecms build",
    "start":  "flamecms start",
    "migrate":"flamecms migrate"
  }
}

5. Create the .env file

cp .env.example .env
# Then edit .env with your values

6. Run the first migration

npm run migrate
npm run dev

Environment Variables

FlameCMS reads configuration from environment variables at runtime. Below is the full reference:

Required

Optional — Server

Optional — Security

Optional — Media

Full .env.example

# ── Required ─────────────────────────────────────────────────────────────────
DATABASE_URL=postgresql://flame:secret@localhost:5432/flamecms
JWT_SECRET=change-me-to-a-random-string-at-least-32-characters
SITE_URL=http://localhost:3001

# ── Server ───────────────────────────────────────────────────────────────────
PORT=3001
HOST=0.0.0.0
NODE_ENV=development
LOG_LEVEL=info

# ── Security ─────────────────────────────────────────────────────────────────
JWT_EXPIRES_IN=15m
REFRESH_EXPIRES_IN=7d
BCRYPT_ROUNDS=12
RATE_LIMIT_MAX=20
RATE_LIMIT_WINDOW=60000
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# ── Media ─────────────────────────────────────────────────────────────────────
UPLOAD_MAX_SIZE=10485760
UPLOAD_DIR=./uploads

Verifying the Installation

After starting the dev server, verify FlameCMS is working:

# Health check
curl http://localhost:3001/health
# → {"status":"ok","version":"1.0.0","db":"connected"}

# API documentation
open http://localhost:3001/api/docs

Troubleshooting

Error: connect ECONNREFUSED 127.0.0.1:5432 PostgreSQL is not running or the DATABASE_URL is incorrect. Verify with:

psql $DATABASE_URL -c "SELECT 1"

Error: Cannot find module 'flamecms' Run npm install in your project root.

JWT_SECRET must be at least 32 characters Generate a safe secret: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"