Setting up from source

This page details the steps required to set up a production environment from source.

Note

This documentation has been heavily adopted from Mastodons 'Installing from source' documentation

Pre-requisites

• A server running Ubuntu 24.04 or Debian 12 that you have root access to
• A domain name (or subdomain) for your Retrospring site, like example.com
• A mail delivery service or an SMTP server

System repositories

Make sure curl, wget, gnupg, apt-transport-https, lsb-release and ca-certificates are installed first:

apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates

Node.js

mkdir -p /etc/apt/keyrings && curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_16.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

System packages

apt-get install -y --no-install-recommends build-essential libpq-dev postgresql-client libxml2-dev libxslt1-dev libmagickwand-dev imagemagick libidn11-dev libicu-dev libjemalloc-dev nodejs yarn

Installing Ruby

We will use rbenv to manage Ruby versions as it simplifies obtaining the correct versions and updating them when new releases are available. Since rbenv needs to be installed for an individual Linux user, we must first create the user account under which Retrospring will run:

adduser --disabled-login retrospring

We can then switch to the user:

su - retrospring

And proceed to install rbenv and rbenv-build:

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

Once this is done, we can install the correct Ruby version:

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.2.3
rbenv global 3.2.3

We’ll also need to install the bundler:

gem install bundler --no-document

Return to the root user:

exit

Setup

Setting up PostgreSQL

Performance configuration (optional)

For optimal performance, you may use pgTune to generate an appropriate configuration and edit values in /etc/postgresql/16/main/postgresql.conf before restarting PostgreSQL with systemctl restart postgresql

Creating a user

You will need to create a PostgreSQL user that Retrospring could use. It is easiest to go with “ident” authentication in a simple setup, i.e. the PostgreSQL user does not have a separate password and can be used by the Linux user with the same username.

Open the prompt:

sudo -u postgres psql

In the prompt, execute:

CREATE USER retrospring CREATEDB;
CREATE DATABASE retrospring_production OWNER retrospring;
\q

Done!

Setting up nginx

Copy the configuration template for nginx from the Retrospring directory:

cp /home/retrospring/retrospring/docs/nginx.conf /etc/nginx/sites-available/retrospring
ln -s /etc/nginx/sites-available/retrospring /etc/nginx/sites-enabled/retrospring
rm /etc/nginx/sites-enabled/default

Then edit /etc/nginx/sites-available/retrospring and follow the comments and adjusts domains and paths according to your setup.

Reload nginx for the changes to take effect:

systemctl reload nginx

Setting up Retrospring

It is time to download the Retrospring code. Switch to the retrospring user:

su - retrospring

Checking out the code

Use git to download the latest stable release of Retrospring:

git clone https://github.com/Retrospring/retrospring.git && cd retrospring

Visit the latest releases page and check it out (ex. 2024.0811.1)

git checkout 2024.0811.01

Installing dependencies

Now to install Ruby and JavaScript dependencies:

bundle install --deployment --without development test mysql
yarn install --frozen-lockfile

Configuring Retrospring

Database configuration

You can either configure Retrosprings database connection via environment variables:

export DATABASE_URL=postgres://[username]:[password]@[host]/[dbname]?pool=25

...or with copying the config/database.yml.postgres to config/database.yml and adjusting its contents:

cp config/database.yml.postgres config/database.yml
$EDITOR config/database.yml

Application configuration

Copy the configuration file config/justask.yml.example to config/justask.yml and adjust its contents:

cp config/justask.yml.example config/justask.yml
$EDITOR config/justask.yml

SMTP configuration

It is recommended to read up on the chapter Action Mailer configuration from the Ruby on Rails guides.

E-Mail sending configuration is currently done via environment variables, the following ones are available:

Rails :smtp_settings key	Retrospring environent variable
:address	SMTP_SERVER
:port	SMTP_PORT
:user_name	SMTP_LOGIN
:password	SMTP_PASSWORD
:domain	SMTP_DOMAIN (or LOCAL_DOMAIN as fallback)
:authentication	SMTP_AUTH_METHOD
:ca_file	SMTP_CA_FILE (/etc/ssl/certs/ca-certificates.crt as default)
:openssl_verify_mode	SMTP_OPENSSL_VERIFY_MODE
:enable_starttls	SMTP_ENABLE_STARTTLS (always, never or auto)
:enable_starttls_auto	true when SMTP_ENABLE_STARTTLS is set to auto, otherwise false
:tls	SMTP_TLS (any value, or true enables this)
:ssl	SMTP_SSL (any value, or true enables this)

Additionally, you can configure the Action Mailer delivery method using SMTP_DELIVERY_METHOD, the default is sendmail.

Setup tasks

Generate secret key

This command creates a secret key used for encryption/hashing across the application:

RAILS_ENV=production bundle exec rails credentials:edit

Note

This command only needs to be run once per setup, the other setup tasks need to be run after each deployment.

Export locales

This exports the locales for use in JavaScript code:

RAILS_ENV=production bundle exec i18n export

Initialize the database

This command creates the database schema:

RAILS_ENV=production bundle exec rake db:migrate

Precompile assets

This command compiles all JavaScript/Stylesheet assets:

RAILS_ENV=production bundle exec rake assets:precompile

Running Retrospring

Manually

You can start Retrospring manually using foreman:

foreman start

As systemd services

TODO: Provide example systemd service files

---

You should now be able to visit your configured domain and see the Retrospring homepage!

Continue to First Steps for setting up an administrator account and more.