Install

Pizug Companion is delivered as a Docker image: pizug/companion on Docker Hub. It is one container, one port and one data volume. There is no database server to install next to it.

The current version is 2.0.0.

Coming from version 1?

Version 2 is a clean install: it does not read the data directory of version 1. See Upgrade & Maintenance.

Quick start

You need Docker installed. Then:

docker volume create pizug_companion
docker run -d --name pizug-companion -p 3000:8080 -v pizug_companion:/data --restart=always pizug/companion:2.0.0

Open http://localhost:3000/. On a new installation the page asks you to create the administrator account. After that:

1. Set the license. The community license is free.
2. Connect a tenant.

Caution

Until the administrator account exists, whoever opens the page first can create it. On a shared network, finish this step right after starting the container, or create the administrator with environment variables as described below.

The data directory

Everything Companion keeps lives in one directory, /data inside the container: users, tenants, encrypted credentials, stored message logs and artifact history. You can remove the container and start a new one on the same directory, and it continues where it stopped.

Volume managed by Docker

The quick start uses a Docker volume named pizug_companion. On Windows and Mac this is the faster choice, because the data stays inside the Docker file system.

Bind mount (a directory of the host)

On a Linux server you may prefer a directory you choose, such as /var/data/companion. The container runs as a non-root user (uid 65532), so give that user the directory first:

sudo mkdir -p /var/data/companion
sudo chown 65532:65532 /var/data/companion
docker run -d --name pizug-companion -p 3000:8080 -v /var/data/companion:/data --restart=always pizug/companion:2.0.0

Tip

On Windows, a bind mount to a C:\ path crosses the WSL2 file system boundary and is slow. Use a Docker volume there. See Microsoft’s notes on performance across file systems.

Back up the master key

On first start Companion writes master.key into the data directory. It encrypts the tenant credentials in the database. Back it up together with the rest of the directory: a database without its key cannot be used. See Backup.

The first administrator

There are three ways to create it. All three only work while no user exists.

• In the browser. Open the page and fill in the form. This is the quick start above.

• With environment variables. The administrator is created when the container starts, and the setup form never appears. The variables are ignored once any user exists, so they can stay in your container definition. The password needs at least 8 characters.

  docker run -d --name pizug-companion -p 3000:8080 -v pizug_companion:/data --restart=always \
    -e COMPANION_ADMIN_USERNAME=admin -e COMPANION_ADMIN_PASSWORD='choose-a-password' \
    pizug/companion:2.0.0

• With the command line, against the data directory, without a running server:

  docker run --rm -it -v pizug_companion:/data pizug/companion:2.0.0 user add --username admin

If you lose the administrator password, the same command line resets it: see Users & Roles.

Docker Compose

services:
  companion:
    image: pizug/companion:2.0.0
    restart: always
    ports:
      - "3000:8080"
      # - "443:8443"   # built-in HTTPS, see the HTTPS page
    volumes:
      - pizug_companion:/data

volumes:
  pizug_companion:

Ports and health

Port	Use
8080	HTTP. Always open.
8443	HTTPS. Only listens once a certificate is installed: see HTTPS.

The image has a health check built in, so docker ps shows healthy when the server answers. For your own monitoring, GET /healthz on the HTTP port needs no sign-in.

Which tag to use

Examples on this site pin the exact version, pizug/companion:2.0.0, which is what we recommend for production: an upgrade then happens when you decide it.

All settings are environment variables. The full list is on the Configuration page.