docs: <APP_DOMAIN> → <APP-DOMAIN>

.env.sample

@@ -76,7 +76,7 @@ ALLOWED_DOMAINS=
 #OIDC_USERINFO_URI=
 #OIDC_USERNAME_CLAIM=preferred_username
 #OIDC_DISPLAY_NAME="My Cool OpenId Connect Provider"
-#OIDC_SCOPES="openid profile email"
+#OIDC_SCOPES="openid profile email offline_access"
 #SECRET_OIDC_CLIENT_SECRET_VERSION=v1
 
 #COMPOSE_FILE="$COMPOSE_FILE:compose.google.yml"

README.md

@@ -19,15 +19,12 @@ Wiki and knowledge base for growing teams
 
 1. Set up Docker Swarm and [`abra`]
 2. Deploy [`coop-cloud/traefik`]
-3. `abra app new ${REPO_NAME}`
-   - **WARNING**: Choose "n" when `abra` asks if you'd like to generate secrets
-4. `abra app config YOURAPPNAME` - be sure to change `$DOMAIN` to something that resolves to
-   your Docker swarm box
-5. Insert secrets:
-    - `abra app secret insert YOURAPPNAME secret_key v1 $(openssl rand -hex 32)` #12
-    - `abra app secret generate -a YOURAPPNAME`
-6. `abra app deploy YOURAPPNAME`
-8. Open the configured domain in your browser to finish set-up
+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>`
+6. Open the configured domain in your browser to finish set-up
 
 [`abra`]: https://git.coopcloud.tech/coop-cloud/abra
 [`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik
@@ -36,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-DOMAIN> app create_email_user test@example.com
 ```
 
 ### Setting up your `.env` config
@@ -46,49 +43,65 @@ 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 <username-to-delete> <username-to-replace>`
+`abra app cmd <APP-DOMAIN> 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
 
-- `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 🥳
+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 🥳
 
 ## 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 <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>`
 
 ### 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://<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>"
 ```