Setup

This guide walks you through setting up umh-core with Docker Compose, starting with a minimal configuration and building up to a full production-ready stack.

Prerequisites

• Docker and Docker Compose installed on your system

• Basic familiarity with the command line

Minimal Setup

1. Find the latest version on the Releases page and replace <VERSION> with your selected version.

2. Save this in docker-compose.yaml.

services:
  umh:
    image: management.umh.app/oci/united-manufacturing-hub/umh-core:<VERSION> # TODO: change this
    restart: unless-stopped
    volumes:
      - umh-data:/data
    environment:
      - AUTH_TOKEN=your-auth-token # TODO: change this
      - LOCATION_0=your-location # TODO: change this
      - RELEASE_CHANNEL=stable
      - API_URL=https://management.umh.app/api

volumes:
  umh-data: {}

Then run:

docker compose up -d

This achieves the same result as the docker cli commands, but the configuration is now documented in a file that you can version control and extend.

Adding TimescaleDB and Grafana

While umh-core can operate standalone, most deployments benefit from persistent storage and visualization capabilities.

TimescaleDB

TimescaleDB is PostgreSQL with an extension optimized for time-series data. Manufacturing data is inherently time-series: sensor readings, production counts, and machine states all have timestamps. It is an optimal solution to store this kind of data.

PgBouncer

PgBouncer is a connection pooler that manages database connections efficiently.

umh-core bridges can create many simultaneous connections to the database. PostgreSQL has a limited number of connections it can handle (typically 100 by default). Without connection pooling, a busy system can exhaust this limit, causing connection failures. PgBouncer multiplexes many client connections onto a pool of database connections. This allows hundreds of application connections while using only a few actual PostgreSQL connections.

In this configuration applications connect to PgBouncer on port 5432 and PgBouncer connects to TimescaleDB internally.

Adding TimescaleDB

Below are the changes to be made to the base configuration to deploy TimescaleDB and PgBouncer together with umh-core.

services:
  umh:
    image: management.umh.app/oci/united-manufacturing-hub/umh-core:<VERSION> # TODO: change this
    restart: unless-stopped
    volumes:
      - umh-data:/data
    environment:
      - AUTH_TOKEN=your-auth-token # TODO: change this
      - RELEASE_CHANNEL=stable
      - API_URL=https://management.umh.app/api
      - LOCATION_0=your-location # TODO: change this

+   pgbouncer:
+     image: docker.io/edoburu/pgbouncer:v1.24.1-p1
+     restart: unless-stopped
+     environment:
+       - DB_NAME=umh
+       - DB_USER=postgres     # TODO: change this, it has to be the same as `POSTGRES_USER` for timescaledb below
+       - DB_PASSWORD=postgres # TODO: change this, it has to be the same as `POSTGRES_PASSWORD` for timescaledb below
+       - DB_HOST=timescaledb
+       - AUTH_TYPE=scram-sha-256
+     ports:
+       - 5432:5432
+     healthcheck:
+       test: ["CMD-SHELL", "pg_isready -h pgbouncer"]
+       interval: 10s
+       timeout: 5s
+       retries: 5
+     depends_on:
+       timescaledb:
+         condition: service_healthy
+     networks:
+       - default
+       - timescaledb-network

+   timescaledb:
+     image: management.umh.app/oci/timescale/timescaledb:2.24.0-pg17
+     restart: unless-stopped
+     environment:
+       - POSTGRES_DB=umh
+       - POSTGRES_USER=postgres     # TODO: change this
+       - POSTGRES_PASSWORD=postgres # TODO: change this
+     volumes:
+       - timescaledb-data:/var/lib/postgresql/data
+     healthcheck:
+       test: ["CMD-SHELL", "pg_isready -h timescaledb"]
+       interval: 10s
+       timeout: 5s
+       retries: 5
+     networks:
+       - timescaledb-network

+ networks:
+   default:
+   timescaledb-network:
+     internal: true

  volumes:
    umh-data: {}
+   timescaledb-data: {}

This declares:

• 2 Services called pgbouncer and timescaledb: PgBouncer acts as a proxy to TimescaleDB. This means the Credentials have to match between these two Services. Healthchecks ensure that the Services are started in order. timescaledb is isolated in the Network timescaledb-network. pgbouncer is both in the default and the timescaledb-network. This makes PgBouncer the only Service which can talk to TimescaleDB directly.

