Docker (precompiled)

This guide details the Precompiled Zero-Touch Docker Deployment for hroot. This is the recommended deployment method for standard production environments, academic laboratories, and universities that want a fast, reliable, and maintenance-free setup.

---

1. Overview & Key Advantages

In this mode, container images are pulled directly from the GitHub Container Registry (ghcr.io/wiso-forschungslabor/hroot:latest or your own custom fork's image). App secrets (SECRET_KEY_BASE, WebPush VAPID keypairs, and internal database credentials) are generated automatically on the first launch.

• Key Advantages:
  • Instant Zero-Touch Start: No time-consuming gem/asset compilation on your server, and no manual code cloning required to run the application.
  • Full In-Browser Setup: Database choice (internal Compose DB vs. external MySQL/MariaDB), schema migrations, SMTP/IMAP mail settings, and initial banking administrator account creation are completed directly through the Setup Wizard at /setup.
  • Support for Custom Forks: Laboratories maintaining their own fork on GitHub can build their own precompiled images via GitHub Actions and deploy them just as easily.
  • One-Click In-App Updates: Seamless version checks and automated updates directly in the Admin UI (/admin/options/check).

---

2. Quickstart Installation (Automated One-Line Installer)

The easiest and recommended way to deploy HROOT is the automated One-Line Interactive Installer. It runs on any modern Linux distribution (Ubuntu, Debian, AlmaLinux, RHEL, Fedora, Rocky, Arch) and handles everything automatically:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/wiso-forschungslabor/hroot-documentation/master/install.sh)"

(Alternatively, if you already cloned the repository locally: cd hroot && ./bin/install)

What the Interactive Installer Handles Automatically:

1. System & Docker Pre-Flight Check:
   • Detects if Docker Engine and Docker Compose v2 are installed.
   • If missing, offers to automatically install Docker via your system package manager (apt, dnf, yum, or pacman).
   • Verifies unprivileged user permissions and adds the current user to the docker group.
2. Container Registry Authentication:
   • Prompts for your GitHub Username and Personal Access Token (PAT with read:packages & repo scopes) and logs in to ghcr.io.
3. Target Directory:
   • Prompts where HROOT should be installed (Default: ./hroot).
4. Docker Image Selection:
   • Official Upstream: ghcr.io/wiso-forschungslabor/hroot:latest (Default).
   • Custom Fork: Specify your repository (e.g. your-university/hroot) and optional release tag (e.g. v4.0-beta5 or latest).
5. Network & Domain Configuration:
   • Enter your domain (e.g. hroot.example.org or localhost:3000).
6. Database Architecture:
   • Internal Docker MySQL 8.0: Auto-generates cryptographically secure root and app database passwords.
   • External Database Server: Enter remote campus MySQL/MariaDB credentials.
7. Setup Protection Token:
   • Auto-generates a secure HROOT_SETUP_TOKEN to protect the in-browser /setup wizard.
8. Orchestration & Secret Generation:
   • Generates SECRET_KEY_BASE, writes .env, creates docker-compose.yml, and sets up initial directory volumes.
9. Launch:
   • Pulls the precompiled images and starts all services in the background (docker compose up -d).

---

3. Minimal Manual Setup (Alternative for CI / Custom Automation)

If you prefer to start manually without the interactive wizard:

1. Log in to GitHub Container Registry (ghcr.io):

   echo $GITHUB_PAT | docker login ghcr.io -u <github-username> --password-stdin

2. Create target directory and download docker-compose.yml:

   mkdir -p /srv/hroot && cd /srv/hroot
   curl -O https://raw.githubusercontent.com/wiso-forschungslabor/hroot/master/docker-compose.yml

3. Launch containers with domain & setup token:

   • For Official Upstream Image:

     APP_DOMAIN=hroot.example.org HROOT_SETUP_TOKEN=your-secure-setup-token docker compose up -d

   • For Custom Fork Image:

     HROOT_IMAGE=ghcr.io/<your-account>/hroot:latest UPDATE_GITHUB_REPO=<your-account>/hroot APP_DOMAIN=hroot.example.org HROOT_SETUP_TOKEN=your-secure-setup-token docker compose up -d

---

4. Complete Configuration in the Web Setup Wizard

Once the containers are running:

1. Open https://<APP_DOMAIN>/setup (or http://localhost:3000/setup) in your web browser.
2. Enter your HROOT_SETUP_TOKEN to unlock the assistant.
3. Complete the tabs:
   • Database: Select internal Docker DB or external MySQL/MariaDB server, click „Test Connection“, and then „Initialize DB“.
   • E-Mail & IMAP: Enter CONTACT_EMAIL and SMTP server credentials, then verify using „Send Test E-Mail“.
   • First Superuser: Enter name, email, and password for your initial banking administrator.
4. Click Finish initial setup to save settings and sign in to hroot.

Tip

Next Step: After completing the wizard, see First steps after installation for the step-by-step roadmap to configure participant pools, custom fields, email templates, and financial settings.

---

5. Architectural Scenarios (Compose Override Modes)

Depending on your server infrastructure (as defined in the Installation Decision Matrix), choose the appropriate execution scenario:

Scenario A: Standalone Docker (Standard Setup)

Best for: A dedicated server running only a single hroot instance, where Docker handles SSL automatically on ports 80/443.

docker compose up -d

---

Scenario B: Multi-Instance / Shared Proxy Setup

Best for: Hosting multiple independent laboratories or multiple hroot instances (e.g. testing, staging, and production) on the same server.

This setup routes multiple instances through a central reverse proxy (nginxproxy/nginx-proxy) with automated Let's Encrypt SSL certificates.

• To start an instance connecting to a shared proxy:

  docker compose -p <project-name> -f docker-compose.yml -f docker/overrides/shared-proxy.yml up -d

• Full Guide & Multi-Lab Example: For the complete architecture explanation, central proxy setup, and a step-by-step example running 3 parallel instances, see Docker Multi-Instance Setup.

---

Scenario C: App-Only Setup (External Host-Nginx / Apache)

Best for: Serving hroot behind an existing NGINX or Apache web server already running directly on the Linux host.

docker compose -f docker-compose.yml -f docker/overrides/app-only.yml up -d

---

Scenario D: External Database Server

Best for: Connecting hroot to an existing, centralized university MySQL/MariaDB server cluster.

docker compose -f docker-compose.yml -f docker/overrides/ext-db.yml up -d

---

6. In-App Updates (One-Click)

Administrators can check for updates and trigger system upgrades directly in the web application:

1. Navigate to Admin $\rightarrow$ Options $\rightarrow$ System Check & Updates (/admin/options/check).
2. Compare the installed Git commit with the latest release available on GitHub.
3. Click Update System Now to trigger an automated, fail-safe update cycle:
   • 1. Database Snapshot: A safety dump of MySQL is saved prior to any changes.
   • 2. Fast Image Download: The new Docker layer is downloaded from ghcr.io.
   • 3. Schema Migrations: rake db:migrate runs in isolation.
   • 4. Health Check: The container starts and readiness is polled for up to 180 seconds.
   • 5. Automated Rollback: If any error occurs, the previous image and database state are restored.

For a detailed comparison of all update methods (including CLI and source-build updates), see Updating an existing installation.

---

7. Server Reboot & Autostart Behavior

By default, all containers in docker-compose.yml (db, web, cron, proxy, acme, mail, sms-gateway) are configured with:

restart: unless-stopped

• What happens on host reboot:

  1. The host operating system boots and starts the Docker daemon (docker.service).
  2. The Docker engine inspects container states and automatically relaunches all containers that were active before the shutdown.
  3. Services that were explicitly stopped by an administrator via docker compose down or docker compose stop will remain stopped across reboots.

• Prerequisite: The Docker daemon must be enabled in systemd (the interactive installer enables this automatically):

  sudo systemctl enable --now docker

• Optional: Managing HROOT via systemd (hroot.service) If your IT policy prefers managing services via systemctl, you can create a systemd unit:

  sudo tee /etc/systemd/system/hroot.service > /dev/null <<'EOF'
  [Unit]
  Description=HROOT Docker Compose Application Stack
  Requires=docker.service
  After=docker.service network-online.target
  Wants=network-online.target
  
  [Service]
  Type=oneshot
  RemainAfterExit=yes
  WorkingDirectory=/srv/hroot
  ExecStart=/usr/bin/docker compose up -d
  ExecStop=/usr/bin/docker compose down
  TimeoutStartSec=0
  
  [Install]
  WantedBy=multi-user.target
  EOF
  
  sudo systemctl daemon-reload
  sudo systemctl enable hroot

  You can then start, stop, and inspect the stack using standard systemd commands:

  sudo systemctl status hroot
  sudo systemctl stop hroot
  sudo systemctl start hroot

---

8. Next Steps

Proceed directly to the First steps after installation checklist to configure participant pools, profile questionnaires, notification templates, and lab parameters in the Site Settings.