Skip to content

Deployment overview ​

This page covers the components of the Gonggong Space server side, the ports each one uses, the recommended minimal deployment topology, and the software the server needs.

Components ​

ComponentDescription
serverapps/server, Node.js (Fastify). Provides the /api endpoints, WebSockets for browsers and daemons, attachment storage, the preview entry point, and client downloads. It does not serve the web app's static files
webapps/web, a React single-page app. vite build produces plain static files in apps/web/dist/, hosted by Nginx or another web server
PostgreSQLThe only database. The schema is migrated automatically when the server starts
Data directoryGONGGONG_DATA_DIR: encrypted attachments, managed artifacts, avatars, force-synced files, base-branch mirrors, client installers, the LiveKit binary, and so on
LiveKit (optional)Media server for 「实时画面」 (live view) previews. By default the server starts a local livekit-server child process the first time it's needed; you can also point it at an external LiveKit
daemonRuns on members' machines, not on the server. See Command line gg and Desktop app

The server is designed as a single instance: browser real-time pushes, daemon connections, and preview tunnels all live in process memory. Don't run multiple server instances behind a load balancer.

Ports ​

PortListenerAccessed byNotes
443 (plus redirect from 80)NginxBrowsers, daemonsThe only public entry point
8787serverNginxListens on 127.0.0.1 only by default; change with HOST / PORT
5432PostgreSQLserverDefault port for a self-managed database; the development pnpm db:up uses 54329
41000–41099serverBrowsersUsed only by the preview "port mode"; each open preview takes one port. Wildcard-domain mode doesn't use them. See Reverse proxy and preview domains
7881/TCP, 7882/UDPlivekit-serverBrowsers, daemonsNeeded only for live view; must be directly reachable by browsers and members' machines (not through Nginx)

Minimal deployment topology ​

A single server can run every server-side component:

text
                   ┌──────────────────────── 服务器 ────────────────────────┐
 浏览器 ─┐          │                                                        │
         │  HTTPS   │  Nginx :443                                            │
         ├────────→ │   ├─ /                → apps/web/dist(静态文件)       │
 成员机器 │  WSS     │   ├─ /api /ws /livekit /downloads → server 127.0.0.1:8787 │
 daemon ─┘          │   └─ *.预览域名       → server(按 Host 分流到预览)   │
                    │                                                        │
                    │  server ──→ PostgreSQL                                 │
                    │     └────→ 数据目录 GONGGONG_DATA_DIR                   │
                    └────────────────────────────────────────────────────────┘

(Diagram labels: 服务器 = server, 浏览器 = browser, 成员机器 = member machine, 静态文件 = static files, 预览域名 = preview domain, 按 Host 分流到预览 = routed to previews by Host, 数据目录 = data directory.)

  • Nginx handles HTTPS, hosts the web app's static files, and reverse-proxies /api, /ws, /livekit, and /downloads to the server.
  • The daemon on members' machines connects to the server through the same domain: /api/daemon/*, /ws/daemon (main connection), /ws/daemon/tunnel (preview tunnel), and /downloads/* (installation and auto-upgrade).
  • When members' machines and the server are not the same machine, the daemon can connect only over https:// and verifies the certificate. See HTTPS and certificates.
  • Configure a separate wildcard preview domain only when people outside the team need to open web previews built by Bots.

For the actual configuration, see Reverse proxy and preview domains.

Trying it out on a LAN

For a LAN-only trial you can skip Nginx: start with pnpm dev:server + pnpm dev:web, and the web dev server proxies /api, /ws, and /livekit to the server. The daemon only allows http:// for a server on the same machine; for other members' machines to connect, you must set up a self-signed certificate and bind with its fingerprint. See HTTPS and certificates. You can also use the Docker deployment.

Software requirements ​

SoftwareRequirement
Operating systemLinux or macOS
Node.js24 or later
pnpmEnable it with corepack enable; the version is pinned by the root package.json
PostgreSQL17 recommended
gitThe server uses it to maintain base-branch mirrors of group repositories (@ file suggestions and file search), so it needs access to the group repositories. See Deploy from source
NginxOr any other web server that can reverse-proxy WebSockets
opensslNeeded to generate a self-signed certificate
livekit-serverOptional. On Linux and Windows (x86_64 / arm64) the server automatically downloads and verifies the official release from GitHub; you can also install it yourself and point to it with GONGGONG_LIVEKIT_BIN

The server doesn't need Claude Code, Codex, or Rust. Those are needed only on members' machines (or on the machine that builds the clients).

Disk encryption

Attachments, diffs, and run details are stored encrypted in the database or on disk, but the base-branch mirrors (mirrors/ under the data directory) are plaintext git repositories. In production, enable disk encryption on the server (such as LUKS). See Security model.

Next steps ​

  1. Deploy from source
  2. Environment variables
  3. HTTPS and certificates
  4. Reverse proxy and preview domains
  5. Backup and restore

Released under the Apache License 2.0