Tools [active]

QoLauncher

A Docker runtime for compiled Go binaries: supervises the process, writes daily log files, and serves a password-protected log viewer, with no change to the app's source.

Tech
Go · Docker · Bash
License
MIT
View on GitHub ↗

Problem

Running a plain Go binary in production usually means writing a Dockerfile, a restart policy, and some way to keep and read logs for every app. QoLauncher packages that into one runtime, so a binary from go build can be mounted and run as is.

What it does

QoLauncher runs as PID 1 inside the container. It starts the binary, captures stdout and stderr, and:

  • supervises restarts with a policy of never, on-failure, or always, plus crash-loop protection;
  • writes output to daily log files and cleans up old ones by retention;
  • serves a web log viewer behind Basic Auth (list, view, download);
  • runs an optional HTTP health check;
  • forwards SIGTERM, SIGINT, and SIGQUIT for graceful shutdown.

launcher.sh adds an interactive menu for running several apps, one container per app, with docker-compose.yml generated automatically.

Usage

# Build a static Linux binary into apps/<app-id>/
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o apps/my-api/server .

# Optional per-app env (each app needs its own ports)
cp .env.example apps/my-api/.env

# Interactive menu: Run, Stop, Restart, Reload, Status, Logs, Apps, Setup
./launcher.sh

Or run the image directly:

docker run -d --name api \
  -v $(pwd)/server:/app/server:ro \
  -v $(pwd)/logs:/var/log/qolauncher \
  -e APP_BINARY=/app/server \
  -e APP_RESTART_POLICY=on-failure \
  -e LOG_USERNAME=admin \
  -e LOG_PASSWORD=secret \
  -p 8080:8080 -p 8081:8081 \
  qolauncher:latest

Configuration

Variable Required Default Description
APP_BINARY yes — Path to the Go executable
APP_RESTART_POLICY no never never, on-failure, always
LOG_DIR no /var/log/qolauncher Daily log directory
LOG_PORT no 8081 Log viewer port
LOG_USERNAME / LOG_PASSWORD yes* — Viewer Basic Auth (*not needed with VIEWER_ENABLED=false)

Notes

  • Binaries must be statically linked (CGO_ENABLED=0) to run on the Alpine base image.
  • docker compose logs only shows the launcher’s own log. The app’s output lives in logs/<app-id>/YYYY-MM-DD.log or the log viewer.