Full Docker Guide

Overview

This guide covers running DataForeman with Docker Compose. There are two ways to install it, depending on whether you want prebuilt images or your own local builds:

• Prebuilt images (recommended for most users) — no git required, just three downloaded files. Updates are a simple docker compose pull. See the Download page for the exact commands.
• Git clone / build from source — for developers who want to modify the code or track develop directly. Uses npm start, which builds core, front, connectivity, and broker locally via docker-compose.dev.yml.

This guide focuses on the git clone method, since the prebuilt-image quick start is already covered on the Download page.

Prerequisites

Before you begin, ensure your system meets the following requirements:

• Docker 20.10 or higher
• Docker Compose 2.0 or higher
• Node.js 22+ and Git (for the git-clone method described here)
• Operating System: Linux, macOS, or Windows with WSL2
• Minimum Resources:
  • 4 GB RAM (8 GB recommended)
  • 20 GB available disk space
  • 2 CPU cores minimum

Quick Start

The fastest way to get DataForeman running from a git clone:

1
2
3

git clone https://github.com/orionK-max/DataForeman.git
cd DataForeman
npm start

npm start builds the images locally the first time (via docker-compose.dev.yml) and starts the full stack.

Access the application at http://localhost:8080

Default credentials:

• Email: ADMIN_EMAIL (default: admin@example.com)
• Password: from ADMIN_PASSWORD in .env (default: password)

⚠️ Important: Change the default password immediately after first login!

Installation Steps

1. Clone the Repository

1
2

git clone https://github.com/orionK-max/DataForeman.git
cd DataForeman

2. Configure Environment Variables

Create a .env file from the template:

1

cp .env.example .env

Edit .env to customize your installation. The most important values to change:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Security — change these before exposing to a network
JWT_SECRET=change-me-in-production
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_secure_password

# Database passwords
PGPASSWORD=your_secure_db_password
TSDB_PASSWORD=your_secure_tsdb_password

# Database hosts — use service names for Docker Compose (do not change to localhost)
PGHOST=db
PGPORT=5432
PGUSER=postgres
PGDATABASE=dataforeman

TSDB_HOST=tsdb
TSDB_PORT=5432
TSDB_USER=tsdb
TSDB_DATABASE=telemetry

Note: PGHOST=db and TSDB_HOST=tsdb refer to Docker Compose service names — leave them as-is for a standard Docker deployment.

3. Start the Services

Launch all containers in detached mode:

1

npm start

npm start automatically runs fix-permissions.sh before starting containers, so no separate permission step is needed. Permissions fix the logs/ and var/ directories that containers write to.

4. Verify Installation

Check that all services are running:

1

docker compose ps

You should see all services in the “Up” state.

What’s Included

The Docker Compose setup includes the following services:

Configuration

Port Configuration

Default ports used by DataForeman:

To change ports, edit the .env file and restart:

1
2

docker compose down
docker compose up -d

Volume Management

Data is persisted in Docker named volumes. Docker prefixes volumes with the project name (dataforeman):

1
2
3
4
5
6
7
8

# List DataForeman volumes
docker volume ls | grep dataforeman

# Inspect the main database volume
docker volume inspect dataforeman_db-data

# Inspect the time-series database volume
docker volume inspect dataforeman_tsdb-data

Upgrades

Upgrade to Latest Version (git clone install)

Since this install builds images locally from source, updating means pulling the new code and rebuilding:

1. Check GitHub Releases for the latest version tag (e.g. vX.X.X)

2. Fetch and check out the new version:

1
2

git fetch --tags
git checkout vX.X.X

3. Rebuild and restart:

1

npm run start:rebuild

Database migrations run automatically when core starts — no manual migration step is needed. Your data (databases, dashboards, configurations) is preserved.

To roll back: git checkout vX.X.X && npm run start:rebuild

Prebuilt-image installs: if you followed the Download page’s curl-based setup instead, updating is simpler — just docker compose pull && docker compose up -d. No git needed.

Database Migrations

Migrations run automatically on startup. Check logs:

1

docker compose logs core | grep migration

Backup and Restore

Backup Database

Create a backup of the main PostgreSQL database:

1

docker compose exec db pg_dump -U postgres dataforeman > backup_$(date +%Y%m%d).sql

Restore Database

Restore from a backup file:

1

cat backup_20250131.sql | docker compose exec -T db psql -U postgres dataforeman

Backup Volumes

Backup the main database volume:

1
2

docker run --rm -v dataforeman_db-data:/data -v $(pwd):/backup \
  alpine tar czf /backup/postgres_backup.tar.gz -C /data .

Troubleshooting

Services Won’t Start

Check logs:

1

docker compose logs

Check specific service:

1
2

docker compose logs db
docker compose logs core

Port Already in Use

If port 8080 is already in use by another application:

1. Edit .env and change FRONT_PORT to a different value (e.g. FRONT_PORT=8090)
2. Restart: docker compose down && docker compose up -d

Database Connection Issues

Reset database:

1
2
3

docker compose down
docker volume rm dataforeman_db-data
docker compose up -d

⚠️ Warning: This deletes all data!

Permission Denied Errors

Run the permission fix script:

1

./fix-permissions.sh

This script fixes permissions on the logs/ and var/ directories that containers write to. It also sets logs/postgres/ to world-writable so the PostgreSQL container (which runs as a different UID) can write its log files.

Container Keeps Restarting

Check container logs for errors:

1

docker compose logs --tail=100 <service-name>

Common issues:

• Insufficient memory (increase Docker memory limit)
• Missing environment variables (check .env)
• Port conflicts (change ports in .env)

Getting Help

If you encounter issues:

1. Check the Troubleshooting section
2. Review logs: docker compose logs
3. Visit GitHub Discussions
4. Report bugs on GitHub Issues