Installation

Prerequisites

Before you begin, make sure you have the following installed on your machine:

If you have Docker installed, you do not need to install PostgreSQL, Redis, or MinIO separately -- the included docker-compose.yml handles everything.

Step 1: Clone the Repository

git clone https://github.com/MUKE-coder/gritcms.git
cd gritcms

Step 2: Install Frontend Dependencies

From the monorepo root, install all JavaScript dependencies for the admin, web, and shared packages:

pnpm install

This uses pnpm workspaces to install dependencies for all three apps and the shared types package in a single command.

Step 3: Start Infrastructure Services

Use Docker Compose to spin up PostgreSQL, Redis, MinIO (file storage), and MailHog (email testing):

docker compose up -d

This starts the following services:

Step 4: Configure Environment Variables

Copy the example environment file and adjust as needed:

cp .env.example .env

The defaults work out of the box with the Docker Compose services. The key variables to verify:

APP_PORT=8080
DATABASE_URL=postgres://grit:grit@localhost:5432/gritcms?sslmode=disable
REDIS_URL=redis://localhost:6379
STORAGE_DRIVER=minio
JWT_SECRET=change-me-in-production

See the Environment Variables reference for the full list.

Step 5: Start the Backend API

Navigate to the API directory and start the Go server:

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

Or, if you have Air installed for live-reload:

pnpm dev:api

The API server starts on port 8080 by default. You will see output confirming database connection, Redis, storage, and available dashboards:

Server starting on port 8080
GORM Studio available at http://localhost:8080/studio
API Documentation at http://localhost:8080/docs

GORM auto-migrates all tables on startup -- no manual migration step is needed.

Step 6: Start the Admin Dashboard

In a new terminal, from the monorepo root:

pnpm --filter admin dev

The admin dashboard starts on http://localhost:3000. This is where you manage all content, products, contacts, and settings.

Step 7: Start the Public Website

In another terminal, from the monorepo root:

pnpm --filter web dev

The public website starts on http://localhost:3001. This is the visitor-facing frontend that renders your pages, blog, courses, and storefront.

All-in-One Development

You can also start all three frontend services simultaneously using Turborepo:

pnpm dev

This runs the admin and web dev servers in parallel. You still need to start the Go API separately (Step 5).

Verify the Setup

Once all services are running, verify everything is working:

Troubleshooting

Port already in use

If port 8080, 3000, or 3001 is already taken, change the port in your .env file (APP_PORT) or in the respective next.config files for the frontend apps.

Database connection refused

Make sure the Docker containers are running: docker compose ps. If PostgreSQL is not healthy, check logs with docker compose logs postgres.

pnpm install fails

Ensure you are using pnpm 10 or later. Check your version with pnpm --version. If you need to upgrade: npm install -g pnpm@latest.

Go module download errors

Run go mod download inside the apps/api directory to pre-fetch all Go dependencies. If you are behind a proxy, set GOPROXY=https://proxy.golang.org,direct.

Redis connection warning

Redis is optional for development. If Redis is not running, the API will log a warning and disable caching and background jobs. Everything else works normally.

MinIO bucket not found

On first startup, you may need to create the upload bucket manually via the MinIO Console at http://localhost:9001. Create a bucket named gritcms-uploads (or whatever MINIO_BUCKET is set to in your .env).