Install Proxus with Docker

At the end of this guide, Proxus runs on one machine with Docker Compose and you are signed in to the hub. This setup suits a trial, a demo or a small site. For production, read Run Proxus with Docker as well.

Before you start

You need:

• A machine with Docker Engine and the Docker Compose plugin (the docker compose command). See the system requirements.
• Internet access to proxus.io for the installer. If you install from a compose file you received with your Proxus delivery instead, have that docker-compose.yml ready.
• Access to Docker Hub, where the Proxus images (proxusplatform/proxus-ui and proxusplatform/proxus-server) and the database and message server images are published. On a network without internet access, follow Install without internet access instead.
• These ports free on the machine: 8080, 8443, 8083, 1883, 8883, 4222, 8222, 7422, 5442, 8123, 9000, 9004 and 9005. Network ports says what each one is for.
• A license key from Proxus or your distributor. You can also start without one and send the License ID the hub shows on its first start.

What the compose file starts

Each service keeps its data on a named Docker volume (proxus-db-volume, clickhouse_data, nats, config, proxus_modules), so the data survives a restart or an image update.

Install with the installer

The installer is the quickest way to start, and the same command later updates, backs up and changes the installation. It checks that Docker and Docker Compose are ready, asks a few questions, downloads the files of the latest Proxus release into a new proxus-platform folder (checked against the release's checksums) and, if you agree, starts the stack.

1. Open a terminal on the machine, go to the folder where Proxus should live (for example /opt), and run the installer for its operating system:

   curl -fsSL https://proxus.io/install.sh | bash

   irm https://proxus.io/install.ps1 | iex

   If your Docker setup needs it, run the command with sudo on Linux, or open PowerShell as administrator on Windows.

2. Answer the installer's questions:

   • Culture sets how numbers and dates are shown, for example tr-TR or en-US. The installer suggests the machine's own setting.
   • Time zone sets the time in the containers and in the log files, for example Europe/Istanbul.
   • Addresses edge gateways reach this machine on: the installer suggests the addresses it found. The hub offers them when you install an edge gateway. See Keep the hub's address stable.
   • Install Keycloak next to Proxus? Answer N unless you need one company account for several applications or Windows sign-in without a password. Proxus signs people in with Active Directory, LDAP, Microsoft Entra ID or Okta without Keycloak. See Choose how people sign in. You can add Keycloak later.
   • Start Proxus now? Answer Y to download the images and start the services at once. The first download is about 2 to 3 GB. The installer waits until every service is healthy.

3. Open Proxus, as in Sign in for the first time.

The installer keeps the answers in proxus-platform/.env and writes a log of every run to proxus-platform/logs/. If Docker is missing, the Docker service is not running or Docker Compose v2 is not installed, it stops with a clear message and writes nothing.

Proxus runs one hub per machine: its containers have fixed names. If Proxus already runs on the machine from another folder, the installer names that folder and stops without changing anything.

To install from a script without questions, add --yes (every question takes its default) and, if needed, the release:

curl -fsSL https://proxus.io/install.sh | bash -s -- install --version 2.1.0 --yes

Update, back up and change the installation

Run the same installer command again in the folder that contains proxus-platform. It recognises the installation and offers:

Installations made with an earlier installer are taken over as they are: their stack name, volumes, data and the ports the hub is published on stay.

Install from a compose file

Use this way when the machine cannot reach proxus.io, or when you manage the files yourself. If the machine cannot reach Docker Hub either, load the images first as in Install without internet access.

1. Take docker-compose.yml from the Proxus release (or from the proxus-docker_<version>.zip package of your delivery) and copy it into a new folder, for example /opt/proxus-platform.

2. Next to it, create a .env file with the settings of this installation:

   .env

   COMPOSE_PROJECT_NAME=proxus
   TZ=Europe/Paris
   PROXUS_CULTURE=fr-FR
   PROXUS_PUBLIC_ADDRESS=192.168.10.20

   TZ sets the time in the containers and log files. PROXUS_PUBLIC_ADDRESS is the address (or several, comma separated) edge gateways reach this machine on. The compose file already uses the images of its release.

3. In the folder, start the stack:

   docker compose up -d

   Docker downloads the images the first time, then starts the five services.

4. Wait until every service is running and healthy:

   docker compose ps

   On the first start the hub creates its database tables, the message server's security settings and the platform's certificate authority (the Proxus Platform CA), so it takes longer than later starts. Until the hub has done this, the hub-server log repeats Waiting for Proxus UI to create the NATS trust. That is expected.

5. Check that the hub answers. This prints Healthy when it is ready:

   curl http://localhost:8080/healthz

Put your own changes to the stack in docker-compose.override.yml next to docker-compose.yml, not in docker-compose.yml itself: the installer and later releases replace docker-compose.yml, never the override.

Sign in for the first time

1. Open https://<host>:8443 in a browser, where <host> is the machine's name or IP address (https://localhost:8443 on the machine itself). The hub's certificate is issued by the Proxus Platform CA, which your browser does not know yet, so it shows a warning the first time. Continue to the page, or open http://<host>:8080 instead. To remove the warning, install the platform CA on your computer (see Certificates).

2. If the form is not in your language, pick it from the list at the top right of the form.

3. Enter the user name Admin and leave Password empty. Select Log In.

4. A new hub has no license yet, so the License Activation window opens. Paste the key you received and activate it. The key works only on this installation; the window shows the License ID to send when you order one.

   If you close the window without activating, you are signed out. License explains licenses in detail.

5. You now see the Operations Center.

Secure the first accounts

The first start creates one administrator account, Admin, with an empty password. Before anyone else can reach the hub, open the user menu at the top right, select My Details, then Change My Password, and set a strong password. For API access, add a user of its own on Security > Users.

Users and roles explains how to add accounts for your team.

Keep the hub's address stable

Each edge gateway is installed with the hub address you choose in its install wizard and connects to that address only. If the hub machine gets a new IP address later, for example from DHCP, the edge gateways lose their connection and each one must be installed again.

• In production, give the hub a fixed address: a DHCP reservation or a static IP, or better, a DNS name such as proxus.plant.local. With a DNS name, an IP change does not affect any edge gateway.
• The install wizard first offers the address you opened the hub on, then the address the installer found. Open the hub on the address the edge machines use, so that the right one comes first.
• To change the address the hub offers, run the installer again and choose Change culture, time zone or addresses. Or set PROXUS_PUBLIC_ADDRESS in proxus-platform/.env (several addresses or DNS names separated by commas) and run docker compose up -d in that folder.

Keep the certificate key

The hub keeps the private keys of its certificates encrypted. The key for them is in the config volume (keys/STORE/certificate-store.key). Include the config volume in every backup: without this key, the certificates cannot be read after a restore. See Backup and restore.

What's next

• Connect your first machine with the built-in simulator.
• A tour of the hub shows what each screen is for.
• Run Proxus with Docker covers production settings, updates and backups.
• Configuration explains the configuration file. Docker keeps it on the config volume, where the hub writes it with its defaults on the first start.