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
4

git clone https://github.com/orionK-max/DataForeman.git
cd dataforeman
./fix-permissions.sh
npm start

Access the application at http://localhost:8080

Default credentials:

• Email: admin@example.com
• Password: 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:

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

# Database Configuration
PGHOST=localhost
PGPORT=5432
PGUSER=postgres
PGPASSWORD=your_secure_password_here
PGDATABASE=dataforeman

# TimescaleDB Configuration
TSDB_HOST=localhost
TSDB_PORT=5433
TSDB_USER=tsdb
TSDB_PASSWORD=your_secure_password_here
TSDB_DATABASE=telemetry

# Application Configuration
PORT=3000
FRONT_PORT=8080

3. Set File Permissions

Run the permission fix script:

1
2

chmod +x fix-permissions.sh
./fix-permissions.sh

This ensures proper permissions for data directories and log files.

4. Start the Services

Launch all containers in detached mode:

1

npm start

or

1

docker compose up -d

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:

• ✅ PostgreSQL Database - Main data storage
• ✅ TimescaleDB Extension - Time-series data optimization
• ✅ NATS Message Bus - Internal service communication
• ✅ Core API Service - Backend API
• ✅ Connectivity Drivers - Protocol handlers (OPC UA, Modbus, etc.)
• ✅ React Frontend - Web interface
• ✅ Log Rotation - Automated log management
• ✅ Caddy Reverse Proxy (optional) - HTTPS and routing

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 volumes:

1
2
3
4
5

# List volumes
docker volume ls | grep dataforeman

# Inspect a volume
docker volume inspect dataforeman_postgres_data

Upgrades

Upgrade to Latest Version

1. Pull the latest code:

1

git pull origin main

2. Pull new Docker images:

1

docker compose pull

3. Restart services:

1
2

docker compose down
docker compose up -d

Database Migrations

Migrations run automatically on startup. Check logs:

1

docker compose logs api | grep migration

Backup and Restore

Backup Database

Create a backup of your PostgreSQL database:

1

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

Restore Database

Restore from a backup file:

1

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

Backup Volumes

Backup all data volumes:

1
2

docker run --rm -v dataforeman_postgres_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 postgres
docker compose logs api

Port Already in Use

If port 8080 is already in use by other application:

1. Edit .env and change APP_PORT
2. Restart: docker compose down && docker compose up -d

Database Connection Issues

Reset database:

1
2
3

docker compose down
docker volume rm dataforeman_postgres_data
docker compose up -d

⚠️ Warning: This deletes all data!

Permission Denied Errors

Run the permission fix script:

1

./fix-permissions.sh

Or manually:

1
2

sudo chown -R $USER:$USER ./data
sudo chmod -R 755 ./data

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