Docker / Podman

Prerequisites:
  • Linux VM with the latest version of Podman
  • Access to Docker Hub
  • Available ports
    • 8443 - Web UI
    • 8162 - OS Agent
    • 2055 - NetFlow
    • 6343 - sFlow
  • PostgreSQL/TimescaleDB container
  • XorMon container
  • Bind mounts for both the database data and the XorMon data
Contents:

Installation

Perform following two steps under the "root" account

Install Podman

Create user "xormon"
    # Debian
adduser xormon

# RedHat
useradd xormon
    Set the "linger" property for the user so that containers can continue running even after logout
    loginctl enable-linger xormon
Perform all subsequent steps under the "xormon" user account

Enable automatic container start

Do not use "su - xormon" to switch to the "xormon" user.Some commands may then fail.
Log in directly as the “xormon” user
    systemctl --user enable podman-restart.service
Create directories for persistent data
    mkdir -p ~/xormon-ng/data ~/xormon-ng/files
Create configuration file
    cd ~/xormon-ng
nano ./xormon-ng.env
    File contents
    APP_PORT=8443
TZ=<timezone>
DB_HOST=timescaledb
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=<db_password>
DB_DATABASE=xormon
APP_SECRET=<xormon-secret>
    Replace <variables> with values:
    • <timezone> - Linux timezone, e.g. 'Europe/Prague' (see list of timezones in 'ls -l /usr/share/zoneinfo')
    • <db_password> - password used for running Timescale DB container
    • <xormon-secret> - any unique string, e.g. 'my-xormon-secret'
    Do not use quotes around the values, "docker run --env-file" does not remove them.
Create network for containers
    podman network create xorux
Start PG16/TimescaleDB container
    source ~/xormon-ng/xormon-ng.env

podman run --network xorux --init --restart=always --shm-size=4g -d \
  -v ~/xormon-ng/data:/var/lib/postgresql/data \
  --name timescaledb -e POSTGRES_PASSWORD=$DB_PASSWORD --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/timescale/timescaledb:latest-pg16
Start XorMon container
    podman run --network xorux --init --restart=always -d --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v ~/xormon-ng/files:/app/server-nest/files \
  --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/xorux/xormon-ng:latest
Navigate to XorMon GUI
    https://<podman_host_IP>:8443/
    Default login: xormon / xormon
Notes:
  • Using ssh-key based devices access docu in Podman.
  • Using Java in Podman docu.

XorMon upgrade

Do not use 'Application Upgrade' form in GUI!

Stop and remove the current container.
Start a new version.

Perform all steps under the "xormon" user account

Upgrade from Docker Hub
    podman stop xormon
podman rm xormon

podman pull docker.io/xorux/xormon-ng:latest

podman run --network xorux --init --restart=always -d --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v ~/xormon-ng/files:/app/server-nest/files \
  --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/xorux/xormon-ng:latest
Upgrade from downloaded image
    podman stop xormon
podman rm xormon

podman load < xormon-ng-docker-x.y.z.tar.gz

podman run --network xorux --init --restart=always -d --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v ~/xormon-ng/files:/app/server-nest/files \
  --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/library/xormon:x.y.z

Backup

Perform all steps under the "xormon" user account

Create a directory for the backup
    mkdir -p /tmp/xormon-backup
Save PostgreSQL and TimescaleDB version
    podman exec timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';" | tee /tmp/xormon-backup/db-version.txt
Stop XorMon
    podman stop xormon
Backup the database

    This step may take a long time depending on the size of the database.
    podman exec timescaledb pg_dump -U postgres --format=custom -d xormon > /tmp/xormon-backup/xormon-database.dump
Backup XorMon configuration and files
    cp ~/xormon-ng/xormon-ng.env /tmp/xormon-backup/
podman unshare tar --numeric-owner -cpzf /tmp/xormon-backup/xormon-files.tar.gz -C ~/xormon-ng/files .
Start XorMon
    podman start xormon

Restore

The database backup can only be restored to the same version of TimescaleDB from which it was created.
The PostgreSQL version can be the same or higher.

Example:
You can restore a database backup from TimescaleDB 2.17.1 on PostgreSQL 14
to TimescaleDB 2.17.1 on PostgreSQL 14, 15, 16 or 17

