Technical Setup
This module is for the person who installs, configures, and maintains ZippCRM. It covers Docker deployment (recommended), environment variables, database management, and common operational tasks.
Docker Installation (Recommended)
Prerequisites
Install Docker Desktop (Mac/Windows) or Docker Engine + Compose plugin (Linux). Verify: docker --version and docker compose version.
Copy the ZippCRM deployment package
Place the docker-compose.yml and .env.example files in a clean folder, e.g., /opt/zippcrm/.
Create your .env file
cp .env.example .env — then edit .env with a text editor. Fill in DATABASE_URL, ZIPPCRM_LICENSE_KEY, PORTAL_URL, and SMTP settings.
Start the stack
docker compose up -d — this starts postgres, backend, and frontend containers. First start takes 2–5 minutes as the database is seeded.
Verify it's running
Open http://localhost:3002 in your browser. You should see the ZippCRM login page. API health: http://localhost:8088/health
Log in as admin
Default credentials: admin@zippcrm.local / password from your .env ADMIN_PASSWORD variable.
Critical Environment Variables
| Variable | Required | Description |
|---|---|---|
DATABASE_URL | Yes | Full PostgreSQL connection string. Format: postgresql://user:pass@host:port/dbname |
ZIPPCRM_LICENSE_KEY | Yes | Your Enterprise license key. Must match in both .env and docker-compose.yml |
PORTAL_URL | Yes | The public URL clients use to reach the portal. Sets CORS headers and email links |
JWT_SECRET | Yes | Random 64-char string for JWT signing. Generate: openssl rand -hex 32 |
SMTP_HOST / _PORT / _USERNAME / _PASSWORD | For email | Transactional email configuration. Without this, no emails are sent to clients |
SCHEDULER_ENABLED | Multi-pod only | Set true on exactly one instance. Leave unset (defaults to true) for single-server Docker |
ANTHROPIC_API_KEY | For AI Copilot | Enables Claude-based AI Copilot features in the UI |
S3_ENDPOINT / _BUCKET / _ACCESS_KEY / _SECRET_KEY | Multi-pod only | Object storage for documents when running multiple backend replicas |
Database Management
Backups
Manual backup
docker exec zippcrm-postgres pg_dump -U zippcrm zippcrm > backup_$(date +%Y%m%d).sql
Restore from backup
docker exec -i zippcrm-postgres psql -U zippcrm zippcrm < backup_20260428.sql
Automated backups
Add a cron job: 0 2 * * * docker exec zippcrm-postgres pg_dump -U zippcrm zippcrm > /backups/zippcrm_$(date +\%Y\%m\%d).sql
Upgrading ZippCRM
Pull the new image
docker compose pull
Restart with new image
docker compose up -d --build — the backend runs database migrations automatically on startup
Verify after upgrade
Check http://localhost:8088/health and log in. If the backend fails to start, check docker compose logs backend for migration errors
Common Operational Tasks
| Task | Command / Location |
|---|---|
| View backend logs | docker compose logs -f backend |
| Restart backend only | docker compose restart backend |
| Check scheduler status | Admin → System → Scheduler, or docker compose logs backend | grep scheduler |
| Reset admin password | docker exec -it zippcrm-postgres psql -U zippcrm -c "UPDATE users SET password_hash = ... WHERE email='admin@zippcrm.local';" — contact Zippcoin support for the hash utility |
| Check disk usage | docker system df and du -sh /var/lib/docker/volumes/zippcrm_pgdata |
| Full stack restart | docker compose down && docker compose up -d |
SSL / HTTPS Setup
For production, always use HTTPS. The recommended approach is to put a reverse proxy (nginx or Caddy) in front of ZippCRM and terminate TLS there.
Install Caddy (easiest option)
apt install caddy on Ubuntu. Caddy auto-provisions Let's Encrypt certificates.
Create /etc/caddy/Caddyfile
Add: zippcrm.yourfirm.com { reverse_proxy localhost:3002 }
Restart Caddy
systemctl restart caddy — certificate is provisioned automatically within 60 seconds.
Update PORTAL_URL in .env
Change to https://zippcrm.yourfirm.com and restart: docker compose restart backend