Get started

Installation and upgrade

Install FengSui on Synology, other Docker hosts, or directly with Node.js, and how to upgrade, stop, and uninstall.

FengSui runs as a single container, published on GitHub Container Registry (ghcr.io/cky008/cpe-dash), supporting amd64 and arm64. Choose the method that fits your setup.

#Synology Container Manager

Applies to DSM 7.2 and above.

1. Prepare the directory. Create docker/cpe-dash/data in File Station, or log in to the NAS via SSH:

   mkdir -p /volume1/docker/cpe-dash/data && cd /volume1/docker/cpe-dash
   curl -fsSLO https://raw.githubusercontent.com/cky008/cpe-dash/main/docker-compose.yml
   curl -fsSL -o .env https://raw.githubusercontent.com/cky008/cpe-dash/main/.env.example
   chmod 600 .env && chmod 700 data
   id -u && id -g      # For example 1026 and 100; fill these into PUID / PGID in .env

2. Edit .env: Fill in DATA_ENCRYPTION_KEY (a random string generated with openssl rand -hex 32), TZ (such as Asia/Shanghai), and PUID / PGID. You will configure router and console passwords later in the web interface.
3. Create the project: Open "Container Manager → Project → Create", select /volume1/docker/cpe-dash as the path, choose "Use existing docker-compose.yml" as the source, and start the project.
4. Find the setup code: Once the container status changes to "Healthy", look for setup code in "Container → cpe-dash → Log", then follow step 4 of Quick start to complete setup.

#Other Docker hosts

Linux, macOS (Docker Desktop or OrbStack), and Windows are all supported. The steps are the same as Quick start:

docker compose pull
docker compose up -d

Common commands:

docker compose logs -f cpe-dash    # View logs
docker compose restart cpe-dash    # Restart
docker compose down                # Stop: logs out of the router, saves data, exits within 10 seconds

#Run directly with Node.js

Suitable for anyone who wants to inspect the source code or contribute. Requires Node.js 22.6 or later.

git clone https://github.com/cky008/cpe-dash.git && cd cpe-dash
npm ci
cp .env.example .env && chmod 600 .env    # Fill in DATA_ENCRYPTION_KEY
npm run build
npm start                                  # http://<local IP>:18384

If you do not want to connect to a real router and only want to inspect the interface, run npm run demo: it simulates a router in the same process, does not read .env, requires no internet access, and opens http://127.0.0.1:18484 with the login password fengsui-demo.

#Upgrade

Back up before upgrading (see Backup and restore), then pull the new image and recreate the container:

docker compose pull
docker compose up -d

In the Synology web UI: "Project → cpe-dash → Action → Build", or stop and start the project.

Changes and manual steps for each release are documented under "Before you upgrade" in GitHub Releases. Review them before upgrading.

#Uninstall

docker compose down
rm -rf ~/cpe-dash     # Deletes all data in data/; make sure you no longer need it first

FengSui leaves nothing on the router. If you configured band locking, Wi-Fi blocklists, or internet access schedules, remove them in the console before uninstalling, or revert them later in the router's own web page.

#Ports and networking

The default Docker network (bridge) is sufficient. Change compose to network_mode: host only if you need FengSui instances on multiple machines to discover each other, at the cost of losing container network isolation. What each entry in docker-compose.yml does, and common changes, are in Docker Compose file.

Edit this page on GitHub