Add basic, initial documentation on services

This includes initial coverage for Redis and MariaDB, and establishes a
template for future work. There's a lot of ground left to cover, however.

README.md

@@ -3,7 +3,7 @@
 This repository contains support files for deploying a simple server setup based on Fedora CoreOS,
 and mainly based around [systemd](https://systemd.io) and [Podman](https://podman.io).
 
-## Pre-requisites
+## Prerequisites
 
 Effective use of the source-files here requires that you have the following dependencies installed
 on your host:
@@ -63,16 +63,13 @@ parameter to the `make` invocation.
 By default, you can use the `<Ctrl>]` key-combination to escape the virtual machine, and can use the
 `make destroy-virtual` command to drop any resources initialized for the virtual host.
 
-## Services
+## Included Services
 
 In addition to host-specific configuration, servers will typically include a number of services,
 managed by `systemd` and `podman`. These are intended to be deployed via Ignition on server setup,
 but also be managed throughout the server's life-cycle.
 
-The mechanisms for building and deploying services are simple and fairly consistent. Firstly, Podman
-containers and systemd services are built and enabled using the included `container-build` systemd
-service. This will read files from `/etc/coreos-home-server` (copied onto the server during
-deployment) and build container images and systemd service definitions as needed.
+Check the [service documentation](config/service/README.md) for more information.
 
 ## License
 

config/service/README.md

@@ -0,0 +1,39 @@
+# CoreOS Service Configuration
+
+This directory contains a set of common services available for deployment onto a CoreOS Home Server
+setup, and managed via systemd and Podman. Each service is given its own subdirectory, and each
+follows a set of common conventions in laying out its files.
+
+Specifically, for a service `example`, we might find the following files and directories under the
+corresponding directory:
+
+  - `spec.bu` -- This file is typically included by the host configuration, and is intended with
+    installing any additional service files required for enabling the service.
+
+  - `Containerfile` -- This file is used in building a container image, handled by the
+    `container-build@example` service and presumably used in the systemd file for the `example`
+    service.
+    
+  - `example.env.template` -- An optional file containing `KEY=value` definitions that can then be
+    used in the systemd service. Host-wide environment is also available in this context, and can be
+    used in expanding shared configuration, secrets, etc. This file is used by the
+    `container-environment@example` service.
+    
+  - `systemd/` -- This directory contains systemd configuration, to be copied into the host-wide
+    `/etc/systemd/system` directory. You'll typically find things like `example.service` files
+    which run the service under Podman, as well as potential one-off services which copy files
+    around in pre-existing Podman containers.
+
+  - `container/` -- This directory contains any static files included in the Podman image, including
+    templated configuration, scripts, etc.
+
+  - `service/` -- This (largely optional) directory contains files required by the systemd services
+    themselves, and which are not included in the Podman images by default; examples include
+    database migration files, one-off configuration files, etc.
+
+Of all these files, the only ones whose paths are mandated by external services are the
+`Containerfile` and `<name>.env.template` files, neither of which are required by anything other
+than convention (i.e. you can choose not to build a container image via the systemd service).
+
+Each service here might have additional details on how it's expected to be deployed and used, check
+the respective `README.md` files for more information.

config/service/mariadb/README.md

@@ -0,0 +1,61 @@
+# MariaDB
+
+This directory contains a simple systemd service for running an instance of MariaDB 10.6.
+
+## Deployment and Use
+
+Including the `spec.bu` file here in your host configuration is enough to have MariaDB enabled on the
+system -- no other configuration is needed. The following commands will manage the service
+accordingly:
+
+  - Starting MariaDB: `sudo systemctl start mariadb`
+  - Stopping MariaDB: `sudo systemctl stop mariadb`
+  - Getting logs for the running service: `journalctl -feu mariadb`
+
+By default, MariaDB listens on the `internal` network under the `mariadb` hostname, port 3306. Any
+services that wish to connect to MariaDB for that hostname and port need to also be included in the
+`internal` network.
+
+The systemd service for MariaDB tries to delay readiness checks for until the listener is correctly
+set up, and will run periodic health-checks to ensure the same.
+
+## Use
+
+Depending on MariaDB from other systemd services is as simple as declaring an ordered dependency in
+the systemd service file, for example:
+
+```ini
+[Unit]
+Description=Service That Uses MariaDB
+Wants=container-build@example.service mariadb.service
+After=container-build@example.service mariadb.service
+```
+
+MariaDB will then be guaranteed to be running before the example service is.
+
+## Database Migrations
+
+Services can define an initial state for databases used internally by way of special
+`mariadb-migrate.sql` files, which are used by the included `mariadb-migrate@` service. 
+
+For example, given a service `example` (in its own directory), we would need a file
+`example/service/mariadb-migrate.sql`, containing SQL calls for creating databases, users:
+
+```sql
+-- Create default database.
+CREATE DATABASE IF NOT EXISTS `${EXAMPLE_DATABASE_NAME}`;
+
+-- Create default user with pre-defined password.
+CREATE USER IF NOT EXISTS '${EXAMPLE_DATABASE_USERNAME}'@'%' IDENTIFIED BY '${EXAMPLE_DATABASE_PASSWORD}';
+GRANT ALL PRIVILEGES ON `${EXAMPLE_DATABASE_NAME}`.* TO '${EXAMPLE_DATABASE_USERNAME}'@'%';
+```
+
+As evidenced above, this file can also have environment variables defined, which are derived from the
+service-specific `example/example.env.template` file (if any exists). Running these migrations is as
+simple a matter as running the aforementioned service, e.g.:
+
+```
+sudo systemctl start mariadb-migrate@example 
+```
+
+The systemd journal should provide evidence of execution and reference to any issues that may have occured.

config/service/redis/README.md

@@ -0,0 +1,34 @@
+# Redis
+
+This directory contains a simple systemd service for running a disk-backed instance of Redis.
+
+## Deployment
+
+Including the `spec.bu` file here in your host configuration is enough to have Redis enabled on the
+system -- no other configuration is needed. The following commands will manage the service
+accordingly:
+
+  - Starting Redis: `sudo systemctl start redis`
+  - Stopping Redis: `sudo systemctl stop redis`
+  - Getting logs for the running service: `journalctl -feu redis`
+
+By default, Redis listens on the `internal` network under the `redis` hostname, port 6379. Any
+services that wish to connect to Redis for that hostname and port need to also be included in the
+`internal` network.
+
+By default, a named volume is created for `redis` which is used for restoring databases on service
+restart.
+
+## Use
+
+Depending on Redis from other systemd services is as simple as declaring an ordered dependency in
+the systemd service file, for example:
+
+```ini
+[Unit]
+Description=Service That Uses Redis
+Wants=container-build@example.service redis.service
+After=container-build@example.service redis.service
+```
+
+Redis will then be guaranteed to be running before the example service is.