feat: automatically backup and migrate upon version upgrade of outline

ansible/roles/outline/handlers/main.yml

@@ -0,0 +1,29 @@
+---
+
+# Mark migration as started
+# Ensures migration critical processes will be continued upon abortion
+- name: "Create migration marker"
+  become_user: "outline"
+  become: true
+  ansible.builtin.file:
+    path: "{{ outline_config.project_source }}/.MIGRATION_PENDING"
+    state: "touch"
+    owner: "outline"
+    group: "outline"
+  listen: "trigger outline migration"
+
+
+- name: "Ensure outline is offline"
+  community.docker.docker_compose_v2:
+    project_src: "{{ outline_config.project_source }}"
+    state: "absent"
+  listen: "backup outline"
+  # TODO create a maintenance mode?
+
+- name: "Make backup of outline database"
+  become_user: "root"
+  become: true
+  ansible.builtin.systemd:
+    name: "backup-postgres.service"
+    state: "started"
+  listen: "backup outline"

ansible/roles/outline/tasks/main.yml

@@ -10,7 +10,7 @@
 
 - name: "Create outline directory"
   ansible.builtin.file:
-    path: "{{ outline_project_source }}"
+    path: "{{ outline_config.project_source }}"
     state: "directory"
     owner: "outline"
     group: "outline"
@@ -31,32 +31,56 @@
       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: "Update configuration and migrate if needed"
+  become_user: "outline"
+  become: true
+  block:
 
-- name: "Create outline 'docker-compose.yml' file"
-  ansible.builtin.template:
-    src: "docker-compose.yml.j2"
-    dest: "{{ outline_project_source }}/docker-compose.yml"
-    owner: "outline"
-    group: "outline"
-    mode: "0600"
+  - name: "Create outline 'docker-compose.yml' file"
+    ansible.builtin.template:
+      src: "docker-compose.yml.j2"
+      dest: "{{ outline_config.project_source }}/docker-compose.yml"
+      owner: "outline"
+      group: "outline"
+      mode: "0600"
+    notify: "trigger outline migration"
+
+  - name: "Create outline 'docker.env' file"
+    ansible.builtin.template:
+      src: "docker.env.j2"
+      dest: "{{ outline_config.project_source }}/docker.env"
+      owner: "outline"
+      group: "outline"
+      mode: "0600"
+    notify: "trigger outline migration"
+
+  - name: "Check if migration must be triggered"
+    ansible.builtin.meta: "flush_handlers"
+
+  - name: "Check if migration has been triggered"
+    ansible.builtin.stat:
+      path: "{{ outline_config.project_source }}/.MIGRATION_PENDING"
+      get_checksum: "no"
+      get_attributes: "no"
+      get_mime: "no"
+    register: "outline_update_marker"
+    changed_when: "outline_update_marker.stat.exists"
+    notify: "backup outline"
+    # NOTE Migration will automatically start the next time outline starts
+
+  - name: "Start handeling migration if needed"
+    ansible.builtin.meta: "flush_handlers"
+
+  - name: "Remove migration marker"
+    ansible.builtin.file:
+      path: "{{ outline_config.project_source }}/.MIGRATION_PENDING"
+      state: "absent"
 
-- name: "Create outline 'docker.env' file"
-  ansible.builtin.template:
-    src: "docker.env.j2"
-    dest: "{{ outline_project_source }}/docker.env"
-    owner: "outline"
-    group: "outline"
-    mode: "0600"
 
 - name: "Docker compose"
   ansible.builtin.include_tasks: "../docker/tasks/compose-up.yml"
   vars:
-    project_source: "{{ outline_project_source }}"
+    project_source: "{{ outline_config.project_source }}"
 
 - name: "Install nginx config"
   ansible.builtin.template:

ansible/roles/outline/templates/docker-compose.yml.j2

@@ -1,7 +1,9 @@
+# Ansible managed
+
 services:
 
   outline:
-    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.
+    image: outlinewiki/outline:{{ outline_config.version }}
     env_file: ./docker.env
     #    ports:
     #      - "4568:3000"
@@ -43,29 +45,6 @@ services:
       #      POSTGRES_PASSWORD: 'pass'
       #      POSTGRES_DB: 'outline'
 
-        #  https-portal:
-        #    image: steveltn/https-portal
-        #    env_file: ./docker.env
-        #    ports:
-        #      - '80:80'
-        #      - '443:443'
-        #    links:
-        #      - outline
-        #    restart: always
-        #    volumes:
-        #      - https-portal-data:/var/lib/https-portal
-        #    healthcheck:
-        #      test: ["CMD", "service", "nginx", "status"]
-        #      interval: 30s
-        #      timeout: 20s
-        #      retries: 3
-        #    environment:
-        #      DOMAINS: 'docs.mycompany.com -> http://outline:3000'
-        #      STAGE: 'production'
-        #      WEBSOCKET: 'true'
-        #      CLIENT_MAX_BODY_SIZE: '0'
-
 volumes:
-        # https-portal-data:
   storage-data:
-          # database-data:
+  # database-data:

ansible/roles/outline/vars/main.yml

@@ -1,2 +1,5 @@
 ---
-outline_project_source: "/var/www/outline/outline"
+
+outline_config:
+  project_source: "/var/www/outline/outline"
+  version: "0.78.0"

docs/outline.md

@@ -15,17 +15,24 @@ website:
 
 ## Creating a new database and/or migrating
 
-Outline databases are maintained (and created?) using migrations. When updating
+Outline databases are maintained 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.
+When no database exists yet, create an empty one and trigger the database migration.
 
 For both scenarios, I would like to refer you to [the official documentation](https://docs.getoutline.com/s/hosting/doc/docker-7pfeLP5a8t).
 
+**However**, this has already been automized in Ansible. When a configuration
+file belonging to outline is updated, the database will automatically be backed
+up.
+
 ## 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.
+
+To specify which version to use (and to automatically downgrade or upgrade),
+edit the value in `roles/outline/vars/main.yml`.