GoACS deployment

Everything needed to run GoACS - a TR-069 (CWMP) and TR-369 (USP) auto configuration server with its admin panel - on your own server with Docker, from the published images. There is no source code here.

These files are generated from the GoACS source repository for every release. Do not edit them in place: keep your settings in .env and your changes in a docker-compose.override.yml (see Customising), so an upgrade never conflicts with them.

Versions

What	Use it for	Images
Tags vX.Y.Z	Production. Each tag pins the files and the image version they belong to.	ghcr.io/goacs/goacs-go-*:vX.Y.Z
Branch main	Trying the newest development build.	ghcr.io/goacs/goacs-go-*:edge

Requirements

• Linux server with Docker Engine 24+ and the Compose plugin (docker compose version).

• Ports: 80 for the panel and for devices (/acs); 443 with HTTPS; 3478/udp if you enable STUN; 8883 if you enable USP.

• Access to the images. If you received registry credentials, sign in once:

  docker login ghcr.io -u <user name you were given>

  and paste the token you were given as the password.

Install

git clone --branch vX.Y.Z https://github.com/goacs/goacs-deploy.git goacs
cd goacs
./install.sh --host acs.example.net

Replace vX.Y.Z with the latest release and acs.example.net with the name or address under which browsers and devices will reach the server.

The installer creates .env with random secrets (database passwords, JWT_SECRET), starts the database, the backend and the panel, applies the database schema and prints the addresses:

• Admin panel: http://acs.example.net/
• ACS URL for devices: http://acs.example.net/acs
• First login: admin / admin - the panel asks you to change the password right away.

./install.sh --help lists the options (--no-start only writes .env, --tag picks the image version).

HTTPS

When the server has a domain name that resolves to it, and port 80 is reachable from the internet (Let's Encrypt checks it there):

./install.sh --domain acs.example.net --email ops@example.net

This also works on an existing installation. It adds docker-compose.https.yml: port 443 with a Let's Encrypt certificate that renews by itself, and COMPOSE_FILE in .env, so plain docker compose ... commands keep using both files.

• Panel and API: https://acs.example.net/ (plain HTTP redirects there).
• Devices: https://acs.example.net/acs. http://acs.example.net/acs (and /file, used for firmware downloads) keeps working without a redirect, for devices that cannot verify a certificate or are set up by IP address.
• The USP broker (8883) and STUN (3478/udp) keep their own ports and do not depend on the domain.

All HTTP traffic goes through one Traefik container (goacs-traefik); the panel and the backend publish no ports of their own.

Before connecting real devices

• Device authentication: /acs accepts any device until you set the ACS user name and password in Settings (basic or digest), and configure the same on your devices.
• TLS: enable HTTPS before exposing the panel to the internet.
• Secrets: .env holds the database and token secrets. Keep it private and include it in your backups.
• Backups: back up the database volume (or a mysqldump) and .env; the GoACS documentation you received describes backup and restore.

Optional parts

• TR-369 (USP): set USP_MQTT_URL=mqtt://goacs-mqtt:1883 and USP_MQTT_PASSWORD in .env, put the broker's TLS certificate and key in usp-certs/ for port 8883, then start with the broker:

  docker compose --profile usp up -d

• STUN for devices behind NAT (TR-111): set STUN_ADDR=:3478 in .env and publish 3478:3478/udp on goacs-backend in docker-compose.override.yml.

• Several backend replicas behind a load balancer: examples/high-availability/.

• Prometheus and Grafana: examples/monitoring/.

Upgrade

1. Read the release notes of the new version and back up the database and .env.

2. Fetch the new files and point the installation at the new images:

   git fetch --tags
   git checkout vX.Y.Z
   ./install.sh --tag vX.Y.Z

   --tag updates GOACS_IMAGE_TAG in your existing .env (which is otherwise never touched) and restarts the stack on the new images. The backend applies database migrations by itself when it starts.

3. Check the panel and docker compose logs goacs-backend.

To go back, check out the previous tag and run ./install.sh --tag with it, restoring the database backup if the new version changed the schema.

Customising

Docker Compose reads docker-compose.override.yml next to docker-compose.yml automatically. Put your changes there (extra volumes, resource limits, another Traefik option) instead of editing the generated files. Other HTTP/HTTPS ports need no override: set HTTP_PUBLISH_PORT / HTTPS_PUBLISH_PORT in .env.

# docker-compose.override.yml
services:
  goacs-backend:
    ports:
      - "3478:3478/udp"   # STUN

With HTTPS on, add the override to COMPOSE_FILE in .env (docker-compose.yml:docker-compose.https.yml:docker-compose.override.yml): an explicit COMPOSE_FILE replaces the automatic lookup.

What is here

Path	What
docker-compose.yml	The stack: Traefik, MariaDB, backend, panel; USP broker under the usp profile
docker-compose.https.yml	HTTPS layer: port 443 and a Let's Encrypt certificate (install.sh --domain)
install.sh	First installation and upgrades
.env.example	Every setting with its default; install.sh copies it to .env
contrib/conf/	MariaDB settings (utf8mb4, connection limit)
contrib/mosquitto/	USP broker configuration and its start script (accounts and access rules)
examples/	High availability, monitoring

Useful commands

docker compose ps                        # what is running
docker compose logs -f goacs-backend     # backend log
docker compose exec goacs-backend ./goacs doctor   # checks database, file store, broker
docker compose down                      # stop (data stays in the volumes)

Contact

contact@goacs.net