On-premises (self-managed)

Deployment options

See the documentation for an overview of the two on-premises deployment options.

Services

The maXzie on-premises deployment contains the following services as Docker containers:

• maxzie
  • Web application
  • REST api
• maxzie-configurator
  • Applies internal maXzie configuration
• caddy
  • Reverse proxy
  • handling TLS termination
  • can automatically obtain and renew public TLS certificates
• postgres
  • production database

Tip

A sample docker-compose.yml file is provided. You can also deploy maXzie with your own container orchestrator, reverse proxy and Postgres server.

Requirements

• Virtual machine with public IP address and the following hardware
  • RAM: a minimum amount of 8 GB
  • CPU: one core per 150 users
  • DISK: 40 GB disk space
• Ports 80 and 443 have to be open externally
• DNS A/AAAA records pointing to the public IP address
• Docker (version 19.03.0 or higher) and Docker Compose (version 1.27.0 or higher) has to be installed on the virtual machine

Note

If you are using the deprecated Docker Compose V1, replace the docker compose command in the following examples with docker-compose.

ZIP file provided by News Innovativ GmbH

The ZIP file contains access data for the maXzie Container Registry, example configuration files and additional documentation.

In the following documentation it is assumed that the ZIP file is unpacked.

Access to maXzie container registry

We provide your personal login information in the file .env.registry_token. The containing environment variables can then either be set manually or loaded into the bash using the source command.

You can then login with:

echo $TOKEN_PWD | docker login --username $TOKEN_NAME --password-stdin newsinnovativ.azurecr.io

Setting up HTTPS

By default, the Caddy reverse proxy serves all sites over HTTPS.

Public DNS names

Caddy can automatically obtain and renew Let’s Encrypt TLS certificates. This is enabled by specifying a domain name in the Caddyfile (e.g. example.com).

Local / internal hostnames

Caddy can also create self-signed certificates for local/internal hostnames. This is enabled by specifyig the hostname in the Caddyfile (e.g. localhost).

In this case the root CA cert can be exported with:

docker compose cp \
    caddy:/data/caddy/pki/authorities/local/root.crt \
    maxzie-caddy-root.crt

Use your own certificate

For providing your own certificates with Caddy, add the following line to the Caddyfile:

Caddyfile

tls cert.pem key.pem

Make sure to add them to the Docker container with a bind mount or a custom Docker image.

Technical maXzie configuration

The following configurations can be set as environment variables for the services, e.g. in a docker-compose.yml file.

Secret or recurring environment variables can be saved in a .env file next to a docker-compose.yml file. (see .env.template)

Danger

Make sure you never commit .env files to Git repositories.

maxzie service

Database

For the database connectivity, set the following environment variables:

• JAKARTA_PERSISTENCE_JDBC_URL: choose depending on the location of the database
  1. On the same host:

     jdbc:postgresql://${POSTGRES_HOST}:5432/${POSTGRES_DATABASE}?currentSchema=${POSTGRES_SCHEMA}

  2. On another host:

     jdbc:postgresql://${POSTGRES_HOST}:5432/${POSTGRES_DATABASE}?currentSchema=${POSTGRES_SCHEMA}&ssl=true&sslmode=verify-full&sslrootcert=/etc/ssl/certs/DatabaseRootCA.crt.pem

     • Make the certificate available to the container with a bind mount, e.g.

       volumes:
         - ./DatabaseRootCA.crt.pem:/etc/ssl/certs/DatabaseRootCA.crt.pem:ro

• JAKARTA_PERSISTENCE_JDBC_USER
• JAKARTA_PERSISTENCE_JDBC_PASSWORD

Authentication

Choose one of the available authentication methods. Then set the following environment variables for that method:

1. Internal authentication using maXzie
   • NEWSVG_PROFILES: migrationNone,authenticationInternal
   • in the maxzie-config.yml file add (see maxzie-config.doc.yml for documentation)
     • the definitions for loginname, passwort and isPasswortTemporary to customer_specific_field_definitions
     • loginname and passwort to mitarbeiter_customer_specific_form_fields
     • also add email to both, if an SMTP server is configured
2. OpenID Connect / Microsoft Entra ID
   • NEWSVG_PROFILES: migrationNone,authenticationOIDC
   • NEWSVG_OIDCCLIENTID
   • NEWSVG_OIDCAUTHORITY
   • NEWSVG_OIDCTENANTID
   • NEWSVG_OIDCREDIRECTURI
   • NEWSVG_OIDCSCOPES
     • has to be exactly one scope
   • NEWSVG_OIDCJWKSURI
   • NEWSVG_OIDCLOGINBUTTONTEXT
   • Optional: NEWSVG_OIDCAUDCLAIM
   • Optional: NEWSVG_OIDCIDENTIFYINGCLAIM
     • Default: unique_name
   • Optional: NEWSVG_OIDCPERMITTEDGROUPIDS
     • List separated by spaces
   • Options for Non-Microsoft Entra ID identity providers:
     • NEWSVG_OIDCPROTOCOLMODE: OIDC
     • Optional: NEWSVG_OIDCKNOWNAUTHORITIES
       • List separated by spaces
     • The following parameters are optional. If one of them is set, all have to be set:
       • Optional: NEWSVG_OIDCAUTHORITYMETADATA_ISSUER
       • Optional: NEWSVG_OIDCAUTHORITYMETADATA_AUTHORIZATION_ENDPOINT
       • Optional: NEWSVG_OIDCAUTHORITYMETADATA_TOKEN_ENDPOINT
       • Optional: NEWSVG_OIDCAUTHORITYMETADATA_USERINFO_ENDPOINT
3. LDAPS / Active Directory
   • NEWSVG_PROFILES: migrationNone,authenticationActiveDirectory
   • NEWSVG_ACTIVEDIRECTORYURL
   • Optional: NEWSVG_ACTIVEDIRECTORYDOMAIN
     • set if user should not log in with username@domain
   • Optional: NEWSVG_ACTIVEDIRECTORYROOTDN
     • if not set, will be determined from domain
   • Optional: NEWSVG_ACTIVEDIRECTORYSEARCHFILTER
     • Default: (&(objectClass=user)(userPrincipalName={0}))
       • {0}: username@activeDirectoryDomain
       • {1}: username
   • Import TLS certificate as explained in the documentation.

SMTP server for sending notifications / password resets (optional)

• NEWSVG_SMTP_HOST
• NEWSVG_SMTP_PORT
• NEWSVG_SMTP_PROTOCOL
• NEWSVG_SMTP_USER
• NEWSVG_SMTP_PASSWORD

Import the SMPT server TLS certificate as explained in the documentation.

Import TLS certificates for accessing external services (e.g. Active Directory, SMTP)

To import certificates to the maXzie Java keystore, run the following commands for each certificate in the maXzie main folder:

# Export the default maXzie keystore
docker run --rm --name prepare-java-keystore -v ./:/tmp/certs -u root --entrypoint "" maxzie bash -c 'cd /tmp/certs/ && cat /etc/ssl/certs/java/cacerts > cacerts && chown maxzie_app:maxzie_app cacerts'

# Add certificate to maXzie keystore (change the file name and alias!)
docker run --rm -v ./:/tmp/certs maxzie bash -c 'cd /tmp/certs && keytool -keystore cacerts -storepass changeit -noprompt -trustcacerts -importcert -alias my-company-root-ca -file my-company-root-ca.crt'

To use the new maXzie keystore, mount it on the maxzie container. For an example see the docker-compose.yml file.

maxzie-configurator service

Database

For the database connectivity, set the following environment variables:

• JAKARTA_PERSISTENCE_JDBC_URL: same as for the maxzie service
• JAKARTA_PERSISTENCE_JDBC_USER
• JAKARTA_PERSISTENCE_JDBC_PASSWORD
• PGPASSWORD
• PGSSLMODE: verify-full (if database is on another host)
• PGSSLROOTCERT: path to database certificate (if database is on another host)
• POSTGRES_HOST
• POSTGRES_ADMIN_USER
• POSTGRES_DATABASE
• POSTGRES_SCHEMA
• POSTGRES_MAXZIE_USER
• POSTGRES_MAXZIE_PASSWORD

Internal maXzie configuration

These options can be set in the maxzie-config.yml file.

Make sure this file is readable for everyone (e.g. with chmod o+r maxzie-config.yml).

Tip

See the maxzie-config.doc.yml file for documentation and maxzie-config.example.yml for a typical configuration.

Start maXzie

Start Docker Container:

docker compose up -d

Common administration tasks

Note

Depending on the Docker Compose Version, you might have to replace the container names in the following commands.

• maxzie-maxzie-1 => maxzie_maxzie_1

Create first maXzie user

Call this command to create a new maXzie user and answer the prompts.

docker exec -it maxzie-maxzie-1 /opt/maintenance/createmaxzieuser

Backups

You are responsible for backing up

• the maXzie PostgreSQL database
• all configuration files

Updates

You are responsible for updating the services by pulling and using the latest Docker images.

One option would be using a nightly cron job that runs:

docker compose pull
docker compose down --remove-orphans
docker compose up -d

One of many other options could be Watchtower.

Changing configuration

After configuration changes, especially to the maxzie-config.yml file, run:

docker compose down --remove-orphans
docker compose up -d

If you only changed the Caddyfile, reload Caddy with:

docker compose exec -w /etc/caddy caddy caddy reload

Logging

To see a docker container’s 1000 most recent logs, and follow to see new ones streaming in:

docker compose logs <SERVICENAME> -n=1000 -f

Monitoring

Display a live stream of containers resource usage statistics:

docker stats

For more information about the reverse proxy see Monitoring Caddy.

Removing old Docker images

If old Docker images take up too much space, they can be removed with the docker image prune command.