Installation

To install hroot, choose the deployment method that fits your laboratory's infrastructure, customization needs, and technical policies.

---

Choosing Your Deployment Method

Use the comparative matrix below to decide which deployment path to follow:

1. Decision & Recommendation Matrix

Deployment Method	Best For	When to Choose	Key Characteristics
1.i. Docker (precompiled) (Standard & Recommended)	Production Labs & Standard Setups	Choose this if you want the fastest, zero-touch setup with automated Docker engine setup, precompiled images, and in-browser setup.	• Interactive One-Line Installer • Automated Docker & Sudo checks • Prebuilt images from ghcr.io • Automated secret generation • Guided Setup Wizard at /setup • 1-Click In-App updates
1.ii. Docker (self-compiled) (Build from Source)	Custom Features, Theming & Local Dev	Choose this if your laboratory plans to modify source code, add custom features/CSS, or test local branches, while keeping container isolation.	• Built locally with Dockerfile • CLI-first .env configuration • Independent of remote registry • Full Docker Compose isolation
1.iii. Manual Deployment (Legacy Bare-Metal)	Environments where Docker is Forbidden	Choose this only if institutional IT policies prohibit Docker on your server.	• Runs directly on host OS • Native Ruby, rbenv, Passenger/Puma • Manual system package maintenance

---

2. Selecting Your Docker Compose Setup Mode

If you deploy using Docker (precompiled or self-compiled), select one of the following scenarios based on your server architecture:

Scenario	Mode	Purpose	Routing & SSL Management
A. Standard Setup	Standalone Compose	A dedicated server hosting only one hroot instance.	Handled automatically by the built-in NGINX reverse proxy & ACME Let's Encrypt companion on ports 80/443.
B. Shared Proxy	Multi-Instance Compose	Hosting multiple instances/labs on a single server.	Routed through a central reverse proxy with shared SSL certificates.
C. App-Only	External Host Proxy	Integrating with existing web servers on your Linux host.	Traffic is passed directly to the app container via NGINX/Apache on the host.
D. External Database	Remote DB Compose	Connecting hroot to an existing university MySQL server.	Uses remote database credentials configured via .env or /setup.

---

Detailed Installation Guides

Proceed to the step-by-step documentation for your chosen method:

0. System Requirements and Prerequisites: Hardware, network/DNS, SMTP/IMAP mail setup, and unprivileged user permissions checklist.

1. Docker (precompiled): Pre-built container images, zero-touch secret generation, and in-browser setup wizard.

   • See also: Docker Multi-Instance Setup for hosting multiple laboratories on one server.

2. Docker (self-compiled): Compiling from local source code, customizing features, and CLI-based configuration.

3. Manual Deployment: Bare-metal installation on Ubuntu Linux with native Ruby, MySQL, and Phusion Passenger.

   • Ruby and rbenv
   • MySQL
   • Git
   • Webserver and SSL Setup
   • Production server with Phusion Passenger
   • Cronjob for background task

---

Next Steps: Post-Installation Setup

Tip

Finished the basic installation?
Follow the First steps after installation checklist for a guided, step-by-step walkthrough on configuring participant pools, custom fields, message templates, finance/payment types, and staff permissions in the Site Settings.

---

Initial Configuration & Administration

• First steps after installation: Step-by-step post-installation configuration roadmap.
• Environment Configuration: Comprehensive catalog of all .env environment variables and security settings.
• Backup and Maintenance: Database snapshot routines, updates, and maintenance tasks.
• Starting a local server and running automated tests: Running test suites and development servers.
• Basic configuration: Initial system branding and laboratory rules.
• Language configuration and timezone: Configuring default locales and timezones.
• Custom field definitions: Setting up participant registration fields and questionnaires.