Perform all steps under the "xormon" user account

Create directories for persistent data volumes
    mkdir -p ~/xormon-ng/data ~/xormon-ng/files
Restore XorMon configuration file
    cp /tmp/xormon-backup/xormon-ng.env ~/xormon-ng
Create network for containers
    podman network create xorux
Start PostgreSQL/TimescaleDB container

    Use the versions from the backup.
    Check the file containing the PG and TSDB versions, if you created one.
    cat /tmp/xormon-backup/db-version.txt
    source ~/xormon-ng/xormon-ng.env

podman run --network xorux --init --restart=always --shm-size=4g -d \
  -v ~/xormon-ng/data:/var/lib/postgresql/data \
  --name timescaledb -e POSTGRES_PASSWORD=$DB_PASSWORD --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/timescale/timescaledb:x.y.z-pg1X
Restore the database
    podman exec timescaledb psql -U postgres -c "DROP DATABASE IF EXISTS xormon;" -c "CREATE DATABASE xormon;"
podman exec timescaledb psql -U postgres -d xormon -X -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'
podman exec timescaledb psql -U postgres -d xormon -X -c "SELECT timescaledb_pre_restore()"
podman exec timescaledb psql -U postgres -d xormon -X -c "ALTER SYSTEM SET timescaledb.restoring = on;"

podman exec -i timescaledb pg_restore -U postgres -d xormon --no-owner --role=postgres < /tmp/xormon-backup/xormon-database.dump

podman exec timescaledb psql -U postgres -d xormon -X -c "SELECT timescaledb_post_restore()"
podman exec timescaledb psql -U postgres -d xormon -X -c "ALTER SYSTEM SET timescaledb.restoring = off;"

podman restart timescaledb
Restore XorMon files
    podman unshare tar --numeric-owner -xpzf /tmp/xormon-backup/xormon-files.tar.gz -C ~/xormon-ng/files/
Start XorMon container
    podman run --network xorux --init --restart=always -d --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v ~/xormon-ng/files:/app/server-nest/files \
  --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/xorux/xormon-ng:latest
Navigate to XorMon GUI
    https://<podman_host_IP>:8443/

TimescaleDB Upgrade

This method allows you to upgrade only the TimescaleDB version, not the PostgreSQL version.
Upgrading PostgreSQL requires data migration, as described in "PostgreSQL upgrade" section of this guide.

To upgrade TimescaleDB, simply stop and delete the current container, then start a new one with a higher version of TimescaleDB.

The database data is persisted on the file system using a bind mount, therefore deleting the container will not delete the database data.

Perform all steps under the "xormon" user account

Display PostgreSQL and TimescaleDB version
    podman exec timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';"
Stop XorMon
    podman stop xormon
Remove TimescaleDB container
    podman stop timescaledb
podman rm timescaledb
Deploy new TimescaleDB container

    Install either a specific version of TimescaleDB or simply the "latest" version.
    In either case, use the same version of PostgreSQL as the original container.
    source ~/xormon-ng/xormon-ng.env

podman pull docker.io/timescale/timescaledb:latest-pg1X

podman run --network xorux --init --restart=always --shm-size=4g -d \
  -v ~/xormon-ng/data:/var/lib/postgresql/data \
  --name timescaledb -e POSTGRES_PASSWORD=$DB_PASSWORD --env-file ~/xormon-ng/xormon-ng.env \
  docker.io/timescale/timescaledb:latest-pg1X
Update TimescaleDB extension
    podman exec timescaledb psql -U postgres -X -c "ALTER EXTENSION timescaledb UPDATE;"
podman exec timescaledb psql -U postgres -d xormon -X -c "ALTER EXTENSION timescaledb UPDATE;"
Display PostgreSQL and TimescaleDB version
    podman exec timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';"
Restart TimescaleDB container
    podman restart timescaledb
Start XorMon
    podman start xormon

PostgreSQL upgrade

Upgrading to a higher version of PostgreSQL requires the following steps, described earlier in this guide

Perform all steps under the "xormon" user account

Stop XorMon
    podman stop xormon
Back up the database

    Perform following steps in the "Backup" section:
    • Create a directory for the backup
    • Save PostgreSQL and TimescaleDB version
    • Backup the database
