The steps described in this section are for preparing a production installation. For possible modifications to this procedure to configure the development environment, see the Contributing section below.

Requirements

Server side:
- Ruby interpreter, depending on the version of Rails used (see Gemfile),
  - https://guides.rubyonrails.org/upgrading_ruby_on_rails.html#ruby-versions
- database (e.g. MySQL >= 8.0) supporting:
  - recursive Common Table Expressions (CTE) for SELECT/UPDATE/DELETE,
    - MariaDB does not support CTE for UPDATE/DELETE (https://jira.mariadb.org/browse/MDEV-18511)
  - decimal datatype with precision of at least 30,
    - SQLite3 flexible typing decimal will work, but precision will be limited to 16, making it practical mostly for testing purposes
- for testing: browser as specified in Client side requirements
Client side:
- browser (e.g. Firefox >= 121) supporting:
  - import maps (required by importmap-rails gem >= 2.0)
  - CSS :has() pseudo-class

Gems

On systems where development tools and libraries are not installed by default (such as Ubuntu), you should install them before proceeding with Ruby gems. Select the database client library according to the database engine you are planning to use:

sudo apt install build-essential libyaml-dev libmysqlclient-dev

git clone https://gitea.michalczyk.pro/fixin.me/fixin.me.git
cd fixin.me
bundle config --local frozen true
bundle config --local path .gem

Select which database engine gem to install (mysql, postgresql, sqlite):

bundle config --local with mysql
bundle install

Configuration

Customize application settings (starting below SETUP comment) appropriately:

cp -a config/application.rb.dist config/application.rb

Create secret_key_base. It will be automatically generated on first credentials:edit, so it's enough to run command below, save the file and exit editor:

bundle exec rails credentials:edit

Precompile assets:

RAILS_ENV=production bundle exec rails assets:precompile

Database

Grant database user and privileges:

> mysql -p
mysql> create user fixinme@localhost identified by 'Some-password1%';
mysql> grant all privileges on fixinme.* to fixinme@localhost;
mysql> flush privileges;

Copy config template and update database configuration:

cp -a config/database.yml.dist config/database.yml

Run database creation and migration tasks:

RAILS_ENV=production bundle exec rails db:create db:migrate db:seed

Running

Standalone Rails server + Apache proxy

Customize Puma config template:

cp -a config/puma.rb.dist config/puma.rb

and specify server IP/port, either with port or bind, e.g.:

bind 'tcp://0.0.0.0:3000'

(option 1) Start server manually

bundle exec rails s -e production

(option 2) Start server as systemd service

Customize service template, setting at least User and WorkingDirectory:

sudo cp bin/fixinme.service.dist /etc/systemd/system/fixinme.service

sudo systemctl daemon-reload
sudo systemctl enable fixin.service
sudo systemctl start fixin.service

sudo systemctl status fixin.service

Apache mod_passenger

TODO: add sample configuration

Contributing

Database

Grant database user privileges for development and test environments, possibly with different Ruby versions:

> mysql -p
mysql> create user `fixinme-dev`@localhost identified by '<some password>';
mysql> grant all privileges on `fixinme-%`.* to `fixinme-dev`@localhost;
mysql> flush privileges;

Development environment

Starting application server in development environment:

bundle exec rails s -e development

For running rake tasks, prepend command with environment:

RAILS_ENV="development" bundle exec rake ...

Running tests

Tests need to be run from within toplevel application directory:

all system tests:
```
  bundle exec rails test:system
```

system test(s) with seed/test name specified:

  bundle exec rails test:system --seed 64690 --name test_add_unit

all tests from one file, with optional seed:

  bundle exec rails test test/system/users_test.rb --seed 1234

Icons

Pictogrammers Material Design Icons: https://pictogrammers.com/library/mdi/

Rake tasks

Exporting default settings defined in application to seed file (e.g. to send as PR or share between installations):

    bundle exec rails db:seed:export