# Outline

Wiki and knowledge base for growing teams

<!-- metadata -->

* **Category**: Apps
* **Status**: 3, beta
* **Image**: [outlinewiki/outline](https://hub.docker.com/r/outlinewiki/outline), 4, upstream
* **Healthcheck**: No
* **Backups**: Yes
* **Email**: Yes
* **Tests**: 2
* **SSO**: 3 (OAuth)

<!-- endmetadata -->

## Basic usage

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

[`abra`]: https://git.coopcloud.tech/coop-cloud/abra
[`coop-cloud/traefik`]: https://git.coopcloud.tech/coop-cloud/traefik

## Tips & Tricks

### Create an initial admin user

```
abra app cmd YOURAPPNAME app create_email_user test@example.com
```

### Setting up your `.env` config

Avoid the use of quotes (`"..."`) as much as possible, the NodeJS scripts flip out for some reason on some vars.

### Deleting a user (e.g. to fix SSO weirdness)

`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
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 🥳

## Single Sign On with Keycloak

`abra app config YOURAPPNAME`, then uncomment everything in the `OIDC_` section.

Create a new client in Keycloak:

- **Valid Redirect URIs**: `https://YOURAPPDOMAIN/auth/oidc.callback`

`abra app deploy YOURAPPDOMAIN`