`service`

content/baguette/index.md

@@ -767,56 +767,72 @@ Ports:
 ```
 
 **`Service`: a service example.**<br />
-A service configuration has two parts: the service description and its configuration file template(s).
-Let's use `gitea` as example, the `git` web server handling [our repositories][baguette-gitea].
+A service is defined by its description in a `.spec` file and its template(s).
+Let's use `gitea` as an example, the `git` web server handling [our repositories][baguette-gitea].
 
 ```YAML
 # `gitea.spec`
 
-# The actual command to run to start the service
+# The command which is run to start the service.
 command: gitea -C . -w . -c gitea.cfg
 
-# what tokens the service needs, see that http is optional
+# The tokens needed by the service. Here http is optional.
 consumes: database, http?
 
-# does the service requires a domain name to be configured?
-# this name may be used in the service configuration, or its (forward|backward) dependencies
+# Does the service require a domain name to be configured?
+# If so, service will require a "domain" token, such as `service add $service domain=example.com`
+# This name may be used in the service configuration, or its (forward or backward) dependencies.
 requires-domain: true
 
-# the service requires a simgle port to be open
-# by default, 80
+# The port(s) the service requires.
+# By default, if a service requires a port named "http", its value will be 80.
 ports: http
 
-# `%configuration` indicates the name of the configuration template
+# `%configuration` indicates the name of the configuration template.
+# For example, if the template file is `/usr/baguette/service/templates/gitea.cfg.j2`:
 %configuration gitea.cfg
 ```
 
 *We **currently** use a bit more configuration for the database, but we will get there at some point.*
 
-Now, a quick look at its configuration template. *just a sample, we'll skip most, don't worry*<br />
+Now, a quick look at the `gitea` configuration template. <side-note>*just a sample, we'll skip most, don't worry*</side-note><br />
 Templating is done with `Jinja2` templates: [see more about Jinja2 templating][crinja].
 
+First, let's say we created a `gitea` service this way:
+```zsh
+service add gitea domain=example.com database=postgresql
+```
+
+Now, we want to see the template used to configure `gitea`.
+
 ```YAML
 [database]
-# providers = list of services behind the tokens
-# for example: behind 'database' there is a `postgresql` service
-# and we want the main port to use (for a database, 'ports.main' = port to access it remotely)
+# `service` passes data to the templates.
+# `providers` is the list of services behind the tokens used.
+# For example, behind "providers.database" there is a `postgresql` service.
+
+# Gitea needs to establish a connection to its database.
+# The database ports can be accessed with "database.ports".
+# The port used to connect to the database is named "main" by convention.
 # See the definition of the postgresql service for details.
 HOST     = 127.0.0.1:{{ providers.database.ports.main }}
 
-# we have to enter the database name
-# by default, databases are configured with a name convention as follow: environment_service_db
-# service.id is 'environment/service', which identifies uniquely the service
-# to get the right database name, we should take the service.id template variable and replace the "/" by "_" then add "_db"
+# Here, the template requires the database name.
+# By convention, databases are named: $environment_$service_db.
+# In our example, `service` creates the database "root_gitea_db", as the default environment is "root".
+# `service.id` is '$environment/$service', which uniquely identifies the service.
+# In our example, `service.id` is "root/gitea".
+# The database name will be obtained by replacing "/" by "_" and adding "_db" to the service.id variable.
+# This is performed this way:
 NAME     = {{ service.id | replace("/", "_") }}_db
 
-# by default, the user name is identical to the database name, but without the "_db" suffix
+# By convention the user name is identical to the database name without the "_db" suffix.
 USER     = {{ service.id | replace("/", "_") }}
 
-# we have created the `random_password` function, taking a service id in parameter
-# `random_password` creates a unique password the first time it is called
-# after that, it provides the same password each time it is called with the same service id
-# `random_password` enables sharing a password between two service configurations
+# The `random_password` function creates a unique password the first time it is called.
+# This function takes a service id in parameter.
+# After that, it provides the same password each time it is called with the same service id.
+# `random_password` enables sharing a password between two service configurations.
 PASSWD   = {{ random_password( service.id ) }}
 
 [repository]
@@ -832,8 +848,8 @@ ROOT_URL         = http://{{ service.domain }}:{{ service.ports.http }}/
 
 **Current implementation of `service`**<br />
 It [currently works][working-service-asciinema], and we just need to add more services!
-Every new corner case will be thoroughly investigated to provide the smoothest experience possible under BaguetteOS.
-We currently use it for a few services, such as the nginx providing this very website.
+Every new corner case will be thoroughly investigated to provide the smoothest experience possible with BaguetteOS.
+We currently use it for the nginx providing this very website.
 
 Currently, there are no fancy environments, just plain directories.
 
@@ -842,7 +858,7 @@ First, we want to work on databases, to export data and get a simple backup serv
 
 Then, we could let users manage their own services, but this is of little interest in practice since services are running under different users already.
 
-The most useful thing to do right now is to provide new services.
+The most useful contributions right now would be to provide new service configurations.
 
 [Back to top](#top)