Self-Hosting
Deploy GudDesk on your own infrastructure with Docker Compose, or from source with Node.js and PostgreSQL.
GudDesk is fully open source (AGPL-3.0) and designed to run on your own infrastructure. This guide covers deployment options for production environments.
Docker Compose (recommended)
The gudlab/guddesk-core repo ships a Dockerfile and a Compose file. There is no pre-built image on a registry; Compose builds the app image locally.
git clone https://github.com/gudlab/guddesk-core.git
cd guddesk-core
cp .env.example .env
# Set AUTH_SECRET (openssl rand -base64 32). Placeholders work for
# GOOGLE_* and RESEND_API_KEY if you only want the server to start.
docker compose up --buildThis starts Postgres 16, runs migrations, and serves the app at http://localhost:3000. Full env notes and pitfalls are in the core self-host guide. After you change NEXT_PUBLIC_APP_URL, rebuild with docker compose up --build.
Install from Source
You can also run from source on Node.js. You need:
- Node.js 20.19 or later, and pnpm
- A PostgreSQL 15+ database that you run yourself or rent (for example Neon, Supabase or AWS RDS)
git clone https://github.com/gudlab/guddesk-core.git
cd guddesk-core
pnpm install
cp .env.example .env
# Edit .env with your production configuration (see Environment Variables below)
# Create the database tables
pnpm prisma db push
# Build for production (this also builds the chat widget)
pnpm build
# Start the production server
pnpm startpnpm install also generates the Prisma client. The app listens on port 3000.
Production Checklist
For production, we recommend:
- Use a managed PostgreSQL database with backups turned on
- Put GudDesk behind a reverse proxy with TLS (Nginx, Caddy, or Traefik)
- Set the four Pusher variables if you want live updates (see Real-time updates). Without them the inbox and widget poll for new messages
Process Manager
Use a process manager like PM2 for reliability:
pm2 start pnpm --name guddesk -- start
pm2 save
pm2 startupReverse Proxy
Nginx
server {
listen 443 ssl http2;
server_name support.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}Caddy
support.yourdomain.com {
reverse_proxy localhost:3000
}
Caddy automatically provisions TLS certificates via Let's Encrypt.
Environment Variables
See the Quickstart guide for the full list of environment variables. Key production variables:
| Variable | Description |
|---|---|
DATABASE_URL | PostgreSQL connection string |
AUTH_SECRET | Session encryption secret (generate with openssl rand -base64 32) |
NEXT_PUBLIC_APP_URL | Your public URL (e.g., https://support.yourdomain.com) |
RESEND_API_KEY | Email delivery API key |
RESEND_FROM | Set this when you self-host. Sender for invites, password resets, sign-in links and notifications, for example GudDesk <support@yourdomain.com>. It must be on a domain you have verified in Resend, or Resend rejects every email |
RESEND_WEBHOOK_SECRET | Needed for inbound email. The signing secret (whsec_...) of your Resend webhook for the email.received event, pointed at https://<your-domain>/api/email/inbound. Without it, the route refuses every request and inbound email stays off. Inbound also needs RESEND_API_KEY to be a full-access key, not a sending-only one: the webhook only carries the email's id, and the app fetches the email with the key, so with a sending-only key every inbound email fails (500) |
ANTHROPIC_API_KEY | Required for AI agent features |
PUSHER_APP_ID | Optional. Pusher app ID (server only) |
PUSHER_SECRET | Optional. Pusher secret (server only, keep it private) |
NEXT_PUBLIC_PUSHER_KEY | Optional. Pusher key, used by the dashboard and the widget |
NEXT_PUBLIC_PUSHER_CLUSTER | Optional. Pusher cluster, for example eu or us2 |
CRON_SECRET | Bearer token for the /api/cron routes (see Scheduled jobs). Without it every cron route returns 401 |
AUTOMATIONS_ENABLED | Run saved automation rules. Off unless the value is exactly true or 1. Saving rules stays allowed either way. Leave unset to keep rules from running |
Real-time updates (optional)
The four Pusher variables are optional. Set all four to get live updates over WebSockets. Without them GudDesk falls back to polling:
- The inbox refreshes the conversation list every 10 seconds and the open thread every 4 seconds, while the browser tab is visible.
- The chat widget checks for new messages every 4 seconds while it's open.
Typing indicators and collision warnings need Pusher, so they stay off in polling mode.
Next.js builds NEXT_PUBLIC_ values into the browser code, so rebuild (pnpm build) and restart after you set or change NEXT_PUBLIC_PUSHER_KEY or NEXT_PUBLIC_PUSHER_CLUSTER. PUSHER_APP_ID and PUSHER_SECRET are read at runtime and only need a restart.
Scheduled jobs
Some work runs from cron routes under /api/cron. Nothing calls them on its own when you self-host, so schedule them yourself. Each route accepts GET or POST and needs the CRON_SECRET from your environment as a bearer token:
Authorization: Bearer <CRON_SECRET>
If CRON_SECRET is missing or empty, every cron route returns 401. Use a long random value, for example openssl rand -hex 32.
| Route | What it does | Suggested schedule |
|---|---|---|
/api/cron/sla-check | Adds a note to conversations past their SLA deadline and emails the assignee | Every 5 minutes |
/api/cron/automations | Unassigned-for rules. Skips unless AUTOMATIONS_ENABLED is true or 1 | Every 5 minutes |
/api/cron/webhook-retry | Retries failed webhook deliveries that are due | Every 5 minutes |
/api/cron/surveys | Sends delayed CSAT survey messages | Every 10 minutes |
/api/cron/analytics | Stores the daily analytics snapshot | Daily |
/api/cron/agent-performance | Stores yesterday's per-agent numbers | Daily |
/api/cron/webhook-cleanup | Deletes webhook delivery records older than 30 days | Daily |
Inbox and API requests also run the SLA check for their workspace at most every 5 minutes, so a busy workspace gets it even if a cron run is missed. When AUTOMATIONS_ENABLED is true or 1, they also run the unassigned-for rules. Keep the cron schedule anyway, because a quiet workspace has no requests to trigger it.
Test a route with curl:
curl -fsS --max-time 60 \
-H "Authorization: Bearer $CRON_SECRET" \
https://support.example.com/api/cron/sla-checkTo schedule them with system cron, keep the secret out of the crontab and the process list. Put it in a file only root can read:
# /etc/guddesk/cron-header (chmod 600)
Authorization: Bearer <CRON_SECRET>Then add /etc/cron.d/guddesk:
BASE=https://support.example.com
CURL="curl -fsS --max-time 60 --retry 3 --retry-delay 10 -o /dev/null -H @/etc/guddesk/cron-header"
*/5 * * * * root $CURL $BASE/api/cron/sla-check
*/5 * * * * root $CURL $BASE/api/cron/webhook-retry
*/5 * * * * root $CURL $BASE/api/cron/automations
*/10 * * * * root $CURL $BASE/api/cron/surveys
0 1 * * * root $CURL $BASE/api/cron/analytics
15 1 * * * root $CURL $BASE/api/cron/agent-performance
25 1 * * * root $CURL $BASE/api/cron/webhook-cleanup-H @file needs curl 7.55 or later. Any scheduler that can send an HTTP request with a header works the same way, for example a Kubernetes CronJob or GitHub Actions.
On Vercel, vercel.json schedules the cron routes once a day, because the Hobby plan allows only daily crons. It does not list /api/cron/automations. Where it is set up, .github/workflows/cron.yml calls /api/cron/sla-check and /api/cron/automations every hour. It needs a CRON_SECRET repository secret that matches the one on Vercel.
Backups
You own the database, so you're responsible for backups:
# Manual backup
pg_dump $DATABASE_URL > backup-$(date +%Y%m%d).sql
# Restore from backup
psql $DATABASE_URL < backup-20250615.sqlSet up automated daily backups via cron or your cloud provider's managed backup service.
Updating
git pull origin main
pnpm install
pnpm prisma db push
pnpm build
pm2 restart guddeskAlways review the changelog before updating to check for breaking changes or required migration steps.
System Requirements
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2+ vCPU |
| RAM | 1 GB | 2+ GB |
| Storage | 10 GB | 20+ GB |
| PostgreSQL | 15+ | 16+ |
| Node.js | 20+ | 22 LTS |