Full Windows Guide

Complete guide to installing and running DataForeman on Windows. Covers installer setup, configuration, troubleshooting, and advanced options for Windows environments.

Overview

This guide provides comprehensive instructions for installing and running DataForeman on Windows systems. Whether you’re using the installer or setting up manually, this guide covers everything you need to know.

Prerequisites

Docker Desktop Required

DataForeman requires Docker Desktop to be installed on Windows.

Installing Docker Desktop

  1. Download Docker Desktop from docker.com
  2. Run the installer and follow the installation wizard
  3. Wait for installation to complete

WSL Update (If Required)

Docker Desktop may prompt you to update WSL (Windows Subsystem for Linux). If this happens:

  1. Open PowerShell as Administrator

    • Right-click the Start button
    • Select “Windows PowerShell (Admin)” or “Terminal (Admin)”

  2. Run the WSL update command:

    1

    wsl --update

  3. Wait for the update to complete (internet connection required)

    • This may take several minutes depending on your connection speed

  4. Restart Docker Engine

    • Open Docker Desktop
    • Click “Restart Docker”
    • Wait for the restart to complete

  5. Verify Docker is running

    • Wait until it shows empty list of containers (this may take several minutes)

System Requirements

Before you begin, ensure your Windows system meets these requirements:

  • Operating System: Windows 10 (version 1809 or later) or Windows 11
  • Architecture: 64-bit (x64)
  • RAM: 4 GB minimum (8 GB recommended)
  • Disk Space: 20 GB available
  • Administrator Access: Required for installation
  • Docker Desktop: Installed and running

Quick Start with Installer

The easiest way to get DataForeman running on Windows:

  1. Download the latest installer from GitHub Releases
  2. Run the setup executable (DataForeman-Setup.exe)
  3. Launch DataForeman from the Start Menu
  4. Access the application at http://localhost:8080

Default credentials:

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

Installation Methods

Step 1: Download the Installer

  1. Visit the GitHub Releases page
  2. Download the latest DataForeman-Setup-x64.exe

Step 2: Run the Installer

  1. Double-click the installer file
  2. If Windows SmartScreen appears, click “More info” → “Run anyway”
  3. Click “Yes” when prompted by User Account Control

Step 3: Installation Wizard

  1. Welcome Screen: Click “Next”
  2. License Agreement: Accept and click “Next”
  3. Installation Location:
    • Default: C:\Program Files\DataForeman
    • Click “Browse” to change location
    • Click “Next”
  4. Components:
    • ✅ Core Application
    • ✅ Desktop Shortcut
    • ✅ Start Menu Items
  5. Install: Click “Install” to begin

Step 4: Complete Installation

  1. Wait for installation to complete (~2-5 minutes)
  2. Click “Finish”
  3. Choose “Launch DataForeman now” if desired

Step 5: First Launch

  1. Open DataForeman from Start Menu or Desktop shortcut
  2. Wait for services to start (may take several minutes on first launch)
  3. Browser should open automatically to http://localhost:8080
  4. Login with default credentials from .env file (located in C:\Program Files\DataForeman)

Method 2: Docker on Windows

For development or advanced users:

Prerequisites

  • Docker Desktop for Windows installed and running
  • WSL 2 backend enabled (recommended)

Installation

  1. Open PowerShell or Command Prompt
  2. Run the following commands:
1
2
3

git clone https://github.com/orionK-max/DataForeman.git
cd dataforeman
docker compose up -d
  1. Access at http://localhost:8080

See the Full Docker Guide for detailed Docker instructions.

Windows Firewall

The installer DOES NOT automatically create firewall rules. You need to configure firewall access manually.

Required Ports

DataForeman uses the following ports that may need firewall configuration:

External Access (User-facing):

  • Port 8080 (TCP) - Frontend web interface (nginx)
  • Port 3000 (TCP) - Core API backend

Internal Services (typically localhost only):

  • Port 5432 (TCP) - PostgreSQL (application database)
  • Port 5433 (TCP) - TimescaleDB (time-series database)
  • Port 4222 (TCP) - NATS message bus

Firewall Configuration

For local-only access (recommended for most users):

No firewall configuration needed - Windows allows localhost connections by default.

For network access (access from other computers):

  1. Open Windows Defender Firewall
  2. Click Advanced settings
  3. Inbound Rules → New Rule
  4. Port → Next
  5. TCP, Specific local ports: 3000,8080
  6. Allow the connection
  7. Apply to all profiles (Domain, Private, Public)
  8. Name: “DataForeman Web Access”

Using PowerShell (run as Administrator):

1
2
3
4

# Allow web interface and API
New-NetFirewallRule -DisplayName "DataForeman Web Interface" -Direction Inbound -Protocol TCP -LocalPort 8080 -Action Allow

New-NetFirewallRule -DisplayName "DataForeman API" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow

⚠️ Security Note: Only open ports if you need network access. Internal service ports (5432, 5433, 4222) should remain localhost-only unless you have specific requirements.

For advanced users who need database access from other tools:

1
2
3
4
5

# PostgreSQL access (use with caution)
New-NetFirewallRule -DisplayName "DataForeman PostgreSQL" -Direction Inbound -Protocol TCP -LocalPort 5432 -Action Allow

# TimescaleDB access (use with caution)
New-NetFirewallRule -DisplayName "DataForeman TimescaleDB" -Direction Inbound -Protocol TCP -LocalPort 5433 -Action Allow

Updates

  1. Download latest installer from GitHub Releases
  2. Run the installer
  3. Your data and settings are preserved

Getting Help

If you encounter issues:

  1. Check this guide’s Troubleshooting section
  2. Review log files in %LOCALAPPDATA%\DataForeman\logs
  3. Visit GitHub Discussions
  4. Report bugs on GitHub Issues
  5. Check Windows-specific issues