From 4e0bf6534a2cab4aa36bbd619cf6211716ee0e85 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julian-Samuel=20Geb=C3=BChr?= <julian-samuel@gebuehr.net>
Date: Wed, 19 Jul 2023 00:08:42 +0200
Subject: [PATCH] Add documentation

---
 docs/services/ilmo.md      | 99 ++++++++++++++++++++++++++++++++++++++
 docs/supported-services.md |  1 +
 2 files changed, 100 insertions(+)
 create mode 100644 docs/services/ilmo.md

diff --git a/docs/services/ilmo.md b/docs/services/ilmo.md
new file mode 100644
index 0000000..effec06
--- /dev/null
+++ b/docs/services/ilmo.md
@@ -0,0 +1,99 @@
+# ILMO
+
+[Ilmo](https://github.com/moan0s/ILMO2) is an open source library management tool.
+
+Read [the documentation](https://ilmo2.readthedocs.io/) to learn what you can do with it.
+
+**Warning**: This service is a custom solution for a small library. Feel free to use it but don't expect a solution that works for every use case
+
+## Dependencies
+
+This service requires the following other services:
+
+- a [Postgres](postgres.md) database
+- a [Traefik](traefik.md) reverse-proxy server
+
+
+## Configuration
+
+To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:
+
+```yaml
+########################################################################
+#                                                                      #
+# ilmo                                                                 #
+#                                                                      #
+########################################################################
+
+ilmo_enabled: true
+ilmo_hostname: ilmo.example.com
+ilmo_instance_name: "My library"
+
+########################################################################
+#                                                                      #
+# /ilmo                                                                #
+#                                                                      #
+########################################################################
+```
+
+## Setting up the first user
+
+You need to create a first user (unless you import an existing database).
+You can do this conveniently by running
+
+```bash
+just run-tags ilmo-add-superuser --extra-vars=username=USERNAME --extra-vars=password=PASSWORD --extra-vars=email=EMAIL
+```
+
+## Usage
+
+After installation, you can go to the ILMO URL, as defined in `ilmo_hostname`. Log in with the user credentials from above.
+
+Follow the [ILMO documentation](https://ilmo2.readthedocs.io/en/latest/index.html) to learn how to use ILMO.
+
+## Migrate an existing instance
+
+The following assumes you want to migrate from `serverA` to `serverB` (managed by mash) but you just cave to adjust the copy commands if you are on the same server.
+
+Stop the initial instance on `serverA`
+
+```bash
+serverA$ systemctl stop ilmo
+```
+
+Dump the database (depending on your existing setup you might have to adjust this)
+```
+serverA$ pg_dump ilmo > latest.sql
+```
+
+Copy the files to the new server
+
+```bash
+serverA$ rsync -av -e "ssh" latest.sql root@serverB:/mash/ilmo/
+serverA$ rsync -av -e "ssh" data/* root@serverB:/mash/ilmo/data/
+```
+
+Install (but don't start) the service and database on the server and import the database.
+
+```bash
+yourPC$ just run-tags install-postgres
+yourPC$ just run-tags install-ilmo
+yourPC$ just run-tags import-postgres --extra-vars=server_path_postgres_dump=/mash/ilmo/latest.sql --extra-vars=postgres_default_import_database=mash-ilmo
+```
+
+Start the services on the new server
+
+```bash
+yourPC$ just run-tags start
+```
+
+Done 🥳
+
+### Troubleshooting
+
+If you by accident started the service before importing the database you should
+
+* stop the service
+* use `/mash/postgres/bin/cli` to get a database interface
+* Delete the existing database (THIS WILL DELETE ALL DATA!) `DROP DATABASE ilmo WITH (FORCE);`
+* Continue from "Install (but don't start) the service and database on the server and import the database."
diff --git a/docs/supported-services.md b/docs/supported-services.md
index e98bddf..7c57be6 100644
--- a/docs/supported-services.md
+++ b/docs/supported-services.md
@@ -20,6 +20,7 @@
 | [Grafana](https://grafana.com/) | An open and composable observability and data visualization platform, often used with [Prometheus](services/prometheus.md) | [Link](services/grafana.md) |
 | [Healthchecks](https://healthchecks.io/) | A simple and Effective Cron Job Monitoring solution | [Link](services/healthchecks.md) |
 | [Hubsite](https://github.com/moan0s/hubsite) | A simple, static site that shows an overview of the available services | [Link](services/hubsite.md) |
+| [ILMO](https://github.com/moan0s/ILMO2) | An open source library management tool. | [Link](services/ilmo.md) |
 | [Infisical](https://infisical.com/) | An open-source end-to-end encrypted platform for securely managing secrets and configs across your team, devices, and infrastructure. | [Link](services/infisical.md) |
 | [InfluxDB](https://www.influxdata.com/) | A self-hosted time-series database. | [Link](services/influxdb.md) |
 | [Jitsi](https://jitsi.org/) | A fully encrypted, 100% Open Source video conferencing solution | [Link](services/jitsi.md) |