Skip to main content
Get SnailyCAD up and running with this step-by-step installation guide. Choose between Docker (recommended) or standalone installation.

​
Prerequisites

Before you begin, make sure you have:

Node.js

Version 18.16.0 or higher

PostgreSQL

Version 12 or higher

pnpm

Version 9.0.4 (package manager)

Git

For cloning the repository
SnailyCAD requires Node.js 18.16.0 or higher. Using an older version will cause installation to fail.

​
Installation Methods

Choose the installation method that works best for your setup:

Docker Installation

Recommended for most users. Easiest setup with containers.

Standalone Installation

Install directly on your server without Docker.

​
Quick Start (Docker)

The fastest way to get started is using Docker Compose.
1

Clone the Repository

git clone https://github.com/SnailyCAD/snaily-cadv4.git
cd snaily-cadv4
2

Copy Environment File

cp .env.example .env
Edit the .env file with your configuration:
# Required: Database credentials
POSTGRES_PASSWORD="your-secure-password"
POSTGRES_USER="postgres"
POSTGRES_DB="snaily-cad-v4"

# Required: Security tokens
JWT_SECRET="your-random-secret-key"
ENCRYPTION_TOKEN="your-32-character-token"

# Required: URLs
CORS_ORIGIN_URL="http://your-ip:3000"
NEXT_PUBLIC_CLIENT_URL="http://your-ip:3000"
NEXT_PUBLIC_PROD_ORIGIN="http://your-ip:8080/v1"
3

Generate Security Tokens

JWT_SECRET: Any random string of charactersENCRYPTION_TOKEN: Must be exactly 32 characters. Generate at CodeBeautify
4

Start with Docker Compose

docker compose -f production.docker-compose.yml up -d
This will:
  • Pull the necessary Docker images
  • Set up PostgreSQL database
  • Build and start the API and client
5

Access SnailyCAD

Once the containers are running:
  • Client: http://your-ip:3000
  • API: http://your-ip:8080/v1
Create your first account by registering through the web interface.
The first user to register will automatically become the owner with full administrative permissions.

​
Quick Start (Standalone)

For installation without Docker:
1

Clone and Install

git clone https://github.com/SnailyCAD/snaily-cadv4.git
cd snaily-cadv4
pnpm install
2

Set Up PostgreSQL

Ensure PostgreSQL is installed and running. Create a database:
CREATE DATABASE "snaily-cad-v4";
3

Configure Environment

Copy .env.example to .env and configure:
DB_HOST="localhost"
DB_PORT="5432"
POSTGRES_PASSWORD="your-password"
POSTGRES_USER="postgres"
POSTGRES_DB="snaily-cad-v4"

JWT_SECRET="your-random-secret"
ENCRYPTION_TOKEN="your-32-character-token"

CORS_ORIGIN_URL="http://localhost:3000"
NEXT_PUBLIC_CLIENT_URL="http://localhost:3000"
NEXT_PUBLIC_PROD_ORIGIN="http://localhost:8080/v1"

PORT_API=8080
PORT_CLIENT=3000
NODE_ENV="production"
4

Build the Project

pnpm run build
This compiles all packages and applications.
5

Start SnailyCAD

pnpm run start
Or use the full start script to update and build:
pnpm run full-start

​
Environment Variables Reference

Key environment variables you must configure:

​
Database Configuration

VariableDescriptionExample
POSTGRES_PASSWORDDatabase passwordmySecurePassword123
POSTGRES_USERDatabase usernamepostgres
POSTGRES_DBDatabase namesnaily-cad-v4
DB_HOSTDatabase hostlocalhost or postgres (Docker)
DB_PORTDatabase port5432

​
Security Tokens

VariableDescriptionExample
JWT_SECRETRandom secret for JWT tokensmy-super-secret-key-123
ENCRYPTION_TOKEN32-character encryption keyGeu2WGypP7irbwa3tCeeKS6YiyluFLep
Never share or commit your JWT_SECRET or ENCRYPTION_TOKEN to version control. Keep these secure!

​
Application URLs

VariableDescriptionExample
CORS_ORIGIN_URLClient URL for CORShttp://192.168.1.100:3000
NEXT_PUBLIC_CLIENT_URLPublic client URLhttp://192.168.1.100:3000
NEXT_PUBLIC_PROD_ORIGINAPI URLhttp://192.168.1.100:8080/v1

​
Optional Configuration

VariableDescriptionDefault
PORT_APIAPI server port8080
PORT_CLIENTClient server port3000
DOMAINDomain (for SSL)(empty)
SECURE_COOKIES_FOR_IFRAMEEnable secure cookiesfalse
For a complete environment variables reference, see the Environment Variables Configuration page.

​
Post-Installation Steps

1

Create Admin Account

Navigate to http://your-ip:3000 and register the first account. This account will automatically have owner permissions.
2

Configure CAD Settings

Go to Admin → Manage → CAD Settings to:
  • Set your CAD name
  • Configure enabled features
  • Set up registration requirements
  • Configure authentication options
3

Create Values

Set up basic values in Admin → Manage → Values:
  • Departments (Police, Sheriff, Fire, EMS)
  • Vehicle types and models
  • Penal codes
  • License types
4

Set Up Users

Configure user management:
  • Enable/disable public registration
  • Set up custom roles
  • Configure permissions

​
Development Installation

For local development with hot-reload: 
# Start development servers with Docker for database
pnpm run dev
This command:
  • Starts PostgreSQL in Docker
  • Runs all packages and apps in watch mode
  • Enables hot-reload for development
Development mode runs on parallel processes and watches for file changes automatically.

​
Verification

Verify your installation is working:
Visit http://your-ip:8080/v1 - you should see API version info
Visit http://your-ip:3000 - you should see the login page
If using Docker:
docker compose -f production.docker-compose.yml logs postgres
Look for “database system is ready to accept connections”
If using Docker:
docker compose -f production.docker-compose.yml logs snailycad-client
docker compose -f production.docker-compose.yml logs snailycad-api

​
Common Issues

Make sure PostgreSQL is running and accessible:
  • Check DB_HOST and DB_PORT are correct
  • Verify PostgreSQL is accepting connections
  • Check firewall rules
Change the ports in .env:
PORT_API=8081
PORT_CLIENT=3001
Remember to update NEXT_PUBLIC_PROD_ORIGIN to match the new API port.
Ensure your ENCRYPTION_TOKEN is exactly 32 characters long. Generate a new one at CodeBeautify.
Reset the database (WARNING: deletes all data):
pnpm --filter @snailycad/api prisma migrate reset

​
Next Steps

Configure Environment Variables

Learn about all available configuration options

Set Up Integrations

Connect Discord, FiveM, and other services

User Guides

Learn how to use each module

Reverse Proxy Setup

Set up SSL with Nginx or Apache

​
Getting Help

If you encounter issues during installation:
For production deployments, we strongly recommend using a reverse proxy (Nginx/Apache) with SSL certificates for security.

Build docs developers (and LLMs) love

Get started for freeTalk to us