risotto/doc/dataset_example/README.md

# Risotto dataset simple examples

This tutorial aims to show how to deploy a [Caddy](https://caddyserver.com/) server via Risotto.

Attention it has no other virtues than to be educational. It is not intended for production use.

## Application services

The project can be divided into three application services:

- caddy-common: an application service containing the information common to the two other application services
- caddy-https: a standalone http/https server
- caddy-https-rp: a https only server served behind a reverse proxy

### caddy-common

Start by creating the project tree:

seed/caddy-common/
├── dictionaries
├── templates
└── manual
    └── image
        └── preinstall

Then describe the application service in [seed/caddy-common/applicationservice.yml](seed/caddy-common/applicationservice.yml).

Also a dictionary [seed/caddy-common/dictionaries/20-caddy.yml](seed/caddy-common/dictionaries/20-caddy.yml) with

- the activation of the caddy service in the "multi-user" target. This service needs some templates:

  - the main configuration's [/etc/caddy/Caddyfile](seed/caddy-common/templates/Caddyfile) to include other /etc/caddy/Caddyfile.d/\*.caddyfile
  - /etc/caddy/Caddyfile.d/risotto.caddyfile with appropriate configuration (this file is not part of this application service)
  - a [sysusers](https://www.freedesktop.org/software/systemd/man/sysusers.d.html) file [/sysusers.d/0caddy.conf](seed/caddy-common/templates/sysuser-caddy.conf) to create the system user "caddy"
  - a [tmpfiles](https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html) file [/tmpfiles.d/0caddy.conf](seed/caddy-common/templates/tmpfile-caddy.conf) to create the directory "caddy_root_directory" and volatile directory "/var/lib/caddy"

- a family "caddy" (Caddy web server) with a filename variable "caddy_root_directory" (The root path of the site) with default value "/srv/caddy". This variable is not used in this service application

Finally, create a script to build the image with the caddy package: [seed/caddy-common/manual/image/preinstall/caddy.sh](seed/caddy-common/manual/image/preinstall/caddy.sh).

### caddy-https

Start by creating the project tree:

seed/caddy-https-rp/
├── dictionaries
└── templates

Then describe the application service in [seed/caddy-https/applicationservice.yml](seed/caddy-https/applicationservice.yml) with OS and caddy-common dependencies.

Also create a dictionary [seed/caddy-https/dictionaries/25-caddy.yml](seed/caddy-https/dictionaries/25-caddy.yml) to define the variables:

- caddy_domain: the domain where Caddy should listen to
- caddy_ca_file, caddy_crt_file and caddy_key_file: certificat for this domain
- redefine the variable incoming_ports to open the ports 80 and 443

And new templates:

- [seed/caddy-https/templates/risotto.caddyfile](seed/caddy-https/templates/risotto.caddyfile)
- [seed/caddy-https/templates/ca_HTTP.crt](seed/caddy-https/templates/ca_HTTP.crt)
- [seed/caddy-https/templates/caddy.key](seed/caddy-https/templates/caddy.key)
- [seed/caddy-https/templates/caddy.crt](seed/caddy-https/templates/caddy.crt)

### caddy-https-rp

Start by creating the project tree:

seed/caddy-https-rp/
├── dictionaries
└── patches
└── templates

Then describe the application service in [seed/caddy-https-rp/applicationservice.yml](seed/caddy-https-rp/applicationservice.yml) with OS, caddy-common and reverse-proxy-client dependencies.

By default, reverse proxy certificate is only readable by "root" user. In the dictionary [seed/caddy-https-rp/dictionaries/25-caddy.yml](seed/caddy-https-rp/dictionaries/25-caddy.yml) we change the user to "caddy".

And add Caddy configuration's file [seed/caddy-https-rp/templates/risotto.caddyfile](seed/caddy-https-rp/templates/risotto.caddyfile).

Finally add a patch to modify Caddyfile to not starts Caddy in port 80: [seed/caddy-https-rp/patches/Caddyfile.patch](seed/caddy-https-rp/patches/Caddyfile.patch).
Patches should only use if a template file is define in an other dataset. You should instead add a condition in the template. But for educational reasons we made a patch in this case.

## Infrastructure

The infrastructure is define in a uniq YAML file: servers.yml:

### Zones

The idea:

- separate the networks according to the uses
- there is no route to each other

Ideally only one area has an Internet access.
Internet access is, in fact, firewall rules.
This network is usually called "external".

The other networks are only there for the communication between server and client.

The host must have an IP in this network.
IP inside this network are deliver automaticly.

A network is call a "zone".

### Modules

A module is simply a list of application services. An system image is build with informations define in application service.

### Hosts

A host is a server on which container or VM are running.
Define the host means define:

- application services to configure the host and VM
- application service provider to define the provider to apply on each VM
- values to adapt the configuration
- servers, the list of VM with :

  - the corresponding module
  - informations (like zone)
  - values

Host must only be a Debian 11 (Bullseye) from now.

### Examples

- Caddy as HTTPS server: [servers.yml](servers.yml.caddy-https)
- Caddy behind a Nginx reverse proxy: [servers.yml](servers.yml.caddy-https-rp)

You must add a index.html file in "/var/lib/risotto/srv/caddy.in.example.net/caddy/".

## risotto.conf

```toml
[directories]
datasets = ['<path_to_dataset_base>/seed', 'seed']
dest = 'installations'
dest_templates = 'templates'

[cert_authority]
email = '<email>'
country = 'FR'
locality = 'Dijon'
state = 'France'
org_name = 'Silique'
org_unit_name = 'Cloud'
```