docs: add outline docs

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"

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"

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.