From f17ee9a9cc7ccb15f0196a7dbecf83e0b1c53bdf Mon Sep 17 00:00:00 2001 From: Laur Ivan Date: Sun, 11 Dec 2022 21:56:50 +0100 Subject: [PATCH] fix(docs): Update role documentation. --- README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 108 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 9ff0a38..5a4132b 100644 --- a/README.md +++ b/README.md @@ -10,54 +10,126 @@ None All variables are listed below (see also `defaults/main.yml`). -```yml -# defaults file for outline +### Outline Core Variables +Outline requires a couple of secrets for data encryption: + +```yml outline_secret_key: 'changeme' outline_utils_secret: 'changeme' +``` +You also need to specify the deployment type. Usually it's `production` -outline_setup_path: '~/outline' +```yml outline_deployment: '' +``` -outline_port: 3000 -outline_url: "http://localhost:{{ outline_port }}" -outline_force_https: "false" -outline_enable_updates: "false" -outline_cdn_url: +You also need to define how you access outline: -outline_debug: "cache,presenters,events,emails,mailer,utils,multiplayer,server,services" +- `outline_port` is the port mapping in Docker. Outline runs at port 3000, which is alos the default +- `outline_url` is the public URL where we see Outline. If you use reverse proxy mapping, put the URL of the reverse proxy (in my case *[this one](https://wiki.home.laurivan.com)*). +- `outline_force_https` will run with HTTPS if true. you can define it as *false* If you're behind a proxy or you don't have a certificate. It defaults to `false`. +- `outline_enable_updates` will enable updates if true. Please read [the documentation](https://app.getoutline.com/s/770a97da-13e5-401e-9f8a-37949c19f97e/) for what this implies (e.g. telemetry) +- Define `outline_cdn_url` if you have a CDN. Defaults to *empty* +**Note**: `outline_url` will define the authentication redirect url for e.g. authentik + +You can define which debug messages to be logged via `outline_debug`. + +### Storage + +Following values are defined for the docker-compose: + +```yml outline_volume_base: "/mnt/outline" +outline_setup_path: '{{ outline_volume_base }}/config' outline_volume_redis: "{{ outline_volume_base }}/redis" outline_volume_db: "{{ outline_volume_base }}/db" outline_volume_s3: "{{ outline_volume_base }}/s3" +``` +Please note that `outline_volume_db` and `outline_volume_s3` are actually created only if local posstgres and fake_s3 containers are created by configuration below. + +You can specify a logo too via `outline_team_logo_url`. By default this is empty. + +You can also change the default language via `outline_language`. The role defaults the language to *en_US*. + +### Authentication + +Outline authentication can happen via: + +- OIDC +- Google authentication +- Slack + +You need to define at least one of them. + +#### OIDC + +OIDC parameters are + +```yml oidc_client_id: oidc_client_secret: oidc_auth_uri: oidc_token_uri: oidc_userinfo_uri: +``` +Your authentication app should provide you all the above. I use something along the lines: + +```yml +oidc_client_id: "changeme" +oidc_client_secret: "changeme" +oidc_auth_uri: "https://sso.laurivan.com/application/o/authorize/" +oidc_token_uri: "https://sso.laurivan.com/application/o/token/" +oidc_userinfo_uri: "https://sso.laurivan.com/application/o/userinfo/" +oidc_username_claim: "preferred_username" +``` + +**Note**: you will probably need to provide the redirect URL to the authentication application. For Authentik, you can find it in the **Provider** for the specific application. + +#### Google ID + +You need to define: + +```yml outline_google_client_id: outline_google_client_secret: +``` + +#### Slack + +You need to define + +```yml outline_slack_client_id: outline_slack_client_secret: +``` -# If the db_host is not "postgres", then we assume the -# db is external and not spin up the docker container +### Database + +You need to assign a database to Outline. This role allows you to launch Postgres in a container via: + +```yml outline_db_schema: "postgres" outline_db_host: "postgres" outline_db_port: "5432" outline_db_user: "postgres" outline_db_password: "changeme" outline_db: "outline" +``` -# By default, PostgreSQL is not secured. If you have a secure -# database instance, replace the content below with "enable". -outline_db_ssl: "disable" +If the db_host is not "postgres", then we assume the db is external and not spin up the docker container. -# Spin up the fake S3 only if "fake_s3" is true +By default, PostgreSQL is not secured. If you have a secure database instance, set the `outline_db_ssl` variable to "enable". + +### S3 + +We define the following variables: + +```yml outline_fake_s3: true outline_fake_s3_port: 4569 outline_aws_access_key_id: @@ -68,17 +140,34 @@ outline_aws_s3_upload_bucket_name: outline-bucket outline_aws_s3_upload_max_size: "26214400" outline_aws_s3_force_path_style: "true" outline_aws_s3_acl: "private" +``` +You need S3 (or S3-like) storage for e.g. uploaded files. By default, the role spins up the fake S3 only if `fake_s3` variable is true. + +I use [MinIO](https://min.io/) with something like: + +```yml +outline_fake_s3: "" +outline_aws_access_key_id: "change me" +outline_aws_secret_access_key: "change me" +outline_aws_region: "my-rack" +outline_aws_s3_upload_bucket_url: "http://minio,example.com:9000" +outline_aws_s3_upload_max_size: "26214400" +outline_aws_s3_force_path_style: "true" +outline_aws_s3_acl: "private" +``` + +### Email + +Outline can send notification emails if you set up the SMTP variables: + +```yml outline_smtp_host: outline_smtp_port: outline_smtp_username: outline_smtp_password: outline_smtp_from_email: outline_smtp_reply_email: - -outline_team_logo_url: - -outline_language: 'en_US' ``` ## Dependencies