From 3c27e320d863060b5c44b16ce7edc7bc3462680a Mon Sep 17 00:00:00 2001 From: 3wc <3wc@doesthisthing.work> Date: Sun, 30 Aug 2026 12:36:21 -0400 Subject: [PATCH 1/3] docs: Formatting and clarity in README --- README.md | 93 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 54 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 857a837..b37b412 100644 --- a/README.md +++ b/README.md @@ -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 YOURAPPNAME secret_key v1 $(openssl rand -hex 32)` - - `abra app secret generate -a YOURAPPNAME` -5. `abra app deploy YOURAPPNAME` + - `abra app secret insert secret_key v1 $(openssl rand -hex 32)` + - `abra app secret generate -a ` +5. `abra app deploy ` 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 -``` -abra app cmd YOURAPPNAME app create_email_user test@example.com +```sh +abra app cmd app create_email_user test@example.com ``` ### Setting up your `.env` config @@ -43,49 +43,64 @@ 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 YOURAPPNAME db delete_user ` +`abra app cmd db delete_user ` -Where `` is the username of the user to be removed, and -`` is the username of another user, to assign documents and +Where `` is the username of the user to be removed, and +`` is the username of another user, to assign documents and revisions to (instead of deleting them). ### Migrate from S3 to local storage -- `abra app config `, add - - `COMPOSE_FILE="$COMPOSE_FILE:compose.local.yml"` - - `FILE_STORAGE_UPLOAD_MAX_SIZE=26214400` -- `abra app deploy -f` - - compose.aws.yml should still be deployed! -- `abra app undeploy ` -- on the docker host, find mountpoint of newly created volume via `docker volume ls` and `docker volume inspect` - - volume name is smth like `_storage-data` -- take note which linux user owns `` (likely `1001`) -- use s3cmd/rclone/... to sync your bucket to `` -- `chown -R : ` -- `abra app config `, 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 -f` -- enjoy getting rid of S3 🥳 +1. `abra app config `, add + * `COMPOSE_FILE="$COMPOSE_FILE:compose.local.yml"` + * `FILE_STORAGE_UPLOAD_MAX_SIZE=26214400` + +2. `abra app deploy -f` + * `compose.aws.yml` should still be deployed! + +3. `abra app undeploy ` + +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 `_storage-data` + * take note which Linux user owns `` (likely `1001`) + * use s3cmd/rclone/... to sync your bucket to `` + +5. `chown -R : ` + +6. `abra app config `, 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 -f` + +8. Enjoy getting rid of S3 🥳 ## Single Sign On with Keycloak/Authentik -- 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` +1. Create an OIDC client in Keycloak (in Authentik this is called a provider and application) +2. Run `abra app config `, then uncomment everything in the `OIDC_` section. + + * **Valid Redirect URIs**: `https:///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 oidc_client_secret v1 ""` +4. `abra app deploy ` ### 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. -- 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 +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:///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 agsoutline v1 "" +abra app secret insert agsauthentik v1 "" +abra app secret insert agswebhook v1 "" ``` -- 2.54.0 From 5d61e6e8bdf912347149be05857fa1b6ee3411f3 Mon Sep 17 00:00:00 2001 From: 3wordchant <3wc@doesthisthing.work> Date: Sun, 30 Aug 2026 16:39:33 +0000 Subject: [PATCH 2/3] Fix NOTE formatting --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b37b412..2c821f8 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,8 @@ As `outline` doesn't support group sync, you can make use of an [extra service, 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:///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. + > [!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:///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: -- 2.54.0 From f6cf8bc1ba30b5f7e6a08e2529383142bea7ccf9 Mon Sep 17 00:00:00 2001 From: 3wc <3wc@doesthisthing.work> Date: Sun, 30 Aug 2026 12:57:01 -0400 Subject: [PATCH 3/3] =?UTF-8?q?docs:=20=20=E2=86=92=20?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 2c821f8..0d9710d 100644 --- a/README.md +++ b/README.md @@ -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 secret_key v1 $(openssl rand -hex 32)` - - `abra app secret generate -a ` -5. `abra app deploy ` + - `abra app secret insert secret_key v1 $(openssl rand -hex 32)` + - `abra app secret generate -a ` +5. `abra app deploy ` 6. Open the configured domain in your browser to finish set-up [`abra`]: https://git.coopcloud.tech/coop-cloud/abra @@ -34,7 +34,7 @@ Wiki and knowledge base for growing teams ### Create an initial admin user ```sh -abra app cmd app create_email_user test@example.com +abra app cmd app create_email_user test@example.com ``` ### Setting up your `.env` config @@ -43,7 +43,7 @@ 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 db delete_user ` +`abra app cmd db delete_user ` Where `` is the username of the user to be removed, and `` is the username of another user, to assign documents and @@ -51,42 +51,42 @@ revisions to (instead of deleting them). ### Migrate from S3 to local storage -1. `abra app config `, add +1. `abra app config `, add * `COMPOSE_FILE="$COMPOSE_FILE:compose.local.yml"` * `FILE_STORAGE_UPLOAD_MAX_SIZE=26214400` -2. `abra app deploy -f` +2. `abra app deploy -f` * `compose.aws.yml` should still be deployed! -3. `abra app undeploy ` +3. `abra app undeploy ` 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 `_storage-data` + * volume name is something like `_storage-data` * take note which Linux user owns `` (likely `1001`) * use s3cmd/rclone/... to sync your bucket to `` 5. `chown -R : ` -6. `abra app config `, switch storage back-end +6. `abra app config `, 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 -f` +7. `abra app deploy -f` 8. 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 `, then uncomment everything in the `OIDC_` section. +2. Run `abra app config `, then uncomment everything in the `OIDC_` section. - * **Valid Redirect URIs**: `https:///auth/oidc.callback` + * **Valid Redirect URIs**: `https:///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 oidc_client_secret v1 ""` -4. `abra app deploy ` +3. Set the OIDC secret using the value from the client/provider `abra app secret insert oidc_client_secret v1 ""` +4. `abra app deploy ` ### Advanced: Group Sync with Authentik @@ -101,7 +101,7 @@ As `outline` doesn't support group sync, you can make use of an [extra service, 3. and insert them as secrets: ```sh -abra app secret insert agsoutline v1 "" -abra app secret insert agsauthentik v1 "" -abra app secret insert agswebhook v1 "" +abra app secret insert agsoutline v1 "" +abra app secret insert agsauthentik v1 "" +abra app secret insert agswebhook v1 "" ``` -- 2.54.0