• 2 Networks called timescaledb-network and default: Without the Network section the Network default is always created by default. Services use the Network default if no explicit Network configuration is provided. The timescaledb-network is configured to be internal which means Services can't reach the internet or any Service outside this Network if they are only connected through this Network.

• 1 Volume called timescaledb-data: This is where TimescaleDB stores its data.

Grafana

Grafana is an open-source visualization platform. It can for example connect to TimescaleDB and allows you to build dashboards showing real-time and historical data.

Adding Grafana

Below are the changes to be made to the base configuration to deploy Grafana together with umh-core.

  services:
    umh:
      image: management.umh.app/oci/united-manufacturing-hub/umh-core:<VERSION> # TODO: change this
      restart: unless-stopped
      volumes:
        - umh-data:/data
      environment:
        - AUTH_TOKEN=your-auth-token # TODO: change this
        - RELEASE_CHANNEL=stable
        - API_URL=https://management.umh.app/api
        - LOCATION_0=your-location # TODO: change this

+   grafana:
+     image: management.umh.app/oci/grafana/grafana:12.3.0
+     restart: unless-stopped
+     ports:
+       - 3000:3000
+     volumes:
+       - grafana-data:/var/lib/grafana
+     healthcheck:
+       test: ["CMD-SHELL", "curl --fail http://grafana:3000/api/health"]
+       interval: 10s
+       timeout: 5s
+       retries: 3

  volumes:
    umh-data: {}
+   grafana-data: {}

umh-core + Grafana + PgBouncer + TimescaleDB

To get the most out of Grafana it should be deployed together with TimescaleDB to have a good and persistent data source.

IMPORTANT: Do not forget to change Database credentials before using this in production!

services:
  umh:
    image: management.umh.app/oci/united-manufacturing-hub/umh-core:<VERSION> # TODO: change this
    restart: unless-stopped
    volumes:
      - umh-data:/data
    environment:
      - AUTH_TOKEN=your-auth-token # TODO: change this
      - RELEASE_CHANNEL=stable
      - API_URL=https://management.umh.app/api
      - LOCATION_0=your-location # TODO: change this

  grafana:
    image: management.umh.app/oci/grafana/grafana:12.3.0
    restart: unless-stopped
    ports:
      - 3000:3000
    volumes:
      - grafana-data:/var/lib/grafana
    healthcheck:
      test: ["CMD-SHELL", "curl --fail http://grafana:3000/api/health"]
      interval: 10s
      timeout: 5s
      retries: 3

  pgbouncer:
    image: docker.io/edoburu/pgbouncer:v1.24.1-p1
    restart: unless-stopped
    environment:
      - DB_NAME=umh
      - DB_USER=postgres     # TODO: change this, it has to be the same as `POSTGRES_USER` for timescaledb below
      - DB_PASSWORD=postgres # TODO: change this, it has to be the same as `POSTGRES_PASSWORD` for timescaledb below
      - DB_HOST=timescaledb
      - AUTH_TYPE=scram-sha-256
    ports:
      - 5432:5432
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h pgbouncer"]
      interval: 10s
      timeout: 5s
      retries: 5
    depends_on:
      timescaledb:
        condition: service_healthy
    networks:
      - default
      - timescaledb-network

  timescaledb:
    image: management.umh.app/oci/timescale/timescaledb:2.24.0-pg17
    restart: unless-stopped
    environment:
      - POSTGRES_DB=umh
      - POSTGRES_USER=postgres     # TODO: change this
      - POSTGRES_PASSWORD=postgres # TODO: change this
    volumes:
      - timescaledb-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h timescaledb"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - timescaledb-network

networks:
  default:
  timescaledb-network:
    internal: true

volumes:
  umh-data: {}
  timescaledb-data: {}
  grafana-data: {}

Starting the Stack

Once the configuration is done you can start the full application stack by using docker compose up -d. There are a lot of useful commands for docker compose for example:

• docker compose ps: check the running state of all services

• docker compose stats: check resource usage of all services

• docker compose pull: attempt to pull new versions of all images used in the docker-compose.yaml

For more refer to the official Docker Compose documentation.

Once started, you can access:

• Grafana at http://localhost:3000 (default login: admin/admin)

• PostgreSQL through PgBouncer at localhost:5432