Manual Deployment

This guide is for administrators installing hroot directly on a Linux server without Docker.

Note

Manual deployment requires maintaining your own Ruby runtime environment, database server, assets precompilation, and background cron schedules. For new installations, consider using Docker Deployment.

---

System Requirements

Install the necessary system packages (example for Ubuntu/Debian):

sudo apt update
sudo apt install build-essential pkg-config libmysqlclient-dev libvips42 git curl nodejs

• Ruby: Version 4.0.6 (Installation via rbenv recommended).
• JavaScript Runtime: Node.js (v18+ recommended) or any ExecJS-compatible runtime for asset precompilation.
• Database: MySQL 8.0+ or MariaDB.

---

Setup and Installation

1. Ruby & Gems

Ensure you are in the project root directory. If using rbenv:

rbenv install 4.0.6
gem install bundler
bundle install

2. Database Creation & Permissions

Copy the environment template: cp .env.example .env and adjust the database credentials.

If you are using a local MySQL/MariaDB instance, log in to your database console and manually create the database and user:

CREATE DATABASE hroot_production;
CREATE USER 'hroot'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON hroot_production.* TO 'hroot'@'localhost';
FLUSH PRIVILEGES;

3. Database Migration

Ensure RAILS_MASTER_KEY and the database variables are set in .env, then run migrations:

bin/rails db:migrate

4. Initial Administrator Account

Create the initial superuser account interactively using the Rails setup command:

bin/rails hroot:create_admin

Follow the interactive prompts to set the administrator's name, email, and password.

Tip

If you need to remove an admin user from the command line later, you can run: bin/rails "hroot:remove_admin[email@domain.net]"

5. Assets & Background Jobs

Precompile assets for production and configure the cron schedule for background email/digest queues using the whenever gem:

bin/rails assets:precompile
whenever -w

6. Directory Permissions

Set proper read/write permissions for directories where logs, uploads, and active storage items are saved:

chmod -R 755 storage log tmp uploads

---

Web Server & SSL Setup

To serve the Rails application securely in production without Docker:

• Comprehensive Web Server & SSL Guide: Follow Webserver and SSL Setup for complete production setups with NGINX (Reverse Proxy + Puma) or Apache 2.4 (Passenger), automated Let's Encrypt SSL certificates (Certbot), institutional certificates, and auto-renewal jobs.
• Apache + Passenger Legacy Reference: See Production server with Phusion Passenger.
• Background Cron Schedules: See Cronjob for background task.

---

Next Steps

Once the web server is operational and your initial administrator account is created, proceed to the First steps after installation guide to configure participant pools, profile fields, communication templates, and lab parameters.