GudDesk
Education

Self-Hosting GudDesk: A Complete Guide

Everything you need to know about running GudDesk on your own infrastructure with Node.js and PostgreSQL.

Self-Hosting GudDesk: A Complete Guide

One of GudDesk's core principles is that you should own your data. Self-hosting makes that a reality. This guide walks you through everything you need to run GudDesk on your own infrastructure.

Prerequisites

Before you start, you'll need:

  • Node.js 20.19 or later and pnpm
  • PostgreSQL 15+, on your own server or a managed service such as Neon, Supabase or AWS RDS
  • A domain name (for the chat widget and dashboard)
  • A Resend API key for transactional emails

The recommended path is Docker Compose in the gudlab/guddesk-core repo: copy .env.example to .env and run docker compose up --build. That builds the app image locally (there is no pre-built image on a registry) and starts Postgres 16. You can also run from source with Node.js and PostgreSQL, as below.

Install and Run

# Clone the repository
git clone https://github.com/gudlab/guddesk-core.git
cd guddesk-core
 
# Install dependencies (this also generates the Prisma client)
pnpm install
 
# Copy the environment template
cp .env.example .env
 
# Edit .env with your configuration
# At minimum, set DATABASE_URL, AUTH_SECRET, NEXT_PUBLIC_APP_URL,
# RESEND_API_KEY, GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
 
# Create the database tables
pnpm prisma db push
 
# Build the app (this also builds the chat widget)
pnpm build
 
# Start the production server
pnpm start

GudDesk is now running at http://localhost:3000, using the PostgreSQL database in DATABASE_URL.

Environment Variables

Here are the key environment variables you'll need to configure:

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string
AUTH_SECRETYesRandom secret for session encryption
RESEND_API_KEYYesFor transactional emails
NEXT_PUBLIC_APP_URLYesYour public-facing URL
GOOGLE_CLIENT_IDYesFor Google OAuth sign-in
GOOGLE_CLIENT_SECRETYesFor Google OAuth sign-in
PUSHER_APP_IDNoPusher app ID, for live updates
PUSHER_SECRETNoPusher secret, for live updates
NEXT_PUBLIC_PUSHER_KEYNoPusher key, for live updates
NEXT_PUBLIC_PUSHER_CLUSTERNoPusher cluster, for live updates
ANTHROPIC_API_KEYNoFor AI agent features

The four Pusher variables are optional. Without them the inbox and the chat widget fall back to polling: the conversation list refreshes every 10 seconds, and the open thread and the widget every 4 seconds. Typing indicators and agent presence need Pusher. NEXT_PUBLIC_ values are built into the browser code, so run pnpm build again after you set or change them.

Keeping It Running

We recommend using a process manager like PM2 to keep GudDesk running:

pm2 start pnpm --name guddesk -- start

Setting Up the Chat Widget

Once your instance is running, embed the chat widget on your site:

<script>
  window.GudDeskSettings = {
    appId: "gd_pub_xxxxxxxxxxxxxxxx",
    baseUrl: "https://your-guddesk-domain.com",
  };
</script>
<script src="https://your-guddesk-domain.com/widget.js" async></script>

You can find your App ID (prefixed gd_pub_) in the dashboard under Settings > Widget. This value is safe to include in client-side code. It only identifies your workspace.

Database Backups

Since you own the database, you're responsible for backups. We recommend:

# Daily automated backup
pg_dump $DATABASE_URL > backup-$(date +%Y%m%d).sql

Set this up as a cron job or use your cloud provider's managed backup service.

Updating

To update your self-hosted instance:

# Pull the latest changes
git pull origin main
 
# Install any new dependencies
pnpm install
 
# Run migrations
pnpm prisma db push
 
# Rebuild and restart
pnpm build
pm2 restart guddesk

Reverse Proxy Setup

For production, put GudDesk behind a reverse proxy like Nginx or Caddy:

server {
    listen 443 ssl;
    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;
    }
}

Need Help?

If you run into issues:

  • Check the documentation for detailed configuration guides
  • Open an issue on GitHub
  • Join the community discussions

Self-hosting gives you complete control over your customer data and infrastructure. It's a bit more work upfront, but the peace of mind is worth it.