aardbei/INSTALLING.md

Requirements

To run Aardbei, you will need a UNIX operating system, which basically means that you need to be running either macos or some flavour of Linux. Running on Windows might very well be possible, but I haven't tried it.

The Ruby-version Aardbei uses is currently 2.3.3, and to ensure that the version is always available, and does not conflict with any system installation of some other Ruby version, the supported way to install it is by compiling from source using the platform-independent tool rbenv, with two helper tools called ruby-build and rbenv-vars.

You will need the following tools installed in whatever way you like:

• Git
• Your distro's equivalent of build-essential (make, gcc, probably other tools)
• Development headers for openssl, zlib and readline (Ubuntu: sudo apt install libssl-dev zlib1g-dev libreadline-dev)
• Nodejs (apt install nodejs) for Javascript minifying.
• In production: a working postgresql installation, with the development headers for libpq (apt install libpq-dev). Other databases will probably work because ActiveRecord should support it, but I'm using Postgres on my own server, and haven't tested anything besides sqlite yet.
• In development: libsqlite3 with development headers (apt install libsqlite3-dev)

Installing rbenv, ruby-build, and rbenv-vars, and adding it to your shell

Installing rbenv

To not depend on your distro's version of rbenv (if any), we install from rbenv's repository.

Clone the rbenv repository to your home directory:

$ git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Try to compile the bash extension:

$ cd ~/.rbenv; src/configure; make -C src; cd -

Add rbenv to your $PATH (note the double >>, a single > will trash your .bashrc!):

$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
$ echo 'eval "$(rbenv init -)"' >> ~/.bashrc
$ source ~/.bashrc

Installing ruby-build, compiling ruby

ruby-build is a plugin for rbenv that provides automated compilation and installation of Ruby.

Create the plugin-directory, and clone the repository to it:

$ mkdir -p ~/.rbenv/plugins
$ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Ensure you have the dependencies listed above installed (build-essential and the development headers for openssl, libreadline and zlib). Now start the compilation of Ruby (this will take a while and will not show a progress bar):

$ rbenv install 2.3.3

If all is well, you will get some success message, if you have an error the script usually tells you what went wrong.

Installing rbenv-vars

rbenv-vars is another plugin for rbenv that allows us to easily set environment variables by listing them in the file .rbenv-vars.

Install it by cloning the repository:

$ git clone https://github.com/rbenv/rbenv-vars.git ~/.rbenv/plugins/rbenv-vars

Copy the template .rbenv-vars-sample to .rbenv-vars, and set the environment to production or development, and the locale to en or nl, without quotes.

RAILS_ENV=development
# ...
AARDBEI_LOCALE=en

Set AARDBEI_HOSTNAME to the hostname your copy is going to run under (in development it's going to be localhost:3000:

AARDBEI_HOSTNAME=aardbei.maartenberg.nl

If you're planning to run in the production environment, but without a real webserver to serve your assets, set RAILS_SERVE_STATIC_FILES=1.

Set AARDBEI_PATH to the full path of the cloned directory, like AARDBEI_PATH=/home/aardbei/aardbei.

Installing dependencies

Aardbei's dependencies in Ruby are managed using Bundler. To install it, rbenv needs to know which version of Ruby we're using. This is stored in the file .ruby-version.

Install bundler by moving to your cloned copy of Aardbei, and running:

$ gem install bundler

Depending on your environment, run either:

$ bundle install --without=production # in development
$ bundle install --without='development test' # in production

If all went well, run rbenv rehash to add the new executables to your shell, and test that the installation worked by running rails. You should see some output listing the available subcommands.

Open up your .rbenv-vars again, run the command rails secret, and set it as your SECRET_KEY_BASE:

SECRET_KEY_BASE=a3a43b...

Setting up the database

In development: SQLite

When running in the development environment, the database is saved as a file in the db folder. To create it, and pre-fill some test data, run this command:

$ RAILS_ENV=development rails db:setup

Note: The test data currently includes a hardcoded admin user, change this if needed!

In production: Postgresql

If you're not already running Postgresql, install it using sudo apt install postgresql-9.5.

Create a database and user with the following commands:

$ sudo -u postgres psql
postgres=# CREATE ROLE aardbei WITH LOGIN PASSWORD 'aardbei123';
CREATE ROLE
postgres=# CREATE DATABASE aardbei WITH OWNER = aardbei;
CREATE DATABASE
postgres=# GRANT ALL PRIVILEGES ON DATABASE aardbei TO aardbei;
GRANT
postgres=# \q

You will probably want to generate a real password for the database instead of 'aardbei123', this can be done by running rails secret.

Fill in your database details in .rbenv-vars:

DB_NAME=aardbei
DB_USER=aardbei
DB_PASS=aardbei123

Now set up the database:

$ rails db:setup

Setting up email

Aardbei needs to be able to email in order to send password reset links and reminders. Set the address for the From: field by setting:

MAIL_FROM_ADDRESS=aardbei@maartenberg.nl

Choose one of the below methods to deliver your mails:

Using Sendmail

If your system already has working sendmail, set MAIL_METHOD to sendmail.

MAIL_METHOD=sendmail

Using Mailgun

If you have your own domain, you can use the free Mailgun tier to deliver your emails. In .rbenv-vars, set:

MAIL_METHOD=mailgun

# ...

MAILGUN_DOMAIN=your.domain.mg
MAILGUN_API_KEY=key-abcdefpdftexexezip

Using SMTP

You can use a SMTP server. Set:

MAIL_METHOD=smtp

SMTP_SERVER=email.example.com
SMTP_USER=coolskeleton95
SMTP_PASS=aardbei123

Create an Admin person

If you're not me, you'll want to create your own user. Run:

$ rails console
> p = Person.new
> p.first_name = 'Maarten'
> p.infix = 'van den'
> p.last_name = 'Berg'
> p.email = 'youremail@example.com'
> p.is_admin = 1
> p.save
> exit

Note that this has not yet set a password for you: to do that, we need to run a server.

Running the server directly / in development mode

To start the server, run the command rails server. Your terminal will block until you press Control-C. In addition to this, you will need to be running the jobs worker to be able to send emails. To start it, run (in another terminal or before starting the server) bin/delayed_job start (or run in the foreground with bin/delayed_job run).

Running in production

TODO.

Activating your admin user

To activate your admin user, have your server running and go to http://localhost:3000/register. Enter the email address you entered when you created your Person, and follow the instructions.