Local Development

This guide covers running GritCMS on your local machine for development. The local setup uses SQLite for zero-configuration database access and includes hot reload for rapid iteration.

Prerequisites

Before starting, make sure you have the following installed:

• Go 1.24+ -- for the API backend
• Node.js 20+ -- for the frontend apps
• pnpm -- the package manager used by the monorepo (npm install -g pnpm)
• Git -- for cloning the repository
• Docker (optional) -- for running PostgreSQL, Redis, and MinIO via docker-compose.yml

Project Structure

GritCMS is a pnpm monorepo with three main services:

Installation

Clone the repository and install dependencies:

git clone https://github.com/your-org/gritcms.git
cd gritcms
pnpm install

This installs dependencies for all packages and apps in the monorepo.

Option A: SQLite (Simplest)

The API uses SQLite by default when no DATABASE_URL is set. This is the fastest way to get started -- no database server needed.

Running the Services

Open three terminal windows (or use a process manager):

Terminal 1 -- API:

cd apps/api
go run cmd/server/main.go

The API starts on http://localhost:8080 and stores data in a local grit.db file.

Terminal 2 -- Admin:

pnpm --filter admin dev

The admin dashboard starts on http://localhost:3000.

Terminal 3 -- Web:

pnpm --filter web dev

The public site starts on http://localhost:3001.

Option B: Docker Compose (Full Stack)

For a setup closer to production with PostgreSQL, Redis, and MinIO:

docker compose up -d

This starts PostgreSQL (port 5432), Redis (port 6379), MinIO (port 9000/9001), and MailHog (port 8025) using the docker-compose.yml in the project root.

Then create a .env file in apps/api/:

DATABASE_URL=postgres://grit:grit@localhost:5432/gritcms?sslmode=disable
REDIS_URL=redis://localhost:6379
MINIO_ENDPOINT=http://localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_BUCKET=uploads
STORAGE_DRIVER=minio

Start the services the same way as Option A (three terminals).

Hot Reload

Frontend Hot Reload

Both Next.js apps (admin and web) run in development mode with Fast Refresh enabled. When you edit a React component, the change appears in the browser instantly without a full page reload.

Backend Restart

The Go backend does not hot-reload by default. After making changes to Go files, stop the server (Ctrl+C) and run go run cmd/server/main.go again.

For automatic restarts, use air:

go install github.com/cosmtrek/air@latest
cd apps/api
air

Air watches for file changes and automatically rebuilds and restarts the Go server.

Initial Setup

After starting all services for the first time:

1. Visit http://localhost:3000 (admin dashboard)
2. Register your admin account (first user becomes admin)
3. Complete the Setup Wizard -- it saves your site settings and creates a default Home page
4. Visit http://localhost:3001 to see the public site

Alternatively, seed defaults manually:

curl -X POST http://localhost:8080/api/seed-defaults

Environment Variables

For local development, the defaults work without configuration. Optional variables:

Next Steps

Once you are comfortable with local development, see the Docker guide for containerized deployments or the Dokploy guide for deploying to a VPS.