Docs
Self-Hosting

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.

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 --build

This 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 start

pnpm 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 startup

Reverse 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:

VariableDescription
DATABASE_URLPostgreSQL connection string
AUTH_SECRETSession encryption secret (generate with openssl rand -base64 32)
NEXT_PUBLIC_APP_URLYour public URL (e.g., https://support.yourdomain.com)
RESEND_API_KEYEmail delivery API key
RESEND_FROMSet 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_SECRETNeeded 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_KEYRequired for AI agent features
PUSHER_APP_IDOptional. Pusher app ID (server only)
PUSHER_SECRETOptional. Pusher secret (server only, keep it private)
NEXT_PUBLIC_PUSHER_KEYOptional. Pusher key, used by the dashboard and the widget
NEXT_PUBLIC_PUSHER_CLUSTEROptional. Pusher cluster, for example eu or us2
CRON_SECRETBearer token for the /api/cron routes (see Scheduled jobs). Without it every cron route returns 401
AUTOMATIONS_ENABLEDRun 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.

RouteWhat it doesSuggested schedule
/api/cron/sla-checkAdds a note to conversations past their SLA deadline and emails the assigneeEvery 5 minutes
/api/cron/automationsUnassigned-for rules. Skips unless AUTOMATIONS_ENABLED is true or 1Every 5 minutes
/api/cron/webhook-retryRetries failed webhook deliveries that are dueEvery 5 minutes
/api/cron/surveysSends delayed CSAT survey messagesEvery 10 minutes
/api/cron/analyticsStores the daily analytics snapshotDaily
/api/cron/agent-performanceStores yesterday's per-agent numbersDaily
/api/cron/webhook-cleanupDeletes webhook delivery records older than 30 daysDaily

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-check

To 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.sql

Set 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 guddesk

Always review the changelog before updating to check for breaking changes or required migration steps.

System Requirements

ResourceMinimumRecommended
CPU1 vCPU2+ vCPU
RAM1 GB2+ GB
Storage10 GB20+ GB
PostgreSQL15+16+
Node.js20+22 LTS