Docker

At the end of this guide, the Proxus hub runs on one machine with Docker Compose, with the time zone and settings of your site, and you know where each setting and your own changes belong. The installer sets all of this up and keeps it up to date; this page explains what it builds, for running and adjusting it.

Before you start

• A Linux machine (or a Windows or macOS machine with Docker Desktop) that meets the system requirements.
• Docker Engine with the Docker Compose plugin (docker compose version prints a version).
• An installation made with the installer, or the docker-compose.yml of a Proxus release in a folder of its own, for example /opt/proxus-platform. Each release's file uses that release's images.
• Access to Docker Hub, where the images proxusplatform/proxus-ui and proxusplatform/proxus-server are published, or the images loaded beforehand with docker load. See Install without internet access.

What the compose file runs

Every service restarts by itself (restart: always) and the hub, the gateway and the databases have health checks. The config volume is shared by the hub, the gateway and the broker: it holds the configuration file, the broker's credentials and TLS certificate, the keys that protect sign-ins, and the Certificate Store key (keys/STORE/certificate-store.key). Without the Certificate Store key, the certificates in the database cannot be read, so back up the config volume together with the database. See Backup and restore.

The proxus-ui container also mounts the Docker socket (/var/run/docker.sock). The hub uses it to restart the stack after a configuration change.

The files of an installation

COMPOSE_PROJECT_NAME names the stack and, with it, its volumes (proxus_config and so on): proxus for new installations, proxus-platform for installations made with an earlier installer. Never change it after the first start: under another name, Compose finds none of the data. The containers have fixed names, so only one Proxus hub stack runs on a host.

Start the stack

Run every command in the installation folder: Compose reads .env there, so the stack name, the release and the compose files are always the right ones. The hub's Restart button in the Config Editor restarts the stack the hub belongs to.

cd /opt/proxus-platform
docker compose up -d

On the first start, the hub creates the message broker's credentials on the config volume. Until it has done that, hub-server prints "Waiting for Proxus UI to create the NATS trust" every two seconds. This is expected.

Check that everything runs:

docker compose ps

proxus-ui, proxus-server and postgresql show healthy once they are ready. Then open https://<host>:8443 and sign in. HTTPS is on by default, with a certificate from the platform's own certificate authority; http://<host>:8080 stays available for local access. See Security.

Day-to-day commands

In the installation folder:

Updates, backups and restores are done by the installer.

Adjust the stack for your site

Put your changes in docker-compose.override.yml next to docker-compose.yml (the installer creates an empty one), then apply them with docker compose up -d. Compose recreates only the containers whose settings changed.

Time zone, culture, address. These are in .env (TZ, PROXUS_CULTURE, PROXUS_PUBLIC_ADDRESS). Run the installer and choose Change culture, time zone or addresses, or edit .env and run docker compose up -d.

Settings as environment variables. Any key of the configuration file can be set under environment: as Section__Key. Values set here win over the file and survive upgrades:

services:
  proxus-ui:
    environment:
      Security__Lockout__MaxFailedAccessAttempts: "5"

Ports. In an override file, a ports list is added to the release's list. To replace it, mark it with !override (Docker Compose 2.24 or later), for example to publish the web interface on port 80 and keep the database reachable only from the host itself:

services:
  proxus-ui:
    ports: !override ["80:8080", "8443:8443"]
  postgresql:
    ports: !override ["127.0.0.1:5442:5442"]

The services reach each other on the internal proxus network and do not need the published ports. See Security for which ports must be open.

HTTPS. The hub serves HTTPS on 8443. To publish it on another host port, for example "443:8443", also set Service__PublicHttpsPort: "443". Add the names users type to reach the hub with Service__PublicHostNames, so the hub's certificates cover them.

MQTT over TLS. The SYSTEM gateway's broker also listens for TLS on 8883, which the shipped file publishes next to 1883.

ClickHouse memory. The clickhouse service is limited to 8 GB of memory. Lower it on a small machine, raise it for a large installation:

services:
  clickhouse:
    deploy:
      resources:
        limits:
          memory: 4g

After an upgrade to 2.0.0

The installer does this by itself. Without it, restart the message broker once after the hub has started, so it picks up its TLS certificate:

docker restart hub-server

Then run the install command of every remote edge gateway again. See Upgrade.

What's next

• Upgrade
• Back up the installation
• Harden the installation
• Install an edge gateway on another host