Full Docker Guide

Overview

This comprehensive guide walks you through deploying DataForeman using Docker Compose. Whether you’re setting up a development environment, staging server, or production instance, this guide covers everything you need to know.

Prerequisites

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

• Docker 20.10 or higher
• Docker Compose 2.0 or higher
• 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:

1
2
3

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

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.

5. 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

DataForeman is built from source — there are no pre-built images to pull. The correct upgrade process is:

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

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