Installation
Everything you need to install and configure before creating your first Grit project. This guide covers system requirements, tool installation, and the Grit CLI setup.
System Requirements
Grit runs on macOS, Linux, and Windows. You need the following tools installed:
| Tool | Minimum Version | Required For | Check Command |
|---|---|---|---|
| Go | 1.21+ | Backend API + CLI | go version |
| Node.js | 18+ | Frontend apps | node --version |
| pnpm | 8+ | Package management | pnpm --version |
| Docker | Latest | PostgreSQL, Redis, MinIO | docker --version |
| Docker Compose | V2 | Service orchestration | docker compose version |
| Git | Any | Version control | git --version |
Installing Go
Go is required for both the Grit CLI and the backend API. Download the latest version from the official website or use a version manager.
macOS (Homebrew)
Linux (Ubuntu/Debian)
Windows
Download the MSI installer from go.dev/dl and run it. The installer adds Go to your system PATH automatically. Alternatively, use winget install GoLang.Go or scoop install go.
Installing Node.js
Node.js 18 or later is required for the Next.js frontend apps. We recommend using a version manager like nvm or fnm.
Using nvm (recommended)
Using Homebrew (macOS)
Installing pnpm
Grit uses pnpm for frontend package management. It is faster, more disk-efficient, and enforces stricter dependency resolution than npm or yarn.
Installing Docker
Docker is used to run PostgreSQL, Redis, MinIO, and Mailhog in development. Install Docker Desktop for your platform:
- macOS: Docker Desktop for Mac
- Windows: Docker Desktop for Windows (WSL2 backend recommended)
- Linux: Docker Engine + Docker Compose V2
After installation, verify Docker is running:
Installing the Grit CLI
The Grit CLI is a Go binary that you install globally. It provides the grit command for scaffolding projects, generating resources, running migrations, and syncing types.
This downloads, compiles, and installs the grit binary into your $GOPATH/bin directory (usually ~/go/bin). Make sure this directory is in your system PATH.
Verifying the Installation
Run the following command to verify everything is installed correctly:
Creating Your First Project
With all tools installed, you are ready to create your first Grit project:
Project Flags
The grit new command supports flags to customize what gets scaffolded:
| Flag | Description | What Gets Created |
|---|---|---|
| (default) | Full-stack project | Go API + Next.js web + admin panel + shared types + Docker |
| --api | Backend only | Go API with auth, Docker setup, no frontend apps |
| --full | Everything + mobile | Default + Expo mobile app + docs site |
Examples:
Troubleshooting
grit: command not found
This means $GOPATH/bin is not in your system PATH. Add the following to your shell profile (~/.zshrc, ~/.bashrc, or ~/.profile):
export PATH=$PATH:$(go env GOPATH)/bin
Then reload your shell: source ~/.zshrc. On Windows, make sure %GOPATH%\\bin is in your system PATH environment variable.
Docker daemon not running
If docker compose up fails with a connection error, make sure Docker Desktop is running. On Linux, start the Docker daemon with sudo systemctl start docker.
Port conflicts
If ports 5432, 6379, 8080, 3000, or 3001 are already in use, edit the .env file and docker-compose.yml to use different ports. Common conflicts:
- Port 5432 -- another PostgreSQL instance is running
- Port 3000 -- another Next.js or React dev server is running
- Port 8080 -- another API server or proxy is running
pnpm install fails
If pnpm install fails with peer dependency errors, try deleting the lockfile and node_modules folders and running again:
Cloud-only setup (no Docker)
If you cannot run Docker, Grit includes a .env.cloud.example file that configures the project to use cloud services instead:
- Database: Neon (free serverless PostgreSQL)
- Redis: Upstash (free serverless Redis)
- Storage: Cloudflare R2 or Backblaze B2
Copy the cloud example and fill in your credentials: