chexpire/INSTALL.md

Installation

Requirements

Chexpire requires :

• Ruby 2.5.1 and Bundler
• NodeJS and Yarn
• MySQL or MariaDB

We are usually running Chexpire on typical POSIX servers like :

• Linux Debian 9, Ruby 2.5.1, NodeJS 8.11 and MariaDB 10.1
• macOS High Sierra, Ruby 2.5.1, NodeJS 10.2.1 and MariaDB 10.2

It probably works on any system that supports Ruby >2.3, NodeJS >6 and MySQL >5.5. Feel free to report any unexpected incompatibilities.

If you are familiar with Ansible, you can use our Ansible roles to easily install the requirements : rbenv, mysql, nodejs. Add this to your playbook :

[…]
roles:
  - mysql
  - { role: rbenv, username: "{{ ansible_user }}", rbenv_ruby_version: "2.5.1" }
  - { role: nodejs, nodejs_install_yarn: yes }
[…]

NB: the Rbenv username variable points to the user that you want to install Rbenv for. If you use this user for the SSH connection of Ansible, you can leave the {{ ansible_user }} value.

If you want to do manual installations, you can use our Wiki documentations for Rbenv, NodeJS, Yarn and MariaDB.

Dependencies

Execute # bundle install to install Ruby gems (including Rails itself).

Execute # yarn install to install Javascript/NodeJS packages.

Depending on what is already installed on your OS or not, you might need to install a few system packages to be able to have everything working.

libsodium

To use elliptic curve SSH keys, we need to have libsodium and its headers.

• on Debian : # apt install libsodium-dev.
• on macOS with Homebrew : # brew install libsodium.

Rails configuration

After cloning this repository, you have to create and edit a few files from example or defaults files, for your local development configuration :

• config/database.yml
• config/secrets.yml
• config/chexpire.yml : set at least the mailer_default_from and host variables. See other configuration overridable in config/chexpire.defaults.yml.

Theses files will be ignored by git.

Database

You need databases for development and tests. You can create them like this (once connected to you MySQL server) :

MariaDB [none]> CREATE DATABASE `chexpire_development`;
MariaDB [none]> CREATE DATABASE `chexpire_test`;

If you don't want to use the default root MySQL user with no password, you can create users :

MariaDB [none]> GRANT ALL PRIVILEGES ON `chexpire_development`.* TO `chexpire_development`@localhost IDENTIFIED BY 'MY_PASSWORD_FOR_DEV';
MariaDB [none]> GRANT ALL PRIVILEGES ON `chexpire_test`.* TO `chexpire_test`@localhost IDENTIFIED BY 'MY_PASSWORD_FOR_TEST';
MariaDB [none]> FLUSH PRIVILEGES;

Don't forget to adapt the settings in config/database.yml accordingly. Also, on Debian 9 with MariaDB, the database socket is at /var/run/mysqld/mysqld.sock, which is not the default in the configuration file.

You must run the migrations with # bundle exec rails db:migrate (for the default environment – development) and # bundle exec rails db:migrate RAILS_ENV=test (for the test environment).

Tests

The test suite can be run with # bundle exec rails test.

This will also generate a code coverage report in coverage/index.html.

With # bundle exec guard your test suite is run completely a first time, then once for each file you change and save. Take a look at https://guardgem.org for more information.

To execute Rubocop (the style-guide linter for Ruby), run # bundle exec rubocop.

Local execution

If you want to start the Rails application manually, with a simple Puma configuration, you have to execute # bundle exec rails server. You will be able to open http://127.0.0.1:3000 in your browser and see Chexpire in action.

Deployment

staging and production environments are preconfigured. You can use any of them or add more if you want.

Capistrano

If you want to use capistrano for deployment, yout need to create config/deploy/config.yml from the example file, and use the script/to_staging and/or script/to_production scripts.

The same way you've created the config files for development, you'll have to do the same on the staging and production servers in the shared/config/ directory,relative to your deploy_to path.