Setup — Field Log

// SETUP GUIDE

Requirements

Field Log runs as a single Docker container. You need:

A Linux host (bare metal, VM, or VPS)
Docker 24+ and Docker Compose v2
Outbound SMTP access if you want email features
~200 MB disk for the image; storage grows with attachments

Works on Raspberry Pi (arm64), Ubuntu, Debian, and any Docker-compatible platform.

Installation

bash

# Clone the repo
git clone https://github.com/devkhelms/Fieldlog.git
cd Fieldlog

Environment file

Copy the example file and fill in your values:

bash

cp .env.example .env
nano .env

Minimum required values:

.env

# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=your-random-hex-string

APP_USERNAME=admin
APP_PASSWORD=your-password

Everything else (SMTP, email alerts, webhooks, SLA thresholds) is optional. See the Configuration reference for the full list.

Keep .env out of source control. It is already in .gitignore.

First run

bash

# Build the container image and start
docker compose up -d --build

# Apply database migrations
docker exec issuetrack python migrate.py

Open http://<your-host>:5000 and sign in with the credentials from .env.

Deploying updates

After pulling new code:

bash

git pull
docker compose up -d --build
docker exec issuetrack python migrate.py

migrate.py is safe to re-run at any time — it only adds missing columns or tables and skips everything already present.

Always rebuild the container for code changes. A plain docker compose restart will not apply Python or template changes.

Data & backups

All persistent data lives in two Docker named volumes:

Volume	Mount	Contents
issuetrack_data	/data	SQLite database
issuetrack_attachments	/attachments	Uploaded files

Both volumes survive container rebuilds. Do not delete them unless you intend to wipe the instance.

You can also download a live .db backup from within the app at Admin → Backup DB.

Mobile / PWA Install

After the container is running, open any of the mobile pages on your phone's browser:

/command/mobile — status dashboard
/quick — quick incident log
/tasks/mobile — task list

On Android / Chrome: tap the three-dot menu → Add to Home Screen. The app installs as a standalone icon with no browser chrome.

On iOS / Safari: tap Share → Add to Home Screen. Standalone display and the amber icon will apply.

The app icon PNG files are generated automatically the first time you run docker exec issuetrack python migrate.py.

Logs & debugging

bash

# Tail application logs
docker logs issuetrack --tail 50

# Check the container is running
docker ps

# Verify environment variables were loaded
docker exec issuetrack printenv | grep SMTP

# Open a shell inside the container
docker exec -it issuetrack bash