Remove the TimescaleDB container
    docker stop timescaledb
docker rm timescaledb
Delete the directory containing the database data
    podman unshare rm -rf ~/xormon-ng/data
Create a new directory for the database data
    mkdir ~/xormon-ng/data
Restore database to a new container

    Start a new timescaledb container with the same version of TimescaleDB but a new version of PostgreSQL
    Perform following steps in the "Restore" section:
    • Start PostgreSQL/TimescaleDB container
    • Restore the database
(Optional) Upgrade TimescaleDB version
Start XorMon
    podman start xormon

XorMon Migration

    Backup up the XorMon files and database on the source virtual machine, and restore them on the new virtual machine.
This documentation describes how to deploy our Docker application containers in environment without an access to the Internet.

Docker installation

For the Docker, make sure you have Docker Engine installed: docs.docker.com/engine/install
You also don't need an Internet connection for this, just follow the instructions for your distro and use this method of installation: Install from the package.
If your distro is not supported, please refer to installation using binaries

As for the Docker compose vs Docker run methods, they both produce the same result, this manual assumes the usage of Docker compose method.

Installation of the downloaded Docker image

Transfer the downloaded xormon-ng-docker-<version>.tar.gz archive onto the server.
Then do the same for the latest TimescaleDB Docker image.
We recommend using the latest-pg16 version of the image.
After you do this, follow the instructions of the Docker method of your preference

Docker compose scenario would follow like this (it only differs in step 4 and 5):
  1. Make sure you have the archive xormon-ng-docker-<version>.tar.gz prepared on the machine.

  2. Follow step by step from here but do not run the containers yet: Docker compose

  3. Then run this command to load the image locally: 
    docker load <  xormon-ng-docker-<version>.tar.gz
  4. After that, inside the docker-compose.yml, edit this part: 
    image: xorux/xormon-ng:latest
    to this:
    image: xormon:<version>
    Note: It is important that you keep the formatting of the .yml file the same as original, otherwise it won't work.

  5. Finally, use this command to start the app: 
    docker compose up -d


Notes:
  • Using ssh-key based devices access docu in Docker.
  • Using Java in Docker docu.
Prerequisites:
  • Linux VM with the latest version of Docker Engine
  • Docker Compose CLI plugin
  • Access to Docker Hub
  • Available ports
    • 8443 - Web UI
    • 8162 - OS Agent
    • 2055 - NetFlow
    • 6343 - sFlow
  • PostgreSQL/TimescaleDB container
  • XorMon container
  • Bind mounts for both the database data and the XorMon data
Contents:

Installation

Perform all steps under the "root" account (or prefix the commands with sudo)

Install Docker Engine

Create directories for persistent data
    mkdir -p /var/xormon-ng/data /var/xormon-ng/files
Create configuration file
    cd /var/xormon-ng
nano ./.env
    File contents
    APP_PORT=8443
TZ=<timezone>
DB_HOST=timescaledb
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=<db_password>
DB_DATABASE=xormon
APP_SECRET=<xormon-secret>
    Replace <variables> with values:
    • <timezone> - Linux timezone, e.g. 'Europe/Prague' (see list of timezones in 'ls -l /usr/share/zoneinfo')
    • <db_password> - password used for running Timescale DB container
    • <xormon-secret> - any unique string, e.g. 'my-xormon-secret'
    Do not use the "$" character in the values, Docker Compose treats it as a variable reference.
Create Docker Compose file
    cd /var/xormon-ng
nano ./docker-compose.yml
    File contents
    services:
  timescaledb:
    image: timescale/timescaledb:latest-pg16
    init: true
    restart: unless-stopped
    shm_size: '4gb'
    environment:
      - POSTGRES_USER=${DB_USERNAME}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - TZ=${TZ}
    volumes:
      - ./data:/var/lib/postgresql/data

  xormon:
    image: xorux/xormon-ng:latest
    init: true
    restart: unless-stopped
    ulimits:
      core: 0
    depends_on:
      - timescaledb
    env_file: .env
    volumes:
      - ./files:/app/server-nest/files
    ports:
      - ${APP_PORT}:${APP_PORT}
      - 8162:8162
      - 2055:2055/udp
      - 6343:6343/udp
    The YAML indentation must be preserved exactly.
