mash-playbook/docs/services/outline.md

Outline

Outline is an open-source knowledge base for growing teams.

Dependencies

This service requires the following other services:

• Postgres
• KeyDB
• a Traefik reverse-proxy server

Configuration

To enable this service, besides enabling the required Dependencies, add the following configuration to your vars.yml file and re-run the installation process:

########################################################################
#                                                                      #
# outline                                                              #
#                                                                      #
########################################################################

outline_enabled: true

outline_hostname: outline.example.com

# This must be generated with: `openssl rand -hex 32`
outline_environment_variable_secret_key: ''

# The configuration below connects Outline to the KeyDB instance, for session storage purposes.
# You may wish to run a separate KeyDB instance for Outline, because KeyDB is not multi-tenant.
# Read more in docs/services/keydb.md.
outline_redis_hostname: "{{ keydb_identifier if keydb_enabled else '' }}"

outline_container_additional_networks_custom: |
  {{
    [keydb_container_network]
  }}  

# By default, files are stored locally.
# To use another file storage provider, see the "File Storage" section below.

# At least one authentication method MUST be enabled for Outline to work.
# See the "Authentication" section below.

########################################################################
#                                                                      #
# /outline                                                             #
#                                                                      #
########################################################################

URL

In the example configuration above, we configure the service to be hosted at https://outline.example.com.

While the Outline Ansible role provides an outline_path_prefix variable, Outline does not support being hosted at a subpath right now.

File Storage

Outline supports multiple file storage mechanisms.

The default configuration stores files locally in a data directory, but you can also stores files on AWS S3 (or compatible S3 altenative).

To enable S3 storage, add the following to your vars.yml configuration:

outline_environment_variable_file_storage: s3

outline_environment_variable_aws_access_key_id: ''
outline_environment_variable_aws_secret_access_key: ''
outline_environment_variable_aws_region: eu-central-1 # example
outline_environment_variable_aws_s3_upload_bucket_url: https://OUTLINE_ASSETS_BUCKET_NAME.s3.eu-central-1.amazonaws.com
outline_environment_variable_aws_s3_upload_bucket_name: OUTLINE_ASSETS_BUCKET_NAME
outline_environment_variable_aws_s3_force_path_style: false

Authentication

For Outline to work, at least one authentication method must be enabled.

The Outline Ansible role provides dedicated Ansible variables for configuring these authentication methods via environment variables (see the outline_environment_variable_* variables in defaults/main.yml of ansible-role-outline).

If you need to pass additional environment variables to Outline, for which dedicated Ansible variables are not available, you can use outline_environment_variables_additional_variables.

If you define SMTP settings (see the outline_environment_variable_smtp_* variables in defaults/main.yml), the Email magic link authentication method will be enabled:

Unfortunately, even with SMTP settings being defined, we haven't been able to get Outline to succesfully send emails just yet, hitting issues similar to this one.