Skip to main content
This guide covers installing SnailyCAD directly on your server without Docker. This method gives you more control but requires manual dependency management.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js version 18.16.0 or higher (20.x recommended)
  • pnpm version 9.0.4 or higher
  • PostgreSQL version 14 or higher
  • Git
  • At least 4GB of RAM
  • At least 10GB of free disk space

​
Installation

1

Install Node.js

Install Node.js 20.x using your package manager:Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
RHEL/CentOS/Fedora:
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
Verify installation:
node --version  # Should show v20.x.x
2

Install pnpm

Install pnpm globally:
npm install -g pnpm
Verify installation:
pnpm --version  # Should show 9.0.4 or higher
3

Install PostgreSQL

Install and configure PostgreSQL:Ubuntu/Debian:
sudo apt-get update
sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
Create a database and user:
sudo -u postgres psql
In the PostgreSQL prompt:
CREATE DATABASE "snaily-cad-v4";
CREATE USER snailycad WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE "snaily-cad-v4" TO snailycad;
\q
4

Clone the repository

Clone the SnailyCAD repository:
git clone https://github.com/SnailyCAD/snaily-cadv4.git
cd snaily-cadv4
5

Configure environment variables

Copy the example environment file:
cp .env.example .env
Edit the .env file and configure the following:
# Database credentials
POSTGRES_PASSWORD="your-secure-password"
POSTGRES_USER="snailycad"
POSTGRES_DB="snaily-cad-v4"

# Database connection (use 'localhost' for standalone)
DB_HOST="localhost"
DB_PORT="5432"

# Security tokens
JWT_SECRET="your-random-jwt-secret"
ENCRYPTION_TOKEN="your-32-character-encryption-token"

# URLs (update with your domain or IP)
CORS_ORIGIN_URL="http://your-domain.com:3000"
NEXT_PUBLIC_CLIENT_URL="http://your-domain.com:3000"
NEXT_PUBLIC_PROD_ORIGIN="http://your-domain.com:8080/v1"

# Ports
PORT_API=8080
PORT_CLIENT=3000

# Environment
NODE_ENV="production"

# Database URL
DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${DB_HOST}:${DB_PORT}/${POSTGRES_DB}?sslmode=prefer
For standalone installations, ensure DB_HOST="localhost" (not “postgres”).
6

Install dependencies

Install all project dependencies:
pnpm install --frozen-lockfile
This may take several minutes depending on your internet connection.
7

Build the application

Build all packages and applications:
pnpm run build
This will:
  • Generate the images domain configuration
  • Build all workspace packages
  • Build the API application
  • Build the Client application
The build process may take 10-15 minutes depending on your server’s resources.
8

Start the application

Start both the API and Client servers:
pnpm run start
This runs the start script which concurrently starts:
  • Client on port 3000 (or your configured PORT_CLIENT)
  • API on port 8080 (or your configured PORT_API)
The application will run in the foreground. Press Ctrl+C to stop it. See the Process Management section below for running it as a service.
9

Access SnailyCAD

Open your browser and navigate to:
  • Client: http://your-server-ip:3000
  • API: http://your-server-ip:8080/v1
Complete the initial setup wizard to create your admin account.

​
Process Management

For production deployments, you should run SnailyCAD as a background service using a process manager.

​
Using PM2

PM2 is a popular process manager for Node.js applications.

​
Install PM2

npm install -g pm2

​
Start with PM2

# Start the application
pm2 start pnpm --name "snailycad" -- start

# Save the PM2 process list
pm2 save

# Set PM2 to start on system boot
pm2 startup

​
Manage with PM2

# View status
pm2 status

# View logs
pm2 logs snailycad

# Restart
pm2 restart snailycad

# Stop
pm2 stop snailycad

# Remove from PM2
pm2 delete snailycad

​
Using systemd

Alternatively, create a systemd service: 
sudo nano /etc/systemd/system/snailycad.service
Add the following configuration: 
[Unit]
Description=SnailyCAD Service
After=network.target postgresql.service

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/snaily-cadv4
Environment="NODE_ENV=production"
ExecStart=/usr/bin/pnpm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
Enable and start the service: 
sudo systemctl daemon-reload
sudo systemctl enable snailycad
sudo systemctl start snailycad
Manage the service: 
# Check status
sudo systemctl status snailycad

# View logs
sudo journalctl -u snailycad -f

# Restart
sudo systemctl restart snailycad

# Stop
sudo systemctl stop snailycad

​
Updating SnailyCAD

To update to the latest version: 
# Stop the application
pm2 stop snailycad  # or: sudo systemctl stop snailycad

# Update the code
git stash
git pull

# Install dependencies and rebuild
pnpm install
pnpm run build

# Restart the application
pm2 restart snailycad  # or: sudo systemctl start snailycad
Alternatively, use the built-in update script: 
pm2 stop snailycad
pnpm run full-start
This script will:
  1. Stash local changes
  2. Pull latest updates
  3. Install dependencies
  4. Copy environment files
  5. Build the application
  6. Start the application

​
Database Management

​
Backup Database

pg_dump -U snailycad -h localhost snaily-cad-v4 > backup.sql

​
Restore Database

psql -U snailycad -h localhost snaily-cad-v4 < backup.sql

​
Connect to Database

psql -U snailycad -h localhost -d snaily-cad-v4

​
Troubleshooting

​
Port Already in Use

Check what’s using the port: 
sudo lsof -i :3000
sudo lsof -i :8080
Change ports in your .env file if needed.

​
Database Connection Failed

Verify PostgreSQL is running: 
sudo systemctl status postgresql
Test the connection: 
psql -U snailycad -h localhost -d snaily-cad-v4
Check PostgreSQL logs: 
sudo journalctl -u postgresql -f

​
Build Failures

Clear the build cache and try again: 
rm -rf node_modules
rm -rf apps/*/node_modules
rm -rf packages/*/node_modules
rm -rf apps/*/.next
pnpm install --frozen-lockfile
pnpm run build

​
Out of Memory

Increase Node.js memory limit: 
export NODE_OPTIONS="--max-old-space-size=4096"
pnpm run build

​
Next Steps

Reverse Proxy Setup

Configure nginx or Caddy for SSL and domain routing

Environment Variables

Complete environment variable reference

Build docs developers (and LLMs) love

Get started for freeTalk to us