adds maintenance and updates readme

MAINTENANCE.md

@@ -0,0 +1,32 @@
+# Outline Recipe Maintenance
+
+All contributions should be made via a pull request. This is to ensure a
+certain quality and consistency, that others can rely on.
+
+## Maintainer Responsibilities
+
+A recipe maintainer has the following responsibilities:
+
+- Respond to pull requests / issues within two weeks
+- Make image security updates within a week
+- Make image major updates every three months
+
+In order to fullfill these responsibilities a recipe maintainer:
+
+- Has to watch the repository (to get notifications)
+- Needs to make sure renovate is configured properly
+
+## Pull Requests
+
+A pull request can be merged if it is approved by at least one maintainer. For
+pull requests opened by a maintainer they need to be approved by another
+maintainer. Even though it is okay to merge a pull request with one approval, it
+is always better if all maintainers looked at the pull request and approved it.
+
+## Become a maintainer
+
+Everyone can apply to be a recipe maintainer:
+1. Watch the repository to always get updates
+2. Simply add your self to the list in the [README.md](./README.md) and open a new pull request with the change.
+3. Once the pull request gets merged you will be added to the [outline maintainers team](https://git.coopcloud.tech/org/coop-cloud/teams/outline-maintainers).
+4. Join the room [#cc-|-outline-maintenance:matrix.org](#cc-|-outline-maintenance:matrix.org) and chat to other maintainers.

README.md

@@ -3,7 +3,7 @@
 Wiki and knowledge base for growing teams
 
 <!-- metadata -->
-
+* **Maintainer**: Local-IT: [@moritz](https://git.coopcloud.tech/moritz), [@msimon](https://git.coopcloud.tech/simon), [@carla](https://git.coopcloud.tech/carla)
 * **Category**: Apps
 * **Status**: 3, stable
 * **Image**: [outlinewiki/outline](https://hub.docker.com/r/outlinewiki/outline), 4, upstream
@@ -21,9 +21,9 @@ Wiki and knowledge base for growing teams
 2. Deploy [`coop-cloud/traefik`]
 3. `abra app new outline`
 4. Insert secrets:
-    - `abra app secret insert <APP-DOMAIN> secret_key v1 $(openssl rand -hex 32)`
-    - `abra app secret generate -a <APP-DOMAIN>`
-5. `abra app deploy <APP-DOMAIN>`
+    - `abra app secret insert YOURAPPNAME secret_key v1 $(openssl rand -hex 32)`
+    - `abra app secret generate -a YOURAPPNAME`
+5. `abra app deploy YOURAPPNAME`
 6. Open the configured domain in your browser to finish set-up
 
 [`abra`]: https://git.coopcloud.tech/coop-cloud/abra
@@ -33,8 +33,8 @@ Wiki and knowledge base for growing teams
 
 ### Create an initial admin user
 
-```sh
-abra app cmd <APP-DOMAIN> app create_email_user test@example.com
+```
+abra app cmd YOURAPPNAME app create_email_user test@example.com
 ```
 
 ### Setting up your `.env` config
@@ -43,65 +43,49 @@ Avoid the use of quotes (`"..."`) as much as possible, the NodeJS scripts flip o
 
 ### Deleting a user (e.g. to fix SSO weirdness)
 
-`abra app cmd <APP-DOMAIN> db delete_user <USERNAME-TO-DELETE> <USERNAME-TO-REPLACE>`
+`abra app cmd YOURAPPNAME db delete_user <username-to-delete> <username-to-replace>`
 
-Where `<USERNAME-TO-DELETE>` is the username of the user to be removed, and
-`<USERNAME-TO-REPLACE>` is the username of another user, to assign documents and
+Where `<username-to-delete>` is the username of the user to be removed, and
+`<username-to-replace>` is the username of another user, to assign documents and
 revisions to (instead of deleting them).
 
 ### Migrate from S3 to local storage
 
-1. `abra app config <APP-DOMAIN>`, add
-   * `COMPOSE_FILE="$COMPOSE_FILE:compose.local.yml"`
-   * `FILE_STORAGE_UPLOAD_MAX_SIZE=26214400`
-
-2. `abra app deploy <APP-DOMAIN> -f`
-   * `compose.aws.yml` should still be deployed!
-
-3. `abra app undeploy <APP-DOMAIN>`
-
-4. On the docker host, find mount *point of newly created volume via `docker volume ls` and `docker volume inspect`
-
-    * volume name is something like `<APP-DOMAIN>_storage-data`
-    * take note which Linux user owns `<STORAGE_MOUNTPOINT>` (likely `1001`)
-    * use s3cmd/rclone/... to sync your bucket to `<STORAGE_MOUNTPOINT>`
-
-5. `chown -R <STORAGE_USER>:<STORAGE_USER> <STORAGE_MOUNTPOINT>`
-
-6. `abra app config <APP-DOMAIN>`, switch storage back-end
-
-   * remove `AWS_*` vars, `SECRET_AWS_SECRET_KEY_VERSION` and `COMPOSE_FILE="$COMPOSE_FILE:compose.aws.yml"`
-   * set `FILE_STORAGE=local`
-
-7. `abra app deploy <APP-DOMAIN> -f`
-
-8. Enjoy getting rid of S3 🥳
+- `abra app config <domain>`, add
+  - `COMPOSE_FILE="$COMPOSE_FILE:compose.local.yml"`
+  - `FILE_STORAGE_UPLOAD_MAX_SIZE=26214400`
+- `abra app deploy <domain> -f`
+  - compose.aws.yml should still be deployed!
+- `abra app undeploy <domain>`
+- on the docker host, find mountpoint of newly created volume via `docker volume ls` and `docker volume inspect`
+  - volume name is smth like `<domain>_storage-data`
+- take note which linux user owns `<storage_mountpoint>` (likely `1001`)
+- use s3cmd/rclone/... to sync your bucket to `<storage_mountpoint>`
+- `chown -R <storage_user>:<storage_user> <storage_mountpoint>`
+- `abra app config <domain>`, switch storage backend
+  - remove `AWS_*` vars, `SECRET_AWS_SECRET_KEY_VERSION` and `COMPOSE_FILE="$COMPOSE_FILE:compose.aws.yml"`
+  - set `FILE_STORAGE=local`
+- `abra app deploy <domain> -f`
+- enjoy getting rid of S3 🥳
 
 ## Single Sign On with Keycloak/Authentik
 
-1. Create an OIDC client in Keycloak (in Authentik this is called a provider and application)
-2. Run `abra app config <APP-DOMAIN>`, then uncomment everything in the `OIDC_` section.
-
-    * **Valid Redirect URIs**: `https://<APP-DOMAIN>/auth/oidc.callback`
-    * Reference the client/provider info to populate the `OIDC_AUTH_URI` `OIDC_TOKEN_URI` and `OIDC_USERINFO_URI` values
-
-3. Set the OIDC secret using the value from the client/provider `abra app secret insert <APP-DOMAIN> oidc_client_secret v1 "<SECRET_VALUE>"`
-4. `abra app deploy <APP-DOMAIN>`
+- Create an OIDC client in Keycloak (in Authentik this is called a provider and application)
+- Run `abra app config YOURAPPNAME`, then uncomment everything in the `OIDC_` section.
+  - **Valid Redirect URIs**: `https://YOURAPPDOMAIN/auth/oidc.callback`
+  - Reference the client/provider info to populate the `_AUTH_URI` `_TOKEN_URI` and `_USERINFO_URI` values
+- Set the OIDC secret using the value from the client/provider `abra app secret insert YOURAPPNAME oidc_client_secret v1 SECRETVALUE`
+- `abra app deploy YOURAPPDOMAIN`
 
 ### Advanced: Group Sync with Authentik
+- As `outline` doesn't support group sync, you can make use of an [extra service, the Outline-Authentik-Connector,](https://github.com/burritosoftware/Outline-Authentik-Connector) to do so.
+- Just uncomment the respective section in your `.env`, and set the necessary envs.
+- Then [follow these instructions](https://github.com/burritosoftware/Outline-Authentik-Connector?tab=readme-ov-file#outline-setup) to create the needed user and tokens
+  - ! for the authentik-token make sure you don't use the token it shows when creating the user (that is a password), create as the user (it will expire) but in the admin interface (path: `https://login..../if/admin/#/core/tokens`). Also setting the needed global permissions was not possible on the user directly, but I had to create a role for this.
 
-As `outline` doesn't support group sync, you can make use of an [extra service, the Outline-Authentik-Connector,](https://github.com/burritosoftware/Outline-Authentik-Connector) to do so.
-
-1. Uncomment the respective section in your `.env`, and set the necessary envs.
-2. Then [follow these instructions](https://github.com/burritosoftware/Outline-Authentik-Connector?tab=readme-ov-file#outline-setup) to create the needed user and tokens
-
-    > [!NOTE]
-    > For the authentik-token make sure you don't use the token it shows when creating the user (that is a password), create as the user (it will expire) but in the admin interface (path: `https://<APP_DOMAIN>/if/admin/#/core/tokens`). Also setting the needed global permissions was not possible on the user directly, but I had to create a role for this.
-
-3. and insert them as secrets:
-
-```sh
-abra app secret insert <APP-DOMAIN> agsoutline v1 "<SECRET_VALUE>"
-abra app secret insert <APP-DOMAIN> agsauthentik v1 "<SECRET_VALUE>"
-abra app secret insert <APP-DOMAIN> agswebhook v1 "<SECRET_VALUE>"
+- and insert them as secrets:
+```
+abra app secret insert YOURAPPNAME agsoutline v1 SECRETVALUE
+abra app secret insert YOURAPPNAME agsauthentik v1 SECRETVALUE
+abra app secret insert YOURAPPNAME agswebhook v1 SECRETVALUE
 ```