Docker Guide

Get FreeITSM running in minutes with three commands

This is the fastest way to try FreeITSM. Docker handles the web server, database, and configuration automatically. No manual setup required.

Prerequisites

You need two things installed on your machine:

  • Git – to clone the repository
  • Docker – to build and run the application

Installing Docker

Linux (Ubuntu / Debian)

# Install Docker Engine
sudo apt update
sudo apt install docker.io docker-compose-plugin -y

# Allow your user to run Docker without sudo
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect

Windows

  1. Open PowerShell as Administrator and install WSL (Windows Subsystem for Linux): 
    wsl --install
    Restart your computer if prompted.
  2. Download and install Docker Desktop from docker.com
  3. During installation, ensure Use WSL 2 based engine is ticked
  4. After installation, open Docker Desktop and wait for it to start

Windows users: Docker Desktop must be running before you can use Docker commands. You'll see the Docker whale icon in your system tray when it's ready.

Build and Run

Open a terminal (Linux) or PowerShell / Command Prompt (Windows) and run these three commands:

# 1. Clone the repository
git clone https://github.com/edmozley/freeitsm.git

# 2. Move into the project folder
cd freeitsm

# 3. Build and start everything
docker compose up --build -d

That's it. Docker will:

  • Build the PHP/Apache web server from the Dockerfile
  • Start a MySQL 8.0 database and import the schema automatically
  • Generate an encryption key for secure settings
  • Connect everything together

Once the build completes (usually 1–2 minutes on first run), open your browser and go to:

http://localhost:8080/setup

This setup page checks that everything is configured correctly. Click Run under Database Verify to create the default tables and admin account.

Default Login

After running Database Verify, log in at http://localhost:8080 with:

  • Username: admin
  • Password: freeitsm

Stopping and Starting

Stop the application

docker compose stop

This stops the containers but preserves your database and all data.

Start it again

docker compose start

Complete Teardown

If you want to remove everything and start fresh – containers, database, all stored data:

# Stop containers and remove all volumes (database, attachments, keys)
docker compose down -v

Warning: This deletes all data

The -v flag removes all Docker volumes, which means your database, uploaded attachments, and encryption key will be permanently deleted. Only use this when you genuinely want a fresh start.

Rebuilding from Scratch

If you've pulled new updates from GitHub or something isn't working right, you can do a clean rebuild:

# 1. Pull the latest code
git pull

# 2. Tear down everything (containers + data)
docker compose down -v

# 3. Rebuild with no cache (forces fresh download of dependencies)
docker compose up --build --no-cache -d

The --no-cache flag tells Docker to ignore its build cache and rebuild every layer from scratch. This is useful if you suspect a cached layer is causing issues.

Updating to a New Version

When a new version of FreeITSM is released, you can update without losing your data:

# 1. Pull the latest code
git pull

# 2. Rebuild and restart (keeps your data)
docker compose up --build -d

After updating, visit /setup and click Run under Database Verify. This will automatically add any new tables or columns without affecting your existing data.

Troubleshooting

Port 8080 already in use

If another application is using port 8080, you can change the port mapping. Edit docker-compose.yml and change "8080:80" to another port, for example "9090:80", then rebuild.

Checking logs

# View logs from all containers
docker compose logs

# View logs from just the web app
docker compose logs app

# Follow logs in real time
docker compose logs -f

Database won't connect

The MySQL container takes a few seconds to initialise on first run. If you see database connection errors, wait 10–15 seconds and refresh the page. Docker's healthcheck ensures the app container waits for MySQL to be ready, but the schema import can take a moment.

Windows: "Docker daemon is not running"

Make sure Docker Desktop is open and fully started. Look for the Docker whale icon in your system tray – it should be steady (not animating). If Docker Desktop won't start, try restarting your computer.

What Docker Gives You

Component Details
Web server Apache with PHP 8.4
Database MySQL 8.0 (auto-configured)
Schema Imported automatically on first start
Encryption key Auto-generated on first boot
Data persistence Docker volumes for database, attachments, and encryption keys

Prefer a Manual Setup?

If you'd rather install FreeITSM on your own web server (IIS, WAMP, or similar), head back to the main getting started page for system requirements and setup steps.

← Back to Getting Started