Skip to content

System Requirements and Prerequisites

Jump to bottom
Jonas Breder edited this page Sep 1, 2026 · 2 revisions

System Requirements & Deployment Prerequisites

Before installing hroot, ensure that your hosting environment, network infrastructure, email services, and user permissions meet the technical requirements outlined below.

1. Hardware & Operating System

Component Minimum Specification Recommended Specification
Operating System Linux (Ubuntu 22.04/24.04 LTS, Debian 12, RHEL / AlmaLinux 9) Ubuntu 24.04 LTS or Debian 12 (64-bit x86_64)
CPU 1 vCPU (Core) 2–4 vCPUs for large subject pools & parallel sessions
Memory (RAM) 2 GB RAM 4 GB RAM (ensures fast Rails caching, database buffering & background workers)
Disk Space 10 GB free storage 25+ GB SSD (for Docker images, MySQL volumes, database backups, file uploads)

2. Network, Domain & DNS Requirements

  1. Fully Qualified Domain Name (FQDN):
    • A dedicated public domain or university subdomain (e.g. hroot.wiso.uni-hamburg.de or lab-recruitment.example.org).
    • DNS A-Record / AAAA-Record: Must point directly to the public IP address of your server.
  2. Firewall & Port Availability:
    • Port 80 (HTTP) & Port 443 (HTTPS): Inbound traffic must be permitted for web clients and automatic SSL certificate generation (via Let's Encrypt / ACME Companion).
    • Port 3000 (Internal/Custom Proxy): Required only if HROOT is operated behind an existing university reverse proxy (e.g. institutional NGINX, Apache, Traefik, or Cloudflare Tunnel).
    • Outbound Internet Access (Port 443): Required for pulling container images from GitHub Container Registry (ghcr.io) and receiving automated updates.

3. Mailing & Email Service Requirements (Critical)

Email communication is the core mechanism of HROOT for participant recruitment, invitation waves, session reminders, and login codes.

Outgoing E-Mail (SMTP)

  • SMTP Server: A reliable SMTP server or institutional mail relay (e.g. smtp.uni-hamburg.de).
  • Port & Security: Port 587 (STARTTLS) or Port 465 (SSL/TLS). Port 25 without authentication is supported for local university relays.
  • Credentials: Valid SMTP username and password.
  • Sender Addresses:
    • SENDER_EMAIL: Address from which emails are sent (e.g. recruitment@uni-hamburg.de).
    • CONTACT_EMAIL: Reply-to address visible to participants.
  • Throughput Allowance: Ensure your mail relay allows sending bulk invitation waves (e.g. 500–2,000 emails/hour) without triggering aggressive spam blocks.

Incoming E-Mail (IMAP / Optional but Strongly Recommended)

  • Purpose: Enables HROOT to automatically read incoming participant replies, process bounce notifications, and handle unsubscribe requests.
  • Requirements: IMAP host (e.g. imap.uni-hamburg.de), Port 993 (SSL), username, password, and folder name (default: INBOX).

4. Software & User Permission Requirements (Non-Root / Sudo-Free)

HROOT is engineered to run in unprivileged user-space without requiring permanent root or sudo privileges during installation and operations.

One-Time Server Preparation (By System Administrator)

# 1. Install Docker Engine & Compose plugin (v2)
sudo apt update && sudo apt install docker.io docker-compose-v2 -y

# 2. Add your service user (e.g. 'hroot' or 'labadmin') to the docker group
sudo usermod -aG docker $USER

# 3. Apply group membership (or log out and back in)
newgrp docker

Installation Rights (By Laboratory Operator / Normal User)

  • No sudo required: As long as the operating user belongs to the docker group, the entire installation, secret generation, and container management run 100% unprivileged.
  • All application files, .env configurations, and uploads are stored in the user's home directory (e.g. ~/hroot or /srv/hroot).

5. Software License & GitHub Access

  • Access Authorization: An authorized grant to access the private HROOT repository (wiso-forschungslabor/hroot or an authorized fork) is required.
  • GitHub Personal Access Token (PAT):
    • A classic GitHub token with repo (Private repository access) and read:packages (GitHub Container Registry ghcr.io download) scopes.

6. Optional Feature Prerequisites

Feature Technical Prerequisites Purpose
Android SMS Gateway Android smartphone with SIM card + Android SMS Gateway App (URL & API Key) Fast SMS dispatch for experiment invitation alerts and last-minute session reminders.
WebPush Notifications Modern browser (HTTPS required) Browser desktop/mobile push notifications for participants. Keys are auto-generated.
Shibboleth / SAML SSO University IdP Entity ID, SSO Target URL & X.509 Certificate Fingerprint Single Sign-On for campus students and faculty staff.
Bot Protection (Captcha) hCaptcha Site/Secret Key or Cloudflare Turnstile Site/Secret Key Protection against automated spam registrations on public registration forms.
Kimai Time Tracking Kimai Instance URL, Username & API Token Automatic synchronization of laboratory staff shifts and work hours.
External Database MySQL 8.0+ / MariaDB 10.6+ (utf8mb4 character set & collation) Connecting HROOT to a central, managed campus database cluster instead of internal Compose DB.

7. Next Step: Installation

Once your prerequisites are verified, continue with the Installation guide or run the interactive one-line installer:

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

HROOT - Hamburg Registration and Organization Online Tool

  1. Installation

    1. System Requirements and Prerequisites

    2. Docker (precompiled)

    3. Docker (self-compiled)

    4. Manual Deployment

    5. First steps after installation

    6. Environment Configuration

    7. Backup and Maintenance

    8. Starting a local server and running automated tests

    9. Basic configuration

    10. Language configuration and timezone

    11. Custom field definitions

  2. Updating an existing installation

  3. Overview

    1. Roles: Users, Admins, Experimenters, Banking‐Administrators
    2. Experiments, Sessions, session types

  4. Subject pool and user management

    1. Browsing the pool
    2. Exporting data
    3. Adding users
    4. Deleting users
    5. Finding duplicate users
    6. More user management

  5. Experiment management

    1. Managing Experiments
    2. Adding Sessions
    3. Experiment and Session Inheritance
    4. Reserving locations (booking)
    5. Assign participants from the pool
    6. Inviting participants
    7. Session management
    8. Waiting list
    9. Invitations Scheduling and Digests

  6. Admission

    1. QR Code Admission
    2. Online Waiting Room
    3. Online Surveys and Completion Links

  7. Calendar

  8. Sending messages

    1. Invitation emails
    2. Confirmation emails
    3. Session reminder emails
    4. Default locale and date formats
    5. SMS and Push Notifications

  9. Settings

    1. Shibboleth Integration
    2. Kimai Integration

  10. Staff Management

  11. Finance

  12. Pools Management

Clone this wiki locally