Chap Install Guide

Install and production setup for chap-server + chap-node, with reverse proxy (ProxyDNSCache recommended)

Installation

This guide covers how to get chap-server and chap-node running with modern styles. ProxyDNSCache is strongly recommended for reverse proxy and wildcard subdomain TLS. You'll need Docker + Compose, open ports, and root/sudo for certs.

Prerequisites

Docker + Compose

Docker and Docker Compose (API ≥ 1.53) on server and nodes.

No auto updates

No version control: check the repo for updates manually.

SSL & Proxy

If using SSL/domain, a reverse proxy is required. ProxyDNSCache is built for Chap.

Privileges

Root/sudo access ideal (tested with it).

Ports

Server: two open ports. Node: one open port.

Reverse Proxy (ProxyDNSCache recommended)

Best to set up ProxyDNSCache first, on both server and nodes.
Needs ports 80, 443, and 441 open.
If you're running nginx/apache, move those off 80/443 and reverse proxy through ProxyDNSCache.

If your domain's on Cloudflare, the guide uses its API to automate wildcard TLS.

ProxyDNSCache: Wildcard Cert with Certbot + Cloudflare

Wildcard allows you to add subdomains just by DNS.
Follow on both server and nodes. Needs sudo.

Remove old certbot

sudo apt-get remove certbot
sudo apt autoremove

Install dependencies

sudo apt update
sudo apt install python3 python3-dev python3-venv libaugeas-dev gcc

Create venv & install pip/certbot

sudo python3 -m venv /opt/certbot/
sudo /opt/certbot/bin/pip install --upgrade pip
sudo /opt/certbot/bin/pip install certbot
sudo ln -s /opt/certbot/bin/certbot /usr/local/bin/certbot

Auto renew

echo "0 0,12 * * * root /opt/certbot/bin/python -c 'import random; import time; time.sleep(random.random() * 3600)' && sudo certbot renew -q" | sudo tee -a /etc/crontab > /dev/null

Cloudflare Plugin

source /opt/certbot/bin/activate
pip install certbot-dns-cloudflare
deactivate

Create cloudflare.ini:

dns_cloudflare_api_token = KEY HERE
Set permissions (& path): 
sudo chmod 600 /path/to/cloudflare.ini

Generate wildcard cert

sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /path/to/cloudflare.ini --preferred-challenges dns -d domain.com -d '*.domain.com'

ProxyDNSCache: systemd Service

Create service file

sudo nano /etc/systemd/system/ProxyDNSCache.service

Contents (fix ExecStart/paths):

[Unit]
Description=ProxyDNSCache
After=network.target

[Service]
WorkingDirectory=/home/ProxyDNSCache
ExecStart=/home/ProxyDNSCache/ProxyDNSCache-linux
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Non-root: allow privileged port bind 

sudo setcap 'cap_net_bind_service=+ep' /home/ProxyDNSCache/ProxyDNSCache-linux

Enable / Start

sudo systemctl daemon-reload
sudo systemctl enable --now ProxyDNSCache
sudo journalctl -u ProxyDNSCache -f

ProxyDNSCache: config.yml

certs:
    - "example.com":
            - cert: "/etc/letsencrypt/live/example.com/fullchain.pem"
                key: "/etc/letsencrypt/live/example.com/privkey.pem"
    - "*.example.com":
            - cert: "/etc/letsencrypt/live/example.com/fullchain.pem"
                key: "/etc/letsencrypt/live/example.com/privkey.pem"

DNS Records (ProxyDNSCache Routing)

A Records

For main panel, websocket, and each node.

SRV Records

Each points _pdcache._tcp.[domain] to the right target + port.

# Main panel domain
_pdcache._tcp.chap.example.com SRV 0 0 8080 localhost.

# Server websocket
_pdcache._tcp.chap-ws.example.com SRV 0 0 8081 localhost.

# Each node
_pdcache._tcp.chap-node-1.example.com SRV 0 0 6002 localhost.

Installing Chap Server

Clone & setup

cd ~/
git clone https://github.com/MJDaws0n/chap.git
mv chap chap-server
cd chap-server
cp .env.example .env
nano .env

APP_URL

Reverse proxy URL

APP_SECRET

Secure random string (don't share)

APP_PORT

Main panel port (matches proxy)

WS_PORT

Websocket port (matches proxy)

DB_PASSWORD

Secure random

DB_ROOT_PASSWORD

Secure random

CAPTCHA_PROVIDER

none/recaptcha/autogate

Build & Start

docker compose -f docker-compose.server.yml up --build
docker compose -f docker-compose.server.yml up -d
Default: admin@chap.dev / password
Change these right after logging in.

Installing Chap Node

Check Docker version

docker version

Must be ≥ 1.53 (see "API version" in Docker Engine section).

Add node in panel

  1. Go to Nodes > Add Node
  2. Set port range
  3. Note NODE_ID and NODE_TOKEN

Clone & setup node

cd ~/
git clone https://github.com/MJDaws0n/chap.git
mv chap chap-node
cd chap-node
cp node/.env.example .env
nano .env

NODE_ID

From dashboard

NODE_TOKEN

From dashboard

CHAP_SERVER_URL

Websocket SRV domain (e.g. chap-ws.example.com)

BROWSER_WS_PORT

Proxy-set logs socket port

Build & Start

docker compose -f docker-compose.node.yml up --build
docker compose -f docker-compose.node.yml up -d
Node should show online in Chap panel.

Updating

Node update

git clone https://github.com/MJDaws0n/chap.git ~/temp && rsync -a --exclude='.env' ~/temp/ ~/chap-node/ && rm -rf ~/temp

cd ~/chap-node/
docker compose -f docker-compose.node.yml up --build
# Then:
docker compose -f docker-compose.node.yml up -d

Server update

git clone https://github.com/MJDaws0n/chap.git ~/temp && rsync -a --exclude='.env' ~/temp/ ~/chap-server/ && rm -rf ~/temp

cd ~/chap-server/
docker compose -f docker-compose.server.yml up --build
# Then:
docker compose -f docker-compose.server.yml up -d
© MJDawson - Chap