Docker Compose Deployment

This page covers deploying all NetXMS components using Docker Compose: the monitoring server, agent, web management console, and a PostgreSQL database.

Docker images are currently available for linux/amd64 only. ARM builds are pending official ARM packages from Raden Solutions.

Always pin a specific version tag (e.g., 6.1.0) in production. Never use :latest.

Overview

The Docker Compose deployment provides a complete NetXMS monitoring stack:

PostgreSQL database — stores all monitoring data and configuration
NetXMS server — the core monitoring engine
NetXMS agent — collects metrics from the host (also used by the server for web service checks, SSH, etc.)
Web management console — browser-based management interface (Jetty-based, HTTPS on port 8443)

All components are available as pre-built images from GitHub Container Registry (GHCR):

Image Description

Image	Description
`ghcr.io/netxms/server:<version>`	Core monitoring server
`ghcr.io/netxms/agent:<version>`	Monitoring agent
`ghcr.io/netxms/web:<version>`	Web management console

ghcr.io/netxms/server:<version>

Core monitoring server

ghcr.io/netxms/agent:<version>

Monitoring agent

ghcr.io/netxms/web:<version>

Web management console

Prerequisites

Docker Engine 20.10 or later
Docker Compose v2
Git (to clone the deployment example repository)

Quick Start

Clone the official NetXMS Docker repository and start the deployment:

git clone https://github.com/netxms/docker.git
cd docker/deployment-example
cp .env.example .env

Edit the .env file to set your desired version and database credentials:

NETXMS_VERSION=6.1.0
POSTGRES_USER=netxms
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=netxms

If you changed the database credentials in .env, update them in conf/server/netxmsd.conf as well.

Start all services:

docker compose up -d

This starts PostgreSQL, initializes the database schema, and brings up the server, agent, and web console.

During database initialization a random password is generated for the admin user and printed to the log of the init container. Retrieve it with:

docker compose logs init

Access the web interface at https://localhost:8443 and log in as admin with the generated password. You will be asked to change it on first login.

Compose File

The deployment uses the following compose.yaml:

services:
  db:
    image: postgres:17
    restart: unless-stopped
    env_file:
      - .env
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U netxms"]
      interval: 10s
      timeout: 5s
      retries: 5
    volumes:
      - db-data:/var/lib/postgresql/data
      - ./conf/pg/postgresql.conf:/etc/postgresql/postgresql.conf

  server:
    image: ghcr.io/netxms/server:${NETXMS_VERSION}
    platform: linux/amd64
    hostname: server
    depends_on:
      db:
        condition: service_healthy
      agent:
        condition: service_started
      init:
        condition: service_completed_successfully
    volumes:
      - ./conf/server/netxmsd.conf:/etc/netxmsd.conf
      - ./conf/server/etc-netxms:/etc/netxms
      - server-var:/var/lib/netxms
    ports:
      - 48920:4701
      - 48921:4703

  agent:
    image: ghcr.io/netxms/agent:${NETXMS_VERSION}
    platform: linux/amd64
    volumes:
      - ./conf/agent/nxagentd.conf:/etc/nxagentd.conf
      - agent-var:/var/lib/netxms

  web:
    image: ghcr.io/netxms/web:${NETXMS_VERSION}
    ports:
      - 8443:8443

  init:
    image: ghcr.io/netxms/server:${NETXMS_VERSION}
    platform: linux/amd64
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - ./conf/server/netxmsd.conf:/etc/netxmsd.conf
    entrypoint: /dbinit.sh

volumes:
  db-data:
  server-var:
  agent-var:

Services

db: PostgreSQL 17 database with a health check. Data is persisted in the db-data volume. A custom postgresql.conf can be mounted for performance tuning.
server: NetXMS monitoring server. Starts only after the database is healthy, the agent is running, and the init service has completed successfully. Server ports 4701 (client connections) and 4703 (agent tunnels) are mapped to host ports 48920 and 48921 respectively.
agent: Monitoring agent. Collects system metrics and is also used by the server for web service checks, SSH connections, and other proxy operations.
web: Web management console running on Jetty. Exposes HTTPS on port 8443 (HTTP on 8080 is available but not exposed by default in the compose file).
init: One-shot service that initializes the database schema on first run. Uses the same server image with the /dbinit.sh entrypoint.

Configuration

Environment File (.env)

Variable Description

Variable	Description
`NETXMS_VERSION`	NetXMS version to deploy (e.g., `6.1.0`). Required.
`POSTGRES_USER`	PostgreSQL username. Default: `netxms`.
`POSTGRES_PASSWORD`	PostgreSQL password. Change this for production.
`POSTGRES_DB`	PostgreSQL database name. Default: `netxms`.

NETXMS_VERSION

NetXMS version to deploy (e.g., 6.1.0). Required.

POSTGRES_USER

PostgreSQL username. Default: netxms.

POSTGRES_PASSWORD

PostgreSQL password. Change this for production.

POSTGRES_DB

PostgreSQL database name. Default: netxms.

Server Configuration

The server configuration file is mounted from conf/server/netxmsd.conf:

LogFile={stdout}
DBDriver=pgsql
DBServer=db
DBName=netxms
DBLogin=netxms
DBPassword=netxms
ManagementAgentAddress=agent

Key parameters:

LogFile={stdout} — sends logs to Docker’s log driver instead of a file
DBServer=db — uses the Docker Compose service name for DNS resolution
ManagementAgentAddress=agent — points to the agent container for web service checks, SSH, etc.

Additional server files (TLS certificates, custom configuration) can be placed in conf/server/etc-netxms/, which is mounted to /etc/netxms inside the container.

Agent Configuration

The agent configuration file is mounted from conf/agent/nxagentd.conf:

LogFile={stdout}
MasterServers=server

The MasterServers parameter uses the Docker Compose service name server for automatic DNS resolution.

PostgreSQL Configuration

A custom PostgreSQL configuration can be mounted from conf/pg/postgresql.conf for performance tuning. The deployment example includes a tuned configuration with settings appropriate for a dedicated monitoring database.

Web Interface SSL

The web console uses HTTPS by default with a self-signed certificate. To use your own SSL certificate:

Create a PKCS#12 keystore containing your certificate and private key

Mount it into the web container and set the keystore password:

services:
  web:
    volumes:
      - /path/to/your/keystore.p12:/var/lib/jetty/etc/keystore.p12
    environment:
      - KEYSTORE_PASSWORD=your_keystore_password

The JAVA_OPTIONS environment variable can be used for JVM tuning (e.g., -Xmx1g to set maximum heap size).

Startup and Verification

Start the deployment:

docker compose up -d

Check that all services are running:

docker compose ps

View logs for a specific service:

docker compose logs server
docker compose logs web
docker compose logs db

Access the web management console at https://localhost:8443 and log in as admin with the password generated during database initialization (docker compose logs init). You will be asked to change it on first login.

Database Operations

The full compose.yaml in the official Docker repository includes additional utility services for database maintenance. These are run as one-off commands:

# Initialize database (runs automatically on first start)
docker compose run --rm init

# Check database integrity
docker compose run --rm check

# Upgrade database schema (after updating NETXMS_VERSION in .env)
docker compose run --rm upgrade

# Unlock database (if locked after an unclean shutdown)
docker compose run --rm unlock

# Background schema upgrade (can run while the server is already running)
docker compose run --rm background-upgrade

The background-upgrade service uses a Compose profile and is excluded from docker compose up. Run it manually when needed.

Upgrading NetXMS

To upgrade to a new version:

Stop the running services:
```
docker compose down
```
Update the NETXMS_VERSION in your .env file to the new version
Pull the new images:
```
docker compose pull
```
Upgrade the database schema:
```
docker compose run --rm upgrade
```
Start the services:
```
docker compose up -d
```

Troubleshooting

Database Connection Issues

Check PostgreSQL service health: docker compose logs db
Verify that database credentials in netxmsd.conf match those in the .env file
Ensure the db service is healthy before the server starts: docker compose ps

Port Conflicts

Port 8443 (web console) or mapped server ports (48920, 48921) may conflict with other services on the host
Change the host port mappings in compose.yaml if needed (e.g., 9443:8443)

Web Interface Not Accessible

Check the web container logs: docker compose logs web
Verify that the server is running and healthy
Ensure port 8443 is not blocked by a host firewall

Agent Connection Problems

Check agent logs: docker compose logs agent
Verify the MasterServers setting in nxagentd.conf matches the server service name
Check network connectivity between containers: docker compose exec agent ping server

Viewing All Logs

To follow logs from all services simultaneously:

docker compose logs -f