# Connect Outline

Approve the Outline instances that workspaces may mirror, register the Outline OAuth application, and turn on Outline in the Helm chart.

Turn on Outline so that workspace admins can mirror Outline collections into a workspace.
Practice reviews and conversations then use the mirrored documents as context.
You approve each Outline instance by its origin. A workspace admin cannot approve one by entering its address.
After this setup, a workspace admin connects Outline in the web app, as [Connect Slack and Outline to a workspace](/user/integrations#connect-outline) describes.

## Before you start [#before-you-start]

- An installed instance that serves its host over HTTPS ([Install on Kubernetes](./kubernetes)).
- The HTTPS origin of each Outline instance, such as `https://wiki.example.com`, on a public address.
- For each origin, the entry in the [processor checklist](./dsms/processor-checklist.mdx): legal role, hosting region, transfer basis, retention terms and processing agreement.
- Optional: the admin role in Outline, to register the OAuth application that links member accounts.
- `kubectl` with access to the release namespace, and `jq`.

The commands use the release namespace `hephaestus` and the release Secret `hephaestus-app`.
Replace these names if your release uses other names.

## Register the Outline OAuth application [#register-the-outline-oauth-application]

Members use this application to link their Outline account, so that Hephaestus knows who wrote a document.
Without it, workspaces mirror collections, but Hephaestus cannot match a document to the member who wrote it.

1. In Outline, open **Settings → Applications**, and add an application.
2. Set **Redirect URI** to `https://<host>/api/login/oauth2/code/outline`, without a final slash.
   Outline compares the address exactly.
3. Set the scope to `read`.
4. Save the application.
5. Copy its client ID and client secret.

## Set the Helm values and Secret keys [#set-the-helm-values-and-secret-keys]

1. Optional: type the client secret of the OAuth application. The shell does not show it:

   ```bash
   read -rs OUTLINE_OAUTH_CLIENT_SECRET && export OUTLINE_OAUTH_CLIENT_SECRET
   ```

2. Optional: add the client secret to the release Secret:

   ```bash
   jq -n --arg secret "$OUTLINE_OAUTH_CLIENT_SECRET" '{stringData: {OUTLINE_OAUTH_CLIENT_SECRET: $secret}}' |
     kubectl -n hephaestus patch secret hephaestus-app --type merge --patch-file /dev/stdin
   ```

3. Add Outline to `site.yaml`:

   ```yaml title="values.yaml"
   config:
     outline:
       enabled: true
       allowedOrigins:
         - https://wiki.example.com
       oauthBaseUrl: https://wiki.example.com
       oauthClientId: 0123456789abcdef
       oauthDisplayName: Example wiki
   ```

   | Value | What it sets | Default |
   | --- | --- | --- |
   | `config.outline.enabled` | The Outline connection, its sync, and its webhook receiver | `false` |
   | `config.outline.allowedOrigins` | The HTTPS origins that a workspace can connect to | Empty |
   | `config.outline.oauthBaseUrl` | The Outline instance of the OAuth application. Required with `oauthClientId`. | Empty |
   | `config.outline.oauthClientId` | The client ID of the OAuth application. Empty creates no account linking. | Empty |
   | `config.outline.oauthDisplayName` | The name on the account-linking button | `Outline` |

   An origin has no path, query, fragment or user name.
   An origin on a private or site-local address is refused.
   The server does not start with an entry that is not valid.
   While `config.outline.enabled` is `false`, the Outline page of each workspace says that Outline is not enabled on this instance.

4. Apply `site.yaml`.
   On a cluster, run the `helm upgrade` command of [Install](./kubernetes#install) again.
   On one host, run the installer again ([Run the installer](./k3s#2-run-the-installer)).

At its next start, the server creates the Outline login provider if it does not exist.
If `oauthBaseUrl` is empty or not valid, the server logs the reason at `ERROR` and creates no provider.
After that, the server ignores the client ID and secret of the chart.
An instance admin can add or change the provider under **Instance administration → Login providers**.

## Check that it worked [#check-that-it-worked]

1. In a workspace, open **Administration → Integrations**.
   The sidebar lists **Outline**.
2. Open **Outline**.
3. Enter an approved origin as **Server URL**, and an Outline API key as **API token**.
4. Select **Connect Outline**.
5. Add a collection.
   Its documents show after the first sync.

When a workspace connects, Hephaestus registers a webhook subscription in Outline.
Its address is `https://<host>/webhooks/outline/…`, so Outline must reach your host.
`WEBHOOK_ROUTING_SECRET` signs each subscription, and you set nothing for it.

## Undo [#undo]

1. In each workspace with an Outline connection, select **Disconnect Outline** if its mirror must be erased.
   A connection cannot disconnect while Outline is off for the instance.
2. Set `config.outline.enabled` to `false` in `site.yaml`.
3. Apply `site.yaml`.

With Outline off, the receiver answers `404` to each Outline delivery.
Outline turns off a subscription after 25 failed deliveries.

To withdraw one Outline instance only, remove its origin from `config.outline.allowedOrigins` and apply `site.yaml`.
Its connections then stop their sync, webhooks, account linking and review context.
Their mirror stays until a workspace admin disconnects them.