path: root/README.org
blob: bf14762734e6c7c25217992fb826fc37bf5f0494 (plain) (tree)




















#+title: Biberon app

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.
- ~publish_folder~ :: Where to upload your website (via the ~server:publish~
  rake task, which use ~rsync~ internally). On your production server, this
  settings does not need to be set.
- ~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
- ~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.yml~ file at the
root of your installation, as [[https://systemd.io/CREDENTIALS/][systemd service credentials]], as environment
variables, or a combination of the three.

When the application starts, it reads its configuration first from the
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.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:

#+begin_src yaml
  base_uri: "https://example.com"
  session_secret: bliblabluverylongstringohmy
  sender_email: someone@someserver.tld
  db_connect_uri: "mysql://biberon: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:

#+begin_src yaml
  production: &default
    base_uri: "https://example.com"
    session_secret: bliblabluverylongstringohmy
    sender_email: someone@someserver.tld
    db_connect_uri: "mysql://biberon:biberon@"
    <<: *default
    base_uri: ""
    db_connect_uri: "sqlite://db/biberon.db"
    <<: *default
    db_connect_uri: "sqlite://db/test.db"

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

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.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:

#+begin_src yaml
  base_uri: "https://example.com"
  session_secret: bliblabluverylongstringohmy
  sender_email: someone@someserver.tld
  db_connect_uri: "mysql://biberon: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

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.yml~).

** With environment variables

You can use the following environment variables:

- ~BIBERON_BASE_URI~ :: set the ~base_uri~ setting.
- ~BIBERON_PUBLISH_FOLDER~ :: set the ~publish_folder~ 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_PUBLISH_FOLDER=myserver.com:/opt/web/biberon/
  export BIBERON_SESSION_SECRET='bliblabluverylongstringohmy'
  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.

#+begin_src shell
  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@ And if you need to quickly
install a mariadb server, you can try to use a docker container for that:

  docker image pull mariadb
  docker volume create biberondb
  docker 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:

  Description=Control Rack Server for Biberons App

  ExecStart=/usr/local/share/rvm/gems/ruby-3.1.2@biberons/bin/rackup -I ./lib -s puma -E production -P ./tmp/puma.pid -o -p 9595


** 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

* Credits

- CSS framework: https://milligram.io/
- Icons: https://iconoir.com/
- Baby bottle favicon: https://openclipart.org/detail/263557/baby-boy-accessories
- Baby feeding background picture: https://undraw.co/