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.21+ -- for the API backend
• Node.js 18+ -- for the frontend apps
• pnpm -- the package manager used by the monorepo (npm install -g pnpm)
• Git -- for cloning the repository

Project Structure

GritCMS is a pnpm monorepo with three main services:

There is also a shared types package at packages/shared used by both frontend apps.

Installation

Clone the repository and install dependencies:

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

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

Running the Services

You need to run all three services for a fully functional local environment. Open three terminal windows (or use a process manager).

API (Go Backend)

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

The API starts on http://localhost:8080. It uses SQLite by default when no DATABASE_URL environment variable is set, storing data in a local grit.db file.

Admin (Next.js Dashboard)

cd apps/admin
pnpm dev

The admin dashboard starts on http://localhost:3000. It proxies API requests to http://localhost:8080.

Web (Next.js Public Site)

cd apps/web
pnpm dev

The public site starts on http://localhost:3001. It also connects to the API at http://localhost:8080.

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. CSS and style changes are also hot-reloaded.

Backend Restart

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

For automatic restarts, you can use a tool like 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.

SQLite for Local Development

By default, the API uses SQLite as its database. This means:

• No database server to install or configure
• Data is stored in a single grit.db file in the apps/api directory
• GORM auto-migrates all models on startup, so the schema is always up to date
• You can delete grit.db at any time to start with a fresh database

SQLite is ideal for local development but not recommended for production. For production deployments, use PostgreSQL (see Docker or Dokploy guides).

Seeding Default Data

After starting the API for the first time, seed the database with default settings and sample data:

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

This creates default site settings (site name, branding, etc.) so the admin panel and public site render correctly out of the box. You only need to run this once per fresh database.

Environment Variables

For local development, the defaults work without any configuration. If you need to customize behavior, you can set these optional environment 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.