From 03d2996fa3cd9efe264bb2111a151df24156f78e Mon Sep 17 00:00:00 2001
From: Silas <69711739+SilasPeters@users.noreply.github.com>
Date: Sat, 27 Jul 2024 00:25:32 +0200
Subject: [PATCH] docs: add outline docs

---
 ansible/roles/outline/tasks/main.yml          |  8 ++++-
 .../outline/templates/docker-compose.yml.j2   |  3 +-
 docs/outline.md                               | 31 +++++++++++++++++++
 3 files changed, 40 insertions(+), 2 deletions(-)
 create mode 100644 docs/outline.md

diff --git a/ansible/roles/outline/tasks/main.yml b/ansible/roles/outline/tasks/main.yml
index 65c7a374..e11f4aaf 100644
--- a/ansible/roles/outline/tasks/main.yml
+++ b/ansible/roles/outline/tasks/main.yml
@@ -22,7 +22,7 @@
   - name: "Ensure Postgres role exists"
     community.postgresql.postgresql_user:
       name: "outline"
-      password: "{{ secret_outline.postgresql_password }}" # Sadly seems required to make authentication over localhost work, for peer authentication fails somehow
+      password: "{{ secret_outline.postgresql_password }}" # TODO Sadly seems required to make authentication over localhost work, for peer authentication fails somehow. Perhaps docker networks can make this easier.
       state: "present"
 
   - name: "Ensure database exists"
@@ -31,6 +31,12 @@
       owner: "outline"
       state: "present"
 
+# TODO this task assumes the database has already been migrated by Outline to
+# have the correct scheme. See `docs/outline.md` for more info.
+# Later on, when the database will be hosted in another docker service, this
+# migration should be done as well here (but be careful for data loss.
+# Backups?).
+
 - name: "Create outline 'docker-compose.yml' file"
   ansible.builtin.template:
     src: "docker-compose.yml.j2"
diff --git a/ansible/roles/outline/templates/docker-compose.yml.j2 b/ansible/roles/outline/templates/docker-compose.yml.j2
index 690ade4d..d59c80e8 100644
--- a/ansible/roles/outline/templates/docker-compose.yml.j2
+++ b/ansible/roles/outline/templates/docker-compose.yml.j2
@@ -1,7 +1,8 @@
 services:
 
   outline:
-    image: outlinewiki/outline:0.78.0
+    image: outlinewiki/outline:0.78.0 # NOTE when bumping this, see `docs/outline.md#Updating to a newer version`
+		# Basically, backup before updating, for a migration will happen automatically upon updating.
     env_file: ./docker.env
     #    ports:
     #      - "4568:3000"
diff --git a/docs/outline.md b/docs/outline.md
new file mode 100644
index 00000000..03bfb98b
--- /dev/null
+++ b/docs/outline.md
@@ -0,0 +1,31 @@
+# Outline configuration
+
+The `docker.env` file contains many configurations, but some configurations must
+be done through the website itself - the settings page. These settings are
+stored in the database, and thus not expressed through the `docker.env` file.
+
+When creating a new database, the following settings must be set through the
+website:
+
+- Arbitrary members should be viewers, and admins (board members and such) should
+  be editors. Whilst it does not fully match this logic, the default role for
+  new members must be set to `viewer` and not `editor`.
+- Logging in should only be done through our OAuth provider. Thus, logging in
+  through email should be disabled.
+
+## Creating a new database and/or migrating
+
+Outline databases are maintained (and created?) using migrations. When updating
+the outline version, one _must_ create a backup beforehand, for the
+documentation states that the database will automatically be migrated once the
+service starts.
+
+When no database exists yet, this can be created by migrating/seeding.
+
+For both scenarios, I would like to refer you to [the official documentation](https://docs.getoutline.com/s/hosting/doc/docker-7pfeLP5a8t).
+
+## Updating to a newer version
+
+When updating outline to the latest version, please make a backup beforehand!
+As explained in the section above, the next time outline starts, a database
+migration will automatically occur.