aboutsummaryrefslogtreecommitdiffstats
path: root/README.org
blob: bf14762734e6c7c25217992fb826fc37bf5f0494 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
#+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
  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.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@127.0.0.1:3306/biberon"
#+end_src

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@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"
#+end_src

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.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@127.0.0.1:3306/biberon"
#+end_src

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

#+begin_src
  sudo systemd-creds encrypt -p --name=secrets secrets.yml -
#+end_src

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

#+begin_src
  export BIBERON_PUBLISH_FOLDER=myserver.com:/opt/web/biberon/
  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
#+end_src

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
#+end_src

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 try to use a docker container for that:

#+begin_src
  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
#+end_src

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

#+begin_src
  docker image pull maildev/maildev
  docker run --rm -d -p 1080:1080 -p 1025:1025 maildev/maildev
#+end_src

** Production instance

You can adapt the following systemd service file:

#+begin_src
  [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
#+end_src

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

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