Improve installation process

README.md

@@ -4,47 +4,70 @@ README
 Quantified self
 
 
-Software requirements
----------------------
+Installation
+------------
+
+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 version: developed on Ruby 3.x
-    * database with:
-        * recursive Common Table Expressions (CTE) support, e.g.
-          MySQL >= 8.0, MariaDB >= 10.2.2
-        * decimal type with precision of at least 30 (not sure if SQLite3
-          supports this)
+    * 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 supporting below requirements (e.g. Firefox >= 121):
+    * browser (e.g. Firefox >= 121) supporting:
         * [`import maps`](https://caniuse.com/import-maps)
           (required by `importmap-rails` gem >= 2.0)
         * CSS [`:has()` pseudo-class](https://caniuse.com/css-has)
 
+### Gems
 
-Installation
-------------
+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
-    bundle config set --local path '.gem'
+    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
 
-Configuration
--------------
+Customize application settings (starting below `SETUP` comment) appropriately:
 
     cp -a config/application.rb.dist config/application.rb
 
-Modify configuration settings below `SETUP` comment appropriately.
+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
 
-Database
---------
+### Database
 
 Grant database user and privileges:
 
     > mysql -p
-    mysql> create user fixinme@localhost identified by '<some password>';
+    mysql> create user fixinme@localhost identified by 'Some-password1%';
     mysql> grant all privileges on fixinme.* to fixinme@localhost;
     mysql> flush privileges;
 
@@ -62,7 +85,7 @@ Running
 
 ### Standalone Rails server + Apache proxy
 
-Copy Puma config template:
+Customize Puma config template:
 
     cp -a config/puma.rb.dist config/puma.rb
 
@@ -70,10 +93,21 @@ and specify server IP/port, either with `port` or `bind`, e.g.:
 
     bind 'tcp://0.0.0.0:3000'
 
-Run server
+#### (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