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. It checks that Docker and Docker Compose are ready, asks for the display language format and the time zone, writes docker-compose.yml into a new proxus-platform folder and, if you agree, starts the stack.

1. Open a terminal on the machine 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.
   • Timezone sets the time in the containers and in the log files, for example Europe/Istanbul.

   The installer then shows the machine address it found ("Address edge gateways use"). The hub offers it when you install an edge gateway. See Keep the hub's address stable.

   • Start the platform now? Answer Y to download the images and start the services at once. The first download is about 2 to 3 GB. Answer n to start later with docker compose up -d in the proxus-platform folder.

3. Check that every service is running and healthy:

   cd proxus-platform
   docker compose ps

   The health checks can take one or two minutes to turn green after the first start.

If a docker-compose.yml already exists in proxus-platform, the installer keeps a copy of it before it writes the new one. If Docker is missing, the Docker service is not running or Docker Compose v2 is not installed, the installer stops with a clear message and writes nothing.

Then continue with Sign in for the first time.

Install from a compose file

Use this way when your Proxus delivery includes a prepared compose file, or when the machine cannot reach proxus.io. If it cannot reach Docker Hub either, load the images first as in Install without internet access.

1. Create a folder for Proxus, for example /opt/proxus, and copy docker-compose.yml into it.

2. Set the time zone. In the compose file, the x-dotnet-env block sets TZ for the hub and the gateway. Change it to the plant's zone, for example:

   docker-compose.yml

   x-dotnet-env: &dotnet-env
     TZ: Europe/Paris

   The hub and the gateway write the times in their log files in this zone.

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

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, edit the Service__PublicAddress line of the proxus-ui service in proxus-platform/docker-compose.yml (several addresses or DNS names separated by commas), then run docker compose up -d. Running the installer again also detects the address again.

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.