Start the containers
    cd /var/xormon-ng
docker compose up -d
Navigate to XorMon GUI
    https://<docker_host_IP>:8443/
    Default login: xormon / xormon
Notes:
  • All "docker compose" commands in this guide must be run from the /var/xormon-ng directory.
  • Using ssh-key based devices access docu in Docker.
  • Using Java in Docker docu.

XorMon upgrade

Do not use 'Application Upgrade' form in GUI!

Check the image version in the Docker Compose file, pull the new image and recreate the XorMon container.

Perform all steps under the "root" account (or prefix the commands with sudo)

Upgrade from Docker Hub

    1. Check the image version of the xormon service
    grep 'image:' /var/xormon-ng/docker-compose.yml
    • If the xormon service uses image: xorux/xormon-ng:latest, no change is needed.
    • If it uses a specific version (e.g. image: xorux/xormon-ng:x.y.z) or a locally loaded image (e.g. image: xormon:x.y.z), "docker compose pull" and "docker compose up" would not upgrade anything.
      Edit /var/xormon-ng/docker-compose.yml and set the new version (or "latest"): 
      image: xorux/xormon-ng:latest
    2. Pull the new image and recreate the container
    cd /var/xormon-ng
docker compose pull xormon
docker compose up -d
Upgrade from downloaded image

    Load the image:
    docker load < xormon-ng-docker-x.y.z.tar.gz
    Set the image of the xormon service in /var/xormon-ng/docker-compose.yml to the loaded version:
    image: xormon:x.y.z
    Recreate the container:
    cd /var/xormon-ng
docker compose up -d

Backup

Perform all steps under the "root" account (or prefix the commands with sudo)

Create a directory for the backup
    mkdir -p /tmp/xormon-backup
Save PostgreSQL and TimescaleDB version
    cd /var/xormon-ng
docker compose exec -T timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';" | tee /tmp/xormon-backup/db-version.txt
Stop XorMon
    docker compose stop xormon
Backup the database

    This step may take a long time depending on the size of the database.
    docker compose exec -T timescaledb pg_dump -U postgres --format=custom -d xormon > /tmp/xormon-backup/xormon-database.dump
Backup XorMon configuration and files
    cp /var/xormon-ng/.env /var/xormon-ng/docker-compose.yml /tmp/xormon-backup/
tar --numeric-owner -cpzf /tmp/xormon-backup/xormon-files.tar.gz -C /var/xormon-ng/files .
Start XorMon
    docker compose start xormon

Restore

The database backup can only be restored to the same version of TimescaleDB from which it was created.
The PostgreSQL version can be the same or higher.

Example:
You can restore a database backup from TimescaleDB 2.17.1 on PostgreSQL 14
to TimescaleDB 2.17.1 on PostgreSQL 14, 15, 16 or 17

Perform all steps under the "root" account (or prefix the commands with sudo)

Create directories for persistent data
    mkdir -p /var/xormon-ng/data /var/xormon-ng/files
Restore XorMon configuration files
    cp /tmp/xormon-backup/.env /tmp/xormon-backup/docker-compose.yml /var/xormon-ng/
Start PostgreSQL/TimescaleDB container

    Use the versions from the backup.
    Check the file containing the PG and TSDB versions, if you created one.
    cat /tmp/xormon-backup/db-version.txt
    Set the image of the timescaledb service in /var/xormon-ng/docker-compose.yml accordingly:
    image: timescale/timescaledb:x.y.z-pg1X
    Start only the database container:
    cd /var/xormon-ng
docker compose up -d timescaledb
Restore the database
    cd /var/xormon-ng
docker compose exec -T timescaledb psql -U postgres -c "DROP DATABASE IF EXISTS xormon;" -c "CREATE DATABASE xormon;"
docker compose exec -T timescaledb psql -U postgres -d xormon -X -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'
docker compose exec -T timescaledb psql -U postgres -d xormon -X -c "SELECT timescaledb_pre_restore()"
docker compose exec -T timescaledb psql -U postgres -d xormon -X -c "ALTER SYSTEM SET timescaledb.restoring = on;"

docker compose exec -T timescaledb pg_restore -U postgres -d xormon --no-owner --role=postgres < /tmp/xormon-backup/xormon-database.dump

