---
title: "Platform | Installation and Upgrade Docker | N3uron KB V1.22"
slug: "platform-installation-and-upgrade-docker"
description: "N3uron is an Industrial Edge Platform for IIoT and DataOps that enables seamless integration between the industrial plant floor and business applications,"
updated: 2026-05-22T09:59:42Z
published: 2026-05-22T09:59:42Z
canonical: "docs.n3uron.com/platform-installation-and-upgrade-docker"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.n3uron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

**Docker** is a containerization platform that enables you to run the **N3uron IIoT & DataOps Platform** within a container. A container is a lightweight, standalone executable package that bundles an application with everything it needs to run. Our official container image is available on [DockerHub](https://hub.docker.com/r/n3uronhub/n3uron) and contains all the components and modules of N3uron**.**

## Getting Started

### Launch a N3uron instance for testing

Your can launch an **ephemeral** N3uron instance for testing using the [Docker CLI](https://docs.docker.com/reference/cli/docker/) with the following command:

```bash
docker run -d --name n3uron -p 8003:8003 n3uronhub/n3uron:v1.22
```

The N3uron WebUI will now be accessible at [http://localhost:8003.](http://localhost:8003.)

### Launch a N3uron instance with data persistence

Create the Docker volumes to ensure data persistence:

```bash
docker volume create n3_config
docker volume create n3_data
docker volume create n3_licenses
docker volume create n3_log
```

Run the container with the volumes mounted:

```bash
docker run -d \
    --name n3uron \
    --hostname docker-node01 \ # Set a hostname for licensing
    -e ADMIN_PASSWORD=verysecurepassword \
    -p 8003:8003 \ # HTTP WebUI
    -p 8443:8443 \ # HTTPS WebUI
     # Add more ports as needed
    -v n3_config:/opt/n3uron/config \
    -v n3_data:/opt/n3uron/data \
    -v n3_log:/opt/n3uron/log \
    -v n3_licenses:/opt/n3uron/licenses \
    n3uronhub/n3uron:v1.22
```

Open [http://localhost:8003](http://localhost:8003) or [http://<node-ip>:8003](http://&lt;node-ip&gt;:8003) to access the WebUI and log into the platform using the user **admin** and the password provided as environment variable.

### Using Docker Compose

[Docker Compose](https://docs.docker.com/compose/) is the preferred and recommended method for defining, configuring, and deploying containers in Docker.

This is the most basic compose.yaml file to deploy N3uron using Docker Compose

```yaml
services:
  n3uron:
    image: n3uronhub/n3uron:v1.22
    hostname: docker-node01 # Set a hostname for licensing
    environment:
      - ADMIN_PASSWORD=verysecurepassword
    ports:
      - 8003:8003 # HTTP WebUI
      # Add more ports as needed
    volumes:
      - config:/opt/n3uron/config
      - data:/opt/n3uron/data
      - licenses:/opt/n3uron/licenses
      - log:/opt/n3uron/log
    restart: always

volumes:
  config:
  data:
  licenses:
  log:
```

Use the following command to deploy and run the container:

```bash
docker compose up -d
```

Open [http://localhost:8003](http://localhost:8003) or [http://<node-ip>:8003](http://&lt;node-ip&gt;:8003) to access the WebUI and log into the platform using the password provided as environment variable.

### Upgrading a N3uron container instance

> [!NOTE]
> Note:
> 
> Before proceeding with an upgrade, ensure that the Support and Maintenance (S&M) of your license is active for the version you plan to install.

To upgrade a running instance of N3uron follow the steps below:

**Step 1 (Optional):** Create a node backup to restore the N3uron configuration if something goes wrong during the update. You can find the steps to perform a node backup in the [Backup and Restore](/v122/docs/platform-backup-and-restore) section.

**Step 2 (Recommended):** Review the [release notes](https://n3uron.com/releasenotes-v122/) for the target N3uron version to identify any breaking changes that might affect your current configuration.

> [!NOTE]
> Note:
> 
> It is strongly recommended to apply the update in a testing environment before implementing it in the production environment.

**Step 3:** Pull the desired version of N3uron from [DockerHub](https://hub.docker.com/r/n3uronhub/n3uron):

```bash
docker pull n3uronhub/n3uron:vX.X.X
```

**Step 4:** Stop and remove the container (data will persist in the volumes). In this example, we assume the container is named “n3uron”:

```plaintext
docker stop n3uron
docker rm n3uron
```

**Step 5:** Run the command documented in the [previous section](/v122/docs/docker#launch-a-n3uron-instance-with-data-persistence) to launch a new N3uron container with the desired version.

**Step 6:** Log into the WebUI to ensure everything is running correctly. If you encounter any issues during the upgrade, you can revert to the previous version of N3uron by following the same steps outlined in this section.

## Examples

### Using secrets to store credentials

Our container image supports using [Docker Secrets](https://docs.docker.com/compose/how-tos/use-secrets/) to securely provide the initial admin password by setting the ADMIN_PASSWORD_FILE environment variable.

Create a text file named passwd.txt in the same directory as your compose.yaml:

```bash
echo "your_secure_password" > passwd.txt
```

Example compose.yaml using secrets:

```yaml
secrets:
  admin_password:
    file: passwd.txt # Path to file containing the password

services:
  n3uron:
    image: n3uronhub/n3uron:v1.22
    hostname: docker-node01
    environment:
      - ADMIN_PASSWORD_FILE=/run/secrets/admin_password
    ports:
      - 8003:8003 # HTTP WebUI
    volumes:
      - config:/opt/n3uron/config
      - data:/opt/n3uron/data
      - licenses:/opt/n3uron/licenses
      - log:/opt/n3uron/log
    # Grant access to the secret, docker automatically mounts
    # the secret at /run/secrets/<secret-name> inside the container
    secrets:
      - admin_password
    restart: always

volumes:
  config:
  data:
  licenses:
  log:
```

### Deployment with Historian database

#### EmbeddedDB

The N3uron Docker image includes a built-in and ready-to-use embedded database for the Historian module; no external containers are required.

#### MongoDB

This example shows how to deploy a standalone N3uron instance with a MongoDB database for the data [Historian](/v122/docs/historian)

**Step 1:** Create a compose.yaml file with the following content:

```yaml
services:
  n3uron:
    image: n3uronhub/n3uron:v1.22
    hostname: docker-node01 # Set a hostname for licensing
    environment:
      - ADMIN_PASSWORD=verysecurepassword
    ports:
     - 8003:8003 # HTTP WebUI
     - 3001:3001 # Inbound Links
     # Add more ports as needed
    volumes:
      - config:/opt/n3uron/config
      - data:/opt/n3uron/data
      - licenses:/opt/n3uron/licenses
      - log:/opt/n3uron/log
    restart: always

  mongo:
    image: mongo:8
    command: |
      --quiet
      --bind_ip 0.0.0.0
      --wiredTigerCollectionBlockCompressor zstd
      --setParameter diagnosticDataCollectionEnabled=false
    ports:
       - 27017:27017
    volumes:
      - mongo_data:/data/db
    restart: always

volumes:
  config:
  data:
  licenses:
  log:
  mongo_data:
```

**Step 2:** Deploy the containers using the following command:

```bash
docker compose up -d
```

**Step 3:** Open [http://localhost:8003](http://localhost:8003/) or [http://<node-ip>:8003](http://&lt;node-ip&gt;:8003) to access the WebUI and log into the platform using the password provided as environment variable.

> [!NOTE]
> Note:
> 
> When configuring the Historian instance, enter the name of the service in the **Host** field. In the example above, we used “**mongo”** as the name of the service.
> 
> ![](https://cdn.document360.io/54093ab5-6b22-4542-a265-04377931f11a/Images/Documentation/image(186).png)

#### TimescaleDB

This example shows how to deploy N3uron with a TimescaleDB database for [Historian](/v122/docs/historian)

**Step 1:** Create a compose.yaml file with the following content:

```yaml
services:
  n3uron:
    image: n3uronhub/n3uron:v1.22
    hostname: docker-node01 # Set a hostname for licensing
    environment:
      - ADMIN_PASSWORD=verysecurepassword
    ports:
     - 8003:8003 # HTTP WebUI
     - 3001:3001 # Inbound Links
     # Add more ports as needed
    volumes:
      - config:/opt/n3uron/config
      - data:/opt/n3uron/data
      - licenses:/opt/n3uron/licenses
      - log:/opt/n3uron/log
    restart: always

  timescale:
    image: timescale/timescaledb-ha:pg18
    environment:
      - POSTGRES_PASSWORD=password
      - PGDATA=/pgdata
    ports:
      - 5432:5432
    volumes:
      - timescale_data:/pgdata
    restart: always

volumes:
  config:
  data:
  licenses:
  log:
  timescale_data:
```

**Step 2:** Deploy the containers using the following command:

```bash
docker compose up -d
```

**Step 3:** Open [http://localhost:8003](http://localhost:8003/) or [http://<node-ip>:8003](http://&lt;node-ip&gt;:8003) to access the WebUI and log into the platform using the user **admin** and the password provided as environment variable.