Installing the application on your own servers

This page is for the technical administrator who installs MyZapp on their own servers (an "on-premise" installation). An instance hosted by the publisher has nothing to install.

The installation relies on Docker: the application and its PostgreSQL database each run in a container, and all data lives in two volumes. Nothing needs compiling.

What you receive

the application's Docker image, as a .tar file or to pull from a private registry;
the orchestration file docker-compose.onprem-client.yml;
the settings template .env.template;
the generate-secrets.sh script, which creates the database passwords;
the init-condition-sql-role.sql script, mounted by the orchestration file;
an empty views-override/ folder.

Requirements: Docker Engine (or Docker Desktop) with Docker Compose v2, at least 2 GB of memory and 10 GB of disk.

Installing

If the image is delivered as a file, load it: docker load -i followed by the name of the .tar file.
Copy .env.template to .env, then fill in at least WEBBASE_IMAGE (the image to use) and APP_PORT (the application port, 8080 by default).
Run ./generate-secrets.sh. It creates the secrets/ folder with two random passwords for PostgreSQL. These passwords never appear in .env; without them, Docker Compose refuses to start.
Start: docker compose -f docker-compose.onprem-client.yml up -d.
Open the application in the browser, at the server's address and on the chosen port: the setup wizard appears.

The setup wizard

The wizard only appears once, on a new instance. It is displayed in the browser's language when available (English, French or Spanish), otherwise in French; the links at the top of the page switch language at any time, and the choice applies to the following steps. It has four steps.

Database (PostgreSQL connection): Host, Port, Database, Username, Password and Connection encryption. With the supplied orchestration file, the database host is webbase-postgres and the password is left empty: the application reads the one in the secrets/ folder. Test connection checks the values before moving on.
Initial administrator account: Display name, Email address and Password of the first administrator.
Security keys: the API token signing key, the data encryption key and the two-factor encryption key are generated at random. Export downloads them: keep them in a safe place, they cannot be retrieved after setup. Regenerate draws new ones.
Configuration summary: enter the Public address of the instance, in https://, the one users will open. It is used to build the links sent by e-mail. Tick Install demo data for the service catalog if needed, then Apply and start.

The application runs its migrations, creates the administrator account, then restarts by itself: wait a few seconds before opening the sign-in page. The supplied orchestration file restarts it automatically.

Switching to HTTPS

The application is only supported over HTTPS: outside a test workstation, its session cookies only travel over an encrypted connection, and a connection over HTTP does not succeed. Put a reverse proxy (nginx, Traefik…) in front of it to carry the certificate and forward requests to the application port.

The proxy must forward the X-Forwarded-For and X-Forwarded-Proto headers. By default, the application only trusts them when they come from the machine itself or from a private network. To trust only the proxy, fill in TRUSTED_PROXIES (its address as seen by the container) or TRUSTED_NETWORKS (its network) in .env.
The application port must only be reachable by the proxy: close it at the firewall, or publish it on the loopback interface only.

Checking the installation

The instance's /health address answers Healthy when the application and its database are working.
The Instance status screen gives the version, the database, the disk space and the enabled modules (see "Monitoring the instance").
Then activate the instance license (see "Managing the instance licenses") and import the documentation shipped with the version (see "Update the documentation").

The database administration tool

pgAdmin is supplied but does not start by default. To use it, fill in PGADMIN_EMAIL and PGADMIN_PASSWORD in .env, then start with the --profile admin option. It listens on the PGADMIN_PORT port (5050 by default). Stop it when you no longer need it.