Upgrading Bare Metal from v3 to v4 - wiso-forschungslabor/hroot-documentation GitHub Wiki

This guide details the complete procedure for upgrading an existing bare-metal (non-Docker) hroot v3.x installation directly on your Linux server to hroot v4.0+, retaining native hosting with Ruby, MySQL, and Phusion Passenger or Puma.

1. Export your MySQL Database:

   mysqldump -u <db_user> -p --single-transaction --routines --triggers <db_name> > ~/hroot_v3_backup_$(date +%Y%m%d_%H%M).sql

2. Back Up Uploaded Files:

   cp -r /path/to/hroot/public/uploads ~/hroot_uploads_v3_backup

Notify users and prevent incoming requests during the upgrade:

cd /path/to/hroot
RAILS_ENV=production bundle exec rake rack:turnout:down[reason="We are running maintenance operations. Please check back shortly."]

If your server still uses RVM, switch to rbenv to eliminate shell overrides and binary gem compilation issues:

1. Remove RVM hooks from your shell: Open ~/.bashrc, ~/.bash_profile, and ~/.profile, and remove any lines referencing .rvm:

   # Remove lines like:
   # source ~/.rvm/scripts/rvm
   # export PATH="$PATH:$HOME/.rvm/bin"

2. Unset RVM environment variables:

   unset GEM_HOME GEM_PATH

3. Install rbenv and ruby-build:

   git clone https://github.com/rbenv/rbenv.git ~/.rbenv
   git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
   echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
   echo 'eval "$(rbenv init - bash)"' >> ~/.bashrc
   source ~/.bashrc

4. Install the Ruby version required by hroot v4:

   cd /path/to/hroot
   rbenv install $(cat .ruby-version)
   rbenv local $(cat .ruby-version)
   gem install bundler

(For complete details, see Ruby and rbenv).

Fetch the latest code and checkout the target release:

cd /path/to/hroot
git fetch origin
git checkout master  # or checkout a specific release tag, e.g. git checkout v4.0.0

From hroot 4.0 on, all laboratory and server settings are read from .env instead of hardcoded Ruby files.

1. Initialize .env and generate cryptographic keys:

   ./bin/init-env

   This creates .env from .env.example and automatically generates secure keys for SECRET_KEY_BASE, WebPush VAPID keypairs, and internal credentials.

2. Transfer your laboratory settings into .env:
   Open your old config/environments/production.rb, config/secrets.yml, and config/database.yml, and copy your settings into .env:

(See Environment Configuration for the full list of optional features like Shibboleth, Kimai, SMS gateways, and Bot Protection).

1. Install Ruby Gems:

   bundle config set --local deployment 'true'
   bundle config set --local without 'development test'
   bundle install

2. Run Database Schema Migrations: You can apply migrations using either the command line or the In-Browser Setup Assistant:

   • Option A (CLI):

     RAILS_ENV=production bin/rails db:migrate

   • Option B (In-Browser Setup Assistant): Open https://<APP_DOMAIN>/setup with your HROOT_SETUP_TOKEN, select „Upgrade from v3.x to v4.0“, verify connected database and administrators, and click „Run v4 Upgrade & Complete Setup“. (This applies all new schema additions in v4 like survey completion links, push notifications, staff roles, updated indexes, and dynamic settings while preserving all research data).

Clear stale cached assets and compile the modern asset pipeline:

RAILS_ENV=production bin/rails assets:clobber
RAILS_ENV=production bin/rails assets:precompile

hroot 4.0 introduces automated invitation digest processing, survey timeout monitors, and IMAP reply processing. Register the updated schedule in your system crontab:

RAILS_ENV=production bundle exec whenever --update-crontab

To inspect the registered cron jobs, run crontab -l.

If you upgraded Ruby or switched to rbenv, update your web server's Ruby path:

Edit /etc/apache2/sites-available/hroot.conf (or /etc/apache2/mods-available/passenger.conf):

# Ensure Passenger uses the rbenv shim:
PassengerRuby /home/hroot/.rbenv/shims/ruby

Restart Apache:

sudo systemctl restart apache2

Edit /etc/nginx/sites-available/hroot:

passenger_ruby /home/hroot/.rbenv/shims/ruby;

Restart NGINX:

sudo systemctl restart nginx

Edit /etc/systemd/system/hroot.service to point ExecStart to /home/hroot/.rbenv/shims/bundle exec puma ...:

sudo systemctl daemon-reload
sudo systemctl restart hroot

touch tmp/restart.txt

1. Disable maintenance mode:

   RAILS_ENV=production bundle exec rake rack:turnout:up

2. Run System Diagnostic Checks:

   • Open https://<APP_DOMAIN>/admin/options/check in your browser.
   • Verify that database connectivity, mailer delivery, and background tasks are healthy.
   • Send a test email from the Admin options page.