docker compose exec -T timescaledb psql -U postgres -d xormon -X -c "SELECT timescaledb_post_restore()"
docker compose exec -T timescaledb psql -U postgres -d xormon -X -c "ALTER SYSTEM SET timescaledb.restoring = off;"

docker compose restart timescaledb
Restore XorMon files
    tar --numeric-owner -xpzf /tmp/xormon-backup/xormon-files.tar.gz -C /var/xormon-ng/files/
Start XorMon container
    cd /var/xormon-ng
docker compose up -d
Navigate to XorMon GUI
    https://<docker_host_IP>:8443/

TimescaleDB Upgrade

This method allows you to upgrade only the TimescaleDB version, not the PostgreSQL version.
Upgrading PostgreSQL requires data migration, as described in "PostgreSQL upgrade" section of this guide.

To upgrade TimescaleDB, simply change the image version in the Docker Compose file and recreate the container.

The database data is persisted on the file system using a bind mount, therefore recreating the container will not delete the database data.

Perform all steps under the "root" account (or prefix the commands with sudo)

Display PostgreSQL and TimescaleDB version
    cd /var/xormon-ng
docker compose exec -T timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';"
Stop XorMon
    docker compose stop xormon
Deploy new TimescaleDB container

    Install either a specific version of TimescaleDB or simply the "latest" version.
    In either case, use the same version of PostgreSQL as the original container.
    Edit the image of the timescaledb service in /var/xormon-ng/docker-compose.yml:
    image: timescale/timescaledb:latest-pg1X
    Pull the new image and recreate the container:
    cd /var/xormon-ng
docker compose pull timescaledb
docker compose up -d timescaledb
Update TimescaleDB extension
    docker compose exec -T timescaledb psql -U postgres -X -c "ALTER EXTENSION timescaledb UPDATE;"
docker compose exec -T timescaledb psql -U postgres -d xormon -X -c "ALTER EXTENSION timescaledb UPDATE;"
Display PostgreSQL and TimescaleDB version
    docker compose exec -T timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';"
Restart TimescaleDB container
    docker compose restart timescaledb
Start XorMon
    docker compose start xormon

PostgreSQL upgrade

Upgrading to a higher version of PostgreSQL requires the following steps, described earlier in this guide

Perform all steps under the "root" account (or prefix the commands with sudo)

Stop XorMon
    cd /var/xormon-ng
docker compose stop xormon
Back up the database

    Perform following steps in the "Backup" section:
    • Create a directory for the backup
    • Save PostgreSQL and TimescaleDB version
    • Backup the database
Remove the containers
    docker compose down
Delete the directory containing the database data
    rm -rf /var/xormon-ng/data
Create a new directory for the database data
    mkdir /var/xormon-ng/data
Restore database to a new container

    Set the image of the timescaledb service in /var/xormon-ng/docker-compose.yml to the same version of TimescaleDB but a new version of PostgreSQL
    Perform following steps in the "Restore" section:
    • Start PostgreSQL/TimescaleDB container
    • Restore the database
(Optional) Upgrade TimescaleDB version
Start XorMon
    docker compose up -d

XorMon Migration

    Backup up the XorMon files and database on the source virtual machine, and restore them on the new virtual machine.

Prerequisites:
  • Linux VM with the latest version of Docker Engine
  • Access to Docker Hub
  • Available ports
    • 8443 - Web UI
    • 8162 - OS Agent
    • 2055 - NetFlow
    • 6343 - sFlow
  • PostgreSQL/TimescaleDB container
  • XorMon container
  • Bind mounts for both the database data and the XorMon data
Contents:

Installation

Perform all steps under the "root" account (or prefix the commands with sudo)

Install Docker Engine

Create directories for persistent data
    mkdir -p /var/xormon-ng/data /var/xormon-ng/files
Create configuration file
    cd /var/xormon-ng
nano ./xormon-ng.env
    File contents
    APP_PORT=8443
TZ=<timezone>
DB_HOST=timescaledb
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=<db_password>
DB_DATABASE=xormon
APP_SECRET=<xormon-secret>
    Replace <variables> with values:
    • <timezone> - Linux timezone, e.g. 'Europe/Prague' (see list of timezones in 'ls -l /usr/share/zoneinfo')
    • <db_password> - password used for running Timescale DB container
    • <xormon-secret> - any unique string, e.g. 'my-xormon-secret'
    Do not use quotes around the values, "docker run --env-file" does not remove them.
Create network for containers
    docker network create xorux
Start PG16/TimescaleDB container
    source /var/xormon-ng/xormon-ng.env

docker run --network xorux --init --shm-size=4g -d --restart unless-stopped \
  -v /var/xormon-ng/data:/var/lib/postgresql/data \
  --name timescaledb -e POSTGRES_PASSWORD=$DB_PASSWORD --env-file /var/xormon-ng/xormon-ng.env \
  timescale/timescaledb:latest-pg16
Start XorMon container
    docker run --network xorux --init -d --restart unless-stopped --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v /var/xormon-ng/files:/app/server-nest/files \
  --env-file /var/xormon-ng/xormon-ng.env \
  xorux/xormon-ng:latest
Navigate to XorMon GUI
    https://<docker_host_IP>:8443/
    Default login: xormon / xormon
Notes:
  • Using ssh-key based devices access docu in Docker.
  • Using Java in Docker docu.

XorMon upgrade

Do not use 'Application Upgrade' form in GUI!

Pull the new image, then stop and remove the current container and start a new one.

Perform all steps under the "root" account (or prefix the commands with sudo)

Upgrade from Docker Hub
    docker pull xorux/xormon-ng:latest
docker stop xormon
docker rm xormon

docker run --network xorux --init -d --restart unless-stopped --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v /var/xormon-ng/files:/app/server-nest/files \
  --env-file /var/xormon-ng/xormon-ng.env \
  xorux/xormon-ng:latest
Upgrade from downloaded image
    docker stop xormon
docker rm xormon

docker load < xormon-ng-docker-x.y.z.tar.gz

docker run --network xorux --init -d --restart unless-stopped --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v /var/xormon-ng/files:/app/server-nest/files \
  --env-file /var/xormon-ng/xormon-ng.env \
  xormon:x.y.z

Backup

Perform all steps under the "root" account (or prefix the commands with sudo)

Create a directory for the backup
    mkdir -p /tmp/xormon-backup
Save PostgreSQL and TimescaleDB version
    docker exec timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';" | tee /tmp/xormon-backup/db-version.txt
Stop XorMon
    docker stop xormon
Backup the database

    This step may take a long time depending on the size of the database.
    docker exec timescaledb pg_dump -U postgres --format=custom -d xormon > /tmp/xormon-backup/xormon-database.dump
Backup XorMon configuration and files
    cp /var/xormon-ng/xormon-ng.env /tmp/xormon-backup/
tar --numeric-owner -cpzf /tmp/xormon-backup/xormon-files.tar.gz -C /var/xormon-ng/files .
Start XorMon
    docker start xormon

Restore

The database backup can only be restored to the same version of TimescaleDB from which it was created.
The PostgreSQL version can be the same or higher.

Example:
You can restore a database backup from TimescaleDB 2.17.1 on PostgreSQL 14
to TimescaleDB 2.17.1 on PostgreSQL 14, 15, 16 or 17

Perform all steps under the "root" account (or prefix the commands with sudo)

Create directories for persistent data
    mkdir -p /var/xormon-ng/data /var/xormon-ng/files
Restore XorMon configuration file
    cp /tmp/xormon-backup/xormon-ng.env /var/xormon-ng/
Create network for containers
    docker network create xorux
Start PostgreSQL/TimescaleDB container

    Use the versions from the backup.
    Check the file containing the PG and TSDB versions, if you created one.
    cat /tmp/xormon-backup/db-version.txt
    source /var/xormon-ng/xormon-ng.env

docker run --network xorux --init --shm-size=4g -d --restart unless-stopped \
  -v /var/xormon-ng/data:/var/lib/postgresql/data \
  --name timescaledb -e POSTGRES_PASSWORD=$DB_PASSWORD --env-file /var/xormon-ng/xormon-ng.env \
  timescale/timescaledb:x.y.z-pg1X
Restore the database
    docker exec timescaledb psql -U postgres -c "DROP DATABASE IF EXISTS xormon;" -c "CREATE DATABASE xormon;"
docker exec timescaledb psql -U postgres -d xormon -X -c 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'
docker exec timescaledb psql -U postgres -d xormon -X -c "SELECT timescaledb_pre_restore()"
docker exec timescaledb psql -U postgres -d xormon -X -c "ALTER SYSTEM SET timescaledb.restoring = on;"

docker exec -i timescaledb pg_restore -U postgres -d xormon --no-owner --role=postgres < /tmp/xormon-backup/xormon-database.dump

docker exec timescaledb psql -U postgres -d xormon -X -c "SELECT timescaledb_post_restore()"
docker exec timescaledb psql -U postgres -d xormon -X -c "ALTER SYSTEM SET timescaledb.restoring = off;"

docker restart timescaledb
Restore XorMon files
    tar --numeric-owner -xpzf /tmp/xormon-backup/xormon-files.tar.gz -C /var/xormon-ng/files/
Start XorMon container
    docker run --network xorux --init -d --restart unless-stopped --name xormon --ulimit core=0 \
  -p 8443:8443 -p 8162:8162 -p 2055:2055/udp -p 6343:6343/udp \
  -v /var/xormon-ng/files:/app/server-nest/files \
  --env-file /var/xormon-ng/xormon-ng.env \
  xorux/xormon-ng:latest
Navigate to XorMon GUI
    https://<docker_host_IP>:8443/

TimescaleDB Upgrade

This method allows you to upgrade only the TimescaleDB version, not the PostgreSQL version.
Upgrading PostgreSQL requires data migration, as described in "PostgreSQL upgrade" section of this guide.

To upgrade TimescaleDB, simply stop and delete the current container, then start a new one with a higher version of TimescaleDB.

The database data is persisted on the file system using a bind mount, therefore deleting the container will not delete the database data.

Perform all steps under the "root" account (or prefix the commands with sudo)

Display PostgreSQL and TimescaleDB version
    docker exec timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';"
Stop XorMon
    docker stop xormon
Remove TimescaleDB container
    docker stop timescaledb
docker rm timescaledb
Deploy new TimescaleDB container

    Install either a specific version of TimescaleDB or simply the "latest" version.
    In either case, use the same version of PostgreSQL as the original container.
    source /var/xormon-ng/xormon-ng.env

docker pull timescale/timescaledb:latest-pg1X

docker run --network xorux --init --shm-size=4g -d --restart unless-stopped \
  -v /var/xormon-ng/data:/var/lib/postgresql/data \
  --name timescaledb -e POSTGRES_PASSWORD=$DB_PASSWORD --env-file /var/xormon-ng/xormon-ng.env \
  timescale/timescaledb:latest-pg1X
Update TimescaleDB extension
    docker exec timescaledb psql -U postgres -X -c "ALTER EXTENSION timescaledb UPDATE;"
docker exec timescaledb psql -U postgres -d xormon -X -c "ALTER EXTENSION timescaledb UPDATE;"
Display PostgreSQL and TimescaleDB version
    docker exec timescaledb psql -U postgres -d xormon -c "SELECT current_setting('server_version') AS postgres, extversion AS timescaledb FROM pg_extension WHERE extname = 'timescaledb';"
Restart TimescaleDB container
    docker restart timescaledb
Start XorMon
    docker start xormon

PostgreSQL upgrade

Upgrading to a higher version of PostgreSQL requires the following steps, described earlier in this guide

Perform all steps under the "root" account (or prefix the commands with sudo)

Stop XorMon
    docker stop xormon
Back up the database

    Perform following steps in the "Backup" section:
    • Create a directory for the backup
    • Save PostgreSQL and TimescaleDB version
    • Backup the database
Remove the TimescaleDB container
    docker stop timescaledb
docker rm timescaledb
Delete the directory containing the database data
    rm -rf /var/xormon-ng/data
Create a new directory for the database data
    mkdir /var/xormon-ng/data
Restore database to a new container

    Start a new timescaledb container with the same version of TimescaleDB but a new version of PostgreSQL
    Perform following steps in the "Restore" section:
    • Start PostgreSQL/TimescaleDB container
    • Restore the database
(Optional) Upgrade TimescaleDB version
Start XorMon
    docker start xormon

XorMon Migration

    Backup up the XorMon files and database on the source virtual machine, and restore them on the new virtual machine.

Dernière mise à jour :