aboutsummaryrefslogtreecommitdiffstats

A tiny baby feeding tracking web app for their very first weeks.

Configuration

This application requires the following settings to be set before start:

base_uri
Canonical URL of your public instance (i.e. http://mysite.com) without trailing slash.
session_secret
Long string use as secret key to encrypt the session cookies. The admin:session_secret rake task exists to help you generate a session secret string.
sender_email
Email address use as sender for email generated by the application.
db_connect_uri
Connection string to the database (to be given as this to Sequel.connect method). It defaults to sqlite://db/biberon.db.

This settings can be given as part of a dedicated config/config.yml file at the root of your installation, as systemd service credentials, as environment variables, or a combination of the three.

When the application starts, it reads its configuration first from the config/config.yml file if any, then systemd credentials if any and finally from environment variables if any. The later taking precedence on the former.

The following sections explain each method specificities.

With config.yml file

The config/config.yml file must be put at the root of your installation, i.e. in the same place as this README.org file.

For your production instance, this file can just contain the necessary settings, like the following example:

---
base_uri: "https://example.com"
session_secret: bliblabluverylongstringohmy
sender_email: someone@someserver.tld
db_connect_uri: "mysql://biberon:biberon@127.0.0.1:3306/biberon"

Beware while writing yaml file that period (:) must be escaped as part of the value, by enclosing the whole value with quotation marks.

But an environment-based content is also supported, mainly for your local/dev instance, for example to run the test cases:

---
production: &default
  base_uri: "https://example.com"
  session_secret: bliblabluverylongstringohmy
  sender_email: someone@someserver.tld
  db_connect_uri: "mysql://biberon:biberon@127.0.0.1:3306/biberon"
development:
  <<: *default
  base_uri: "http://127.0.0.1:9292"
  db_connect_uri: "sqlite://db/biberon.db"
test:
  <<: *default
  db_connect_uri: "sqlite://db/test.db"

The default environment (if nothing is given on the command line) is development.

This method is the preferred one if your system on production server is running a version of systemd anterior to v250. In that case, you can you this solution, but be sure that only the user running the application is able to read you config file (chmod 0600 config/config.yml).

This is also the preferred method for development environment, as it let you set different values for dev and test environments.

With systemd service credentials

The application expect the settings to be part of a common yaml file named secrets. No multi-environment is supported in this file, as the systemd method is implied to be used only on production servers.

You can prepare your secret file like this. First, create a local yaml file named secrets.yml (anything you want, the name is not important) and formatted like that:

---
base_uri: "https://example.com"
session_secret: bliblabluverylongstringohmy
sender_email: someone@someserver.tld
db_connect_uri: "mysql://biberon:biberon@127.0.0.1:3306/biberon"

Then, you can generate an encrypted version of it with the following command:

sudo systemd-creds encrypt -p --name=secrets secrets.yml -

It will display the SetCredentialEncrypted option to add in your systemd file. See the "Run" > "Production instance" to see an exemple of such systemd service file.

Warning, the --name switch on the systemd-creds command line must be secrets. Otherwise, your configuration file will not be loaded by the application.

This method is the preferred one if your system on production server is running systemd v250+. In the contrary, you should go for the config.yml solution, and ensuring only the user running the application is able to read you config file (chmod 0600 config/config.yml).

With environment variables

You can use the following environment variables:

BIBERON_BASE_URI
set the base_uri setting.
BIBERON_SESSION_SECRET
set the session_secret setting.
BIBERON_SENDER_EMAIL
set the sender_email setting.
BIBERON_DB_CONNECT_URI
set the db_connect_uri setting.

A quick way to do it locally, is to create a file named .env at the root of this repository, containing the following lines:

export BIBERON_SESSION_SECRET='bliblabluverylongstringohmy'
export BIBERON_BASE_URI=http://127.0.0.1:9292
export BIBERON_SENDER_EMAIL=someone@someserver.tld
export BIBERON_DB_CONNECT_URI=sqlite://db/biberon.db

Environment variables should be avoided on production servers and only be used locally for development purpose.

Run

Development instance

You can start a local server by using the following rake task.

rake server:start

If you want to use an sqlite database, you can use sqlite://db/biberon.db as a value for the environment variable BIBERON_DB_CONNECT_URI. If you prefer to use a mariadb database, you can use the following: mysql://biberon:biberon@127.0.0.1:3306/biberon. And if you need to quickly install a mariadb server, you can use a docker container for that:

docker image pull mariadb
docker volume create biberondb
docker container create --name biberondb \
  -p 3306:3306 \
  -v biberondb:/var/lib/mysql \
  -e MARIADB_USER=biberon \
  -e MARIADB_PASSWORD=biberon \
  -e MARIADB_DATABASE=biberon \
  -e MARIADB_ROOT_PASSWORD=root mariadb
docker start biberondb

Following the same idea, here is how you can start the maildev docker image to spin off a local mail server:

docker image pull maildev/maildev
docker run --rm -d -p 1080:1080 -p 1025:1025 maildev/maildev

Production instance

You can adapt the following systemd service file:

[Unit]
Description=Control Rack Server for Biberons App
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
Environment="PATH=/usr/local/share/rvm/gems/ruby-3.1.2@biberons/bin:/usr/local/share/rvm/gems/ruby-3.1.2@global/bin:/usr/local/share/rvm/rubies/ruby-3.1.2/bin:/usr/local/share/rvm/bin:/usr/local/bin:/usr/bin:/bin"
Environment="GEM_HOME=/usr/local/share/rvm/gems/ruby-3.1.2@biberons"
Environment="GEM_PATH=/usr/local/share/rvm/gems/ruby-3.1.2@biberons:/usr/local/share/rvm/gems/ruby-3.1.2@global"
Environment="RACK_ENV=production"
SetCredentialEncrypted=secrets:Whxqht+dQJax1aZeCGLxmiAAAAABAAAADAAAABAAAABldG79XsgPAktHO+AAAAAATB9IK+aNiGQnilD…
WorkingDirectory=/opt/web/biberon
ExecStart=/usr/local/share/rvm/gems/ruby-3.1.2@biberons/bin/rackup -I ./lib -s puma -E production -P ./tmp/puma.pid -o 127.0.0.1 -p 9595
KillMode=control-group

[Install]
WantedBy=multi-user.target

Test cases

Currently, only models are tested with rspec. You can run the tests with the command rspec.

Warning, if you do not use a specific value for the db_connect_uri value in the test environment, it will fallback on the default configuration, what will remove all your data, as the test runner truncate all tables between test run. See the "Configuration" > "With config.yml file" section for more details on how to provide a configuration file supporting different value per environment.

Credits