Installation overview

All CCHP programs ship in one image, ghcr.io/cch-hq/cch-plus, and run by role: the control plane serves the console and the management API (default port 8080); the gateway is the data plane that LLM clients call (default port 8081); the worker (background jobs) handles outbox delivery, billing settlement, and scheduled tasks; and a one-time migration job runs the database migrations before each start or upgrade. Business data is stored in PostgreSQL 18 (with TimescaleDB), and runtime state is stored in Dragonfly (Redis protocol). The PgDog connection pool is optional. Docker Compose runs all roles in one container, while k3s / k8s and binary installation run each role as a separate workload or systemd service. All three methods lead to the same setup wizard after startup.

Choose an installation method#

Hardware requirements#

These figures are for one server (VPS) and apply to Docker Compose and binary installation. At the default caps, CCHP’s local data (request archives, staged billing data, temporary files, and so on) needs at least 26 GiB, and the rest of the disk is mainly for the PostgreSQL database. Importing data from CC Hub needs extra space. The PersistentVolumeClaims of a single k3s node total about 481 GiB, so give the node at least that much disk. See Install on k3s / k8s.

Every method also requires:

• A Linux server with an amd64 or arm64 CPU.
• A domain and HTTPS, if you open the console from another computer: the console’s public URL can only be an HTTPS URL or a loopback address.
• Access to ghcr.io (the CCHP image), cch-plus.com (the model price list), and the upstream LLM providers you plan to connect.

Frequently asked questions#

Can I open the console with the server IP and a port?#

Not by default. If you set the console’s public URL, CCH_PUBLIC_BASE_URL, to http:// plus the server IP, CCHP refuses to start. If you don’t have a domain, use SSH port forwarding to open http://localhost:8080 on your own computer. For production use, prepare domains for the console and the gateway and set up an HTTPS reverse proxy. To test on a LAN only, Reduced-security deployment (LAN testing) lets the console and the gateway run over plain http at a LAN address.

Do the three installation methods use the same programs?#

Yes. All three methods use the image ghcr.io/cch-hq/cch-plus: Docker Compose and k3s / k8s run the image directly, and binary installation extracts the program files from the image. The setup wizard and the console features are also the same.