Manage

Docker Compose file

The example docker-compose.yml in full, what each line does, what you can change and how, and how it works with .env.

FengSui runs as a Docker Compose project. The docker-compose.yml in the repository is the recommended setup; Quick start and Installation and upgrade download it, and most people never change it. This page explains it line by line. FengSui's own settings (the encryption key, SMS, notifications and so on) live in .env; see Configuration reference.

#The example file

This is the whole file, as it is in the repository:

# 烽燧 FengSui (cpe-dash) — Synology DS923+ / any Docker host, also `container-compose` on macOS.
#
#   mkdir -p data && cp .env.example .env    # then set DATA_ENCRYPTION_KEY and TZ
#   docker compose up -d                       # Web console: http://<nas-ip>:18384
#
# Every line is explained in the guide: https://fengsui.iocky.com/en/docs/docker-compose/
#
# Run exactly ONE daemon per router: it owns the router's single admin slot and the Telegram bot
# token. Stop any other cpe-dash / cpe-sms instance (NAS or laptop) before starting this one.

services:
  cpe-dash:
    image: ghcr.io/cky008/cpe-dash:latest
    build: .
    container_name: cpe-dash
    restart: unless-stopped
    init: true
    # Unprivileged user; set PUID/PGID to the owner of ./data and ./.env (`id -u` / `id -g` on the NAS)
    user: "${PUID:-1000}:${PGID:-1000}"
    environment:
      # Container networking: listen on every interface of the container, store state in the volume.
      # Everything else (encryption key, SMS / Telegram / alert settings) comes from the mounted .env;
      # the router connection, the console password and the tokens are set in the console.
      - TZ=${TZ:-UTC}
      - WEB_HOST=0.0.0.0
      - WEB_PORT=18384
      - STATE_FILE=/app/data/state.json
    # After editing .env: `docker compose up -d --force-recreate` (`restart` may keep the old file)
    volumes:
      - ./data:/app/data
      - ./.env:/app/.env:ro
    ports:
      - "${WEB_PORT:-18384}:18384"
    # The cross-host duplicate-daemon guard (PEER_DISCOVERY_ENABLED=true, UDP 18385 broadcast beacons,
    # off by default) needs the host network: Docker's bridge does not forward LAN broadcasts. To use
    # it, uncomment the next line and remove `ports:` above (the console is then served on port 18384
    # of the host: WEB_PORT under `environment:`, not the one in .env).
    # network_mode: host
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    # Bounds for a runaway process, far above normal use, so it cannot starve the NAS
    mem_limit: 1g
    # Synology DSM kernels have no pids cgroup, so Docker would drop this with a warning on every
    # start; on other Linux hosts, uncomment it as a second bound
    # pids_limit: 256
    # SIGTERM → queued requests 503, in-flight CPE session logs out, encrypted stores flush (< 10 s)
    stop_grace_period: 15s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

#How it works with .env

The .env next to docker-compose.yml is used twice:

1. Compose fills in variables from it. When it starts the project, Compose reads the .env in the project directory and substitutes the ${…} in the file [Docker: Set, use, and manage variables in a Compose file with interpolation]. The file uses four: TZ, WEB_PORT, PUID and PGID. ${TZ:-UTC} means: the TZ from .env if it has a value, otherwise UTC.
2. FengSui reads its settings from it. The same file is mounted read-only into the container as /app/.env, and FengSui reads it at startup.

The entries under environment: reach the container as environment variables. When a setting is in both .env and the environment, FengSui uses the environment. So WEB_HOST, WEB_PORT and STATE_FILE in .env have no effect inside the container; the WEB_PORT in .env only sets the port on the host (see ports below).

#Line by line

#Image and container

#Environment variables (environment)

#Data and settings file (volumes)

#Ports and network

#Security limits

These entries give the container only what FengSui needs to run. FengSui needs none of them relaxed.

#Resources, stopping and logs

#Applying changes

• You changed docker-compose.yml, or TZ, WEB_PORT, PUID or PGID in .env: run docker compose up -d. Compose sees the changed configuration and recreates the container; data/ is kept [Docker: docker compose up].
• You changed only other settings in .env: run docker compose up -d --force-recreate. The Compose configuration is the same, so a plain up -d does not recreate the container, and docker compose restart keeps the old mount: if your editor saved .env by replacing it with a new file, the container still sees the old one [moby/moby#15793: File mount does not update with changes from host].

docker compose up -d --force-recreate

On Synology, run it the same way over SSH in the project directory.

#Common changes

#Use another port

Set WEB_PORT in .env to the port you want (for example 8443) and run docker compose up -d. The console is then at http://<NAS IP>:8443.

#Allow access from this machine only

With a reverse proxy providing HTTPS on the same host, you can open the port on the host itself only:

    ports:
      - "127.0.0.1:${WEB_PORT:-18384}:18384"

FengSui then sees requests coming from the Docker network's gateway, not from 127.0.0.1. Set ALLOWED_HOSTS as in Access behind a reverse proxy and put the gateway address in TRUSTED_PROXIES. To find it (the network is named after the project directory, plus _default):

docker network inspect cpe-dash_default --format '{{(index .IPAM.Config 0).Gateway}}'

#Pin a version

    image: ghcr.io/cky008/cpe-dash:1.7.1

To upgrade, change the version and run docker compose pull && docker compose up -d.

#Build from source

git clone https://github.com/cky008/cpe-dash.git && cd cpe-dash
cp .env.example .env && chmod 600 .env    # set DATA_ENCRYPTION_KEY and TZ
mkdir -p data && chmod 700 data
docker compose up -d --build

--build builds the image from the source in the directory instead of pulling it.

#Use host networking

When you need PEER_DISCOVERY_ENABLED: uncomment the network_mode: host line, delete ports: and the line under it, and run docker compose up -d. The console is on port 18384 of the host; to change it, change WEB_PORT=18384 under environment:. With host networking the container shares the host's network, so you lose a layer of isolation.

#Limit processes on Linux other than Synology

Uncomment # pids_limit: 256 and run docker compose up -d.

Edit this page on GitHub