Deploy Outline with Docker and use GitHub as the OAuth service

Preface#

Recently, the organization I belong to, Mu Chuang She, needed to deploy a document collaboration program. After some selection (actually, we had used it before), we chose Outline as the document collaboration program. I glanced at the online deployment tutorial, which was still abstract. In fact, if we don't consider integrating Nginx, it's not particularly difficult because it doesn't require special permission management and allocation. Therefore, I directly created an OAuth App in the Mu Chuang She GitHub organization as a login verification method, saving the trouble of building an SSO service.

Preparation#

A server (recommended at least 1c2g) with Docker and Docker Compose installed
A domain name, preferably a top-level domain

Services#

Outline (the main application)
PostgreSQL (database)
Redis (cache database)
Minio (object storage service)

Deployment#

Please first install Docker and Docker Compose services. If you have installed 1Panel as the server panel, it already comes with the relevant services. The deployment is divided into three parts: the first part is to deploy Minio and set up the file object storage service, the second part is to obtain GitHub OAuth related settings, and the third part is to deploy Outline related services.

You can also use an object storage service compatible with the AWS S3 protocol as the object storage for Outline, such as CloudFlare R2, Bifeng Cloud, Tencent Cloud OSS, etc.

If you are using an online object storage service, you can skip deploying Minio and directly start deploying Outline. Refer to your object storage service documentation to fill in the relevant secret information and Endpoint.

Deploy Minio#

Create a folder to place the deployment-related files, such as /opt/Minio, use the following command to create the relevant folder and navigate to the directory, then create the relevant files.

mkdir /opt/Minio && cd /opt/Minio

Below is an example of the docker-compose.yml file

version: 3
services:
  minio:
    image: ${DOCKER_MINIO_IMAGE_NAME}
    env_file: ./.env # Specify environment variable file
    container_name: minio
    ports:
      - 9502:9000
      - 9503:9001
    restart: always
    command: server /data --console-address :9000 --address :9001
    environment:
      MINIO_ROOT_USER: ${MINIO_ROOT_USER}
      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD}
    logging:
      options:
        max-size: 5M
        max-file: 10
      driver: json-file
    volumes:
      - ./minio_data:/data
    labels:
      createdBy: Apps

You also need to create a .env file in the directory where the Docker Compose file is placed and fill in the following content. It is recommended to modify the relevant account and password information for security.

DOCKER_MINIO_IMAGE_NAME=minio/minio:RELEASE.2024-08-03T04-33-23Z.fips
DOCKER_MINIO_ROOT_USER=admin
DOCKER_MINIO_ROOT_PASSWORD=admin

Use Nginx to reverse proxy the Minio service, where port 9502 is the HTTP port for the Minio service, and port 9503 is the API port for the Minio service.

Example: localhost:9502 -> https://minio.example.com localhost:9503 -> https://api-minio.example.com

After deployment is complete, please visit https://minio.example.com and log in using the set username and password.

After logging in, set the Region to cn-1 in the settings, and add a bucket named outline in Bucket to store outline data, setting the access permission to private.

Optional Operation:

Add a user in Bucket -> outline -> Access -> User for Outline service to access the Minio service.

Configure GitHub OAuth#

Visit GitHub and log in
Go to the OAuth Apps page (you can also click: upper right corner avatar - Settings - Developer Settings - OAuth Apps)
Click New OAuth App
Fill in the Register a new OAuth application form

Application name: You can fill it in yourself, for example, outline
Homepage URL: Fill in the homepage URL of Outline
Authorization callback URL: Fill in <Homepage URL>/auth/oidc.callback, where <Homepage URL> needs to be replaced with the homepage URL of Outline

Click the Register application button to enter the application details page
Click the Generate a new client secret button
Note down the Client ID and Client secret for filling in environment variables later (note that the Client secret is only displayed once at creation and cannot be queried later; if lost, you can click the button again to create a new one)

Deploy Outline#

Like Minio, create a folder to place the deployment-related files, such as /opt/Outline, use the following command to create the relevant folder and navigate to the directory, then create the relevant files.

mkdir /opt/Outline && cd /opt/Outline

Below is an example of the docker-compose.yml file

version: 3.8
services:
  outline:
    image: ${DOCKER_OUTLINE_IMAGE_NAME}
    env_file: ./.env
    ports:
      - 9303:3000
    container_name: outline
    restart: always
    networks:
      - outline
    extra_hosts:
      - ${DOCKER_OUTLINE_HOSTNAME}:0.0.0.0
    depends_on:
      - postgres
      - redis

  redis:
    image: ${DOCKER_REDIS_IMAGE_NAME}
    env_file: ./.env
    volumes:
      - ./redis/redis.conf:/redis.conf # Configuration file persistence
    container_name: ${DOCKER_REDIS_HOST}
    restart: always
    networks:
      - outline
    command: [redis-server, /redis.conf] # Startup command

  postgres:
    image: ${DOCKER_POSTGRES_IMAGE_NAME}
    env_file: ./.env
    environment:
      POSTGRES_DB: ${DOCKER_POSTGRES_DB}
      POSTGRES_USER: ${DOCKER_POSTGRES_USER}
      POSTGRES_PASSWORD: ${DOCKER_POSTGRES_PASSWORD}
    volumes:
      - ./database-data:/var/lib/postgresql/data # Data persistence
    container_name: ${DOCKER_POSTGRES_HOST}
    restart: always
    networks:
      - outline

networks:
  outline:

Please read the following configuration line by line in detail and modify according to the actual situation, paying attention to relevant spellings!

Like Minio, create a .env file in the directory where the Docker Compose file is placed and copy the following content:

# Image settings
DOCKER_OUTLINE_IMAGE_NAME=docker.getoutline.com/outlinewiki/outline:latest
DOCKER_POSTGRES_IMAGE_NAME=postgres
DOCKER_REDIS_IMAGE_NAME=redis

# Container names
DOCKER_REDIS_HOST=outline_redis
DOCKER_POSTGRES_HOST=outline_postgres

# Postgres settings
DOCKER_POSTGRES_USER=outline
DOCKER_POSTGRES_PASSWORD=outline
DOCKER_POSTGRES_DB=outline

# GitHub OAuth settings, fill in the information noted earlier

GITHUB_CLIENT_ID=id
GITHUB_CLIENT_SECRET=secret

# Outline settings
DOCKER_OUTLINE_HOSTNAME=docs.example.com # Outline domain name (needs to use Nginx reverse proxy)

# –––––––––––––––– Outline required –––––––––––––––-

NODE_ENV=production

# Generate a 32-byte random key encoded in hexadecimal. You should use openssl rand -hex 32 in the terminal to generate a random value.
SECRET_KEY=d8e45eahe5d298d976464888dea86c92b72dfa73aj8cb8903454205c02c732b3

# Generate a unique random key. The format is not important, but you can still use openssl rand -hex 32 in your terminal to generate this.
UTILS_SECRET=cf561a25absbd24c58e6d74edd726f60de11fd5c3fb8c289c725a48ab3b7b759

# For production, point these to your database; in development, it should work out of the box.
DATABASE_URL=postgres://${DOCKER_POSTGRES_USER}:${DOCKER_POSTGRES_PASSWORD}@${DOCKER_POSTGRES_HOST}:5432/${DOCKER_POSTGRES_DB}
DATABASE_CONNECTION_POOL_MIN=
DATABASE_CONNECTION_POOL_MAX=
# Uncomment this to disable SSL connection to Postgres
PGSSLMODE=disable

# For Redis, you can specify a URL compatible with ioredis, like this
REDIS_URL=redis://${DOCKER_REDIS_HOST}:6379
# Or, if you want to provide additional connection options,
# use a base64-encoded JSON connection options object. Refer to the ioredis documentation for a list of available options.
# Example: Use Redis Sentinel for high availability
# {sentinels:[{host:sentinel-0,port:26379},{host:sentinel-1,port:26379}],name:mymaster}
# REDIS_URL=ioredis://eyJzZW50aW5lbHMiOlt7Imhvc3QiOiJzZW50aW5lbC0wIiwicG9ydCI6MjYzNzl9LHsiaG9zdCI6InNlbnRpbmVsLTEiLCJwb3J0IjoyNjM3OX1dLCJuYW1lIjoibXltYXN0ZXIifQ==

# The URL should point to a fully qualified, publicly accessible URL. If using a proxy,
# the port in the URL and PORT may differ.
URL=https://${DOCKER_OUTLINE_HOSTNAME}
PORT=3000

# View the documentation for running a standalone collaboration server [here](docs/SERVICES.md), this does not need to be set in normal operation.
# COLLABORATION_URL=

# To support uploading avatar and document attachment images, a compatible S3 storage must be provided. AWS S3 is recommended for redundancy,
# but if you want to keep all files stored locally, you can use alternatives like Minio (https://github.com/minio/minio).

# More detailed guides for setting up S3 can be found here:
# => https://wiki.generaloutline.com/share/125de1cc-9ff6-424b-8415-0d58c809a40f
# Here use the username and password used during Minio deployment, or use the user created in the optional operation in the previous section, or fill in the information for an object storage compatible with the AWS S3 protocol.
AWS_ACCESS_KEY_ID=admin
AWS_SECRET_ACCESS_KEY=admin
AWS_REGION=cn-1
# AWS_S3_ACCELERATE_URL=
AWS_S3_UPLOAD_BUCKET_URL=https://api-minio.example.com
AWS_S3_UPLOAD_BUCKET_NAME=outline
AWS_S3_FORCE_PATH_STYLE=true
AWS_S3_ACL=private

# Specify the storage system to use. Possible values are either s3 or local.
# For local, avatar images and document attachments will be stored on the local disk.
FILE_STORAGE=s3

# If local is configured for FILE_STORAGE above, this sets the parent directory for all attachments/images.
# Ensure that this process has permission to create this path and also has permission to write files to it.
FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data

# Maximum allowed size for uploaded attachments.
FILE_STORAGE_UPLOAD_MAX_SIZE=262144000

# Override the maximum size for document imports, which should usually be lower than the maximum size for document attachments.
# FILE_STORAGE_IMPORT_MAX_SIZE=

# Override the maximum size for workspace imports, which may be particularly large and files are temporary and will be automatically deleted after a while.
# FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE=

# –––––––––––––– Authentication ––––––––––––––

# Third-party login credentials, at least one of Google, Slack,
# or Microsoft must be configured for the installation to work, otherwise you will have no login options.

# To configure Slack authentication, you need to create an application at
# => https://api.slack.com/apps
#
# When configuring the Client ID, add a redirect URL to OAuth & Permissions:
# https://<URL>/auth/slack.callback
# SLACK_CLIENT_ID=Get a key from Slack
# SLACK_CLIENT_SECRET=Get the secret for the key above

# To configure Google authentication, you need to create an OAuth client ID at
# => https://console.cloud.google.com/apis/credentials
#
# When configuring the client ID, add an authorized redirect URI:
# https://<URL>/auth/google.callback
# GOOGLE_CLIENT_ID=
# GOOGLE_CLIENT_SECRET=

# To configure Microsoft/Azure authentication, you need to create an OAuth client. See the guide for how to set up your Azure application:
# => https://wiki.generaloutline.com/share/dfa77e56-d4d2-4b51-8ff8-84ea6608faa4
# AZURE_CLIENT_ID=
# AZURE_CLIENT_SECRET=
# AZURE_RESOURCE_APP_ID=

# GitHub authentication

# Fill in the Client ID and Client secret of the GitHub OAuth application
OIDC_CLIENT_ID=${GITHUB_CLIENT_ID}
OIDC_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}

# Fill in the GitHub OAuth endpoint, refer to https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow
OIDC_AUTH_URI=https://github.com/login/oauth/authorize
OIDC_TOKEN_URI=https://github.com/login/oauth/access_token

# OAuth authorization scopes
OIDC_SCOPES=read:user user:email

# Get basic user information via GitHub API
OIDC_USERINFO_URI=https://api.github.com/user
OIDC_USERNAME_CLAIM=name

# Display "Continue with GitHub" on the login screen
OIDC_DISPLAY_NAME=GitHub

# –––––––––––––––– Optional ––––––––––––––––

# Provide Base64 encoded private key and certificate for HTTPS termination. This is only needed if you are not using an external reverse proxy. See documentation:
# https://wiki.generaloutline.com/share/1c922644-40d8-41fe-98f9-df2b67239d45
# SSL_KEY=
# SSL_CERT=

# If using Cloudfront/Cloudflare distribution or similar services, you can set it below.
# This will cause the paths for javascript, stylesheets, and images to be updated to the hostname defined in CDN_URL. In the CDN configuration, the original server
# should be set to the same as the URL.
# CDN_URL=

# Automatically redirect to https in production. The default is true, but if you can ensure
# SSL is terminated at the external load balancer, it can be set to false.
FORCE_HTTPS=false

# Allow the installation to check for updates by sending anonymous statistics to
# the maintainers
ENABLE_UPDATES=false

# How many processes should be started. As a reasonable rule, divide your server's
# available memory by 512 to roughly estimate.
WEB_CONCURRENCY=1

# If your reverse proxy has already logged incoming http
# requests, and this becomes repetitive, you can remove this line
# DEBUG=http

# Configure the minimum severity level for server logs. Should be one of
# error, warn, info, http, verbose, debug, and silly.
LOG_LEVEL=info

# For complete Slack integration, including searching and posting to channels, the following configuration is also needed, more details
# => https://wiki.generaloutline.com/share/be25efd1-b3ef-4450-b8e5-c4a4fc11e02a
#
# SLACK_VERIFICATION_TOKEN=Your token
# SLACK_APP_ID=A0XXXXXXX
# SLACK_MESSAGE_ACTIONS=true

# Optionally enable Sentry (sentry.io) to track errors and performance,
# and optionally add a Sentry tunnel in the UI to bypass ad blockers:
# https://docs.sentry.io/platforms/javascript/troubleshooting/#using-the-tunnel-option)
# SENTRY_DSN=
# SENTRY_TUNNEL=

# To support sending outbound transactional emails, such as document updates or
# invitations, you need to provide SMTP server authentication
# SMTP_HOST=smtp.office365.com
# SMTP_PORT=587
# SMTP_USERNAME=
# SMTP_PASSWORD=
# SMTP_FROM_EMAIL=
# SMTP_REPLY_EMAIL=
# SMTP_TLS_CIPHERS=
# SMTP_SECURE=false

# Default interface language. See translate.getoutline.com for available
# language codes and their approximate translation percentages.
DEFAULT_LANGUAGE=zh_CN

# Optionally enable rate limiter for the application web server
RATE_LIMITER_ENABLED=true

# Configure default rate limiting parameters for the rate limiter
RATE_LIMITER_REQUESTS=1000
RATE_LIMITER_DURATION_WINDOW=60

# Iframely API configuration
# IFRAMELY_URL=
# IFRAMELY_API_KEY=

After starting the service, use Nginx to reverse proxy the Outline service, where port 9303 is the HTTP port for the Outline service.

Example: localhost:9303 -> https://docs.example.com

Visit the homepage of the deployed Outline in your browser (for example, https://docs.example.com), select Log in with GitHub, and if configured correctly, you will be redirected to the GitHub authorization page, where you can authorize login using your GitHub information.

This article was synchronized and updated to xLog by Mix Space. The original link is https://www.sotkg.com/posts/site/7