Self-Host Outline with Gitea SSO: Step-by-Step Guide

I've been a long-time user of the Atlassian stack (Jira, Confluence, and others) through work, and I eventually adopted them for my own use as well since they offer a free tier, I was already familiar with them, and they generally work well. The issue I ran into is that if your spaces, projects, or boards sit inactive for too long, Atlassian may deactivate them, and if you don't recover them in time, they can even be deleted.

As someone who is a big proponent of open source software and self-hosting, I began looking for alternatives and came across Outline. After trying a few options, I found Outline to be the most feature-rich when it comes to the interface, integrations, and API access. Initially, I assumed it included a built-in authentication system, as most platforms do even when they support third-party providers. However, Outline requires you to provide your own identity provider. It is nice, though, that they offer built-in support and documentation for providers like Google, Microsoft, Slack, GitHub, GitLab, Azure, and Discord, in addition to a generic OIDC option, which makes it pretty extensible to other authentication platforms.

This actually worked out well for me. Most of my documentation is about infrastructure, services, networking, code, and processes. Hosting Outline internally and using Gitea for authentication fits perfectly. The two tools complement each other, and everything stays private and under my control. If you want to make it available externally, you can do so in whatever way works best, such as OpenVPN, WireGuard, Cloudflare Tunnels, or another solution.

What is Outline

Outline is an open source knowledge base and wiki platform designed to help teams and individuals organize and share information. It focuses on simplicity and speed, while still offering features like rich text editing, structured documents, integrations, and an API for automation.

Installing Docker

One of the things I really like about Docker "wrapped" applications and services is that it makes them really easy to update, with no need to fuss with the environment or dependencies.

Typically, you can just pull the latest image and restart the stack, or update the version tag in your docker-compose.yml and redeploy.

Here is the link to the Official Docker documentation for installing Docker Engine on your platform. Personally, I used Ubuntu Server for my setup.

Once you have Docker installed and running on your platform, you're ready to move on to setting up your environment with Outline and its supporting services.

Setting up our Environment

In this section, I'll share my docker-compose.yml and docker.env files to get Outline up and running. This setup reflects my own environment and choices, so feel free to adapt it as needed for your own use.

The service stack includes:

• Outline - Node.js-based application
• Postgres - Object-relational database
• Redis - In-memory database for caching and collaboration

docker-compose.yml:

services:
  outline:
    image: docker.getoutline.com/outlinewiki/outline:latest
    env_file: ./docker.env
    ports:
      - "3000:3000"
    volumes:
      - ./storage-data:/var/lib/outline/data
    depends_on:
      - postgres
      - redis

  redis:
    image: redis
    env_file: ./docker.env
    expose:
      - "6379"
    volumes:
      - ./redis.conf:/redis.conf
    command: ["redis-server", "/redis.conf"]
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 30s
      retries: 3

  postgres:
    image: postgres
    env_file: ./docker.env
    expose:
      - "5432"
    volumes:
      - ./database-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-d", "outline", "-U", "user"]
      interval: 30s
      timeout: 20s
      retries: 3
    environment:
      POSTGRES_USER: 'user'
      POSTGRES_PASSWORD: 'pass'
      POSTGRES_DB: 'outline'
      PGSSLMODE: 'disable'

On lines 40-41 in the docker-compose.yml, set the POSTGRES_USER and POSTGRES_PASSWORD you want to use for the Postgres database. No other changes are needed here.

docker.env:

To get the docker.env file, you can download or copy it from the official Outline GitHub env.sample. Save the file as docker.env and make sure it is in the same directory as your docker-compose.yml.

There are a few key values you will need to configure in your copy of the file:

URL=https://docs.example.com
CDN_URL=https://docs.example.com

SECRET_KEY=secret
UTILS_SECRET=secret

DATABASE_URL=postgres://user:pass@postgres:5432/outline

PGSSLMODE=disable

You can generate a secret for lines 4-5 with:

openssl rand -hex 32

On line 7, update user:pass to match the same values you used in docker-compose.yml (lines 40-41). Make sure PGSSLMODE is not commented out and set to disable. This is safe since both the Outline service and Postgres database will run on the same machine within the same stack.

Configuring Gitea as the IDP (Identity Provider)

In this section, we'll set up Gitea as the identity provider for Outline, enabling single sign-on via OAuth. This keeps your documentation environment private while letting you control authentication through Gitea.

1. Create an OAuth Application in Gitea

1. Log in to your Gitea instance with an account that has admin or appropriate permissions.
2. Navigate to Settings → Applications → Manage OAuth2 Applications.
3. Click Create a new OAuth2 Application.
4. Fill out the form:
   • Application Name - Choose a name that identifies Outline as the client.
   • Redirect URI - Set this to https://<YOUR_DOMAIN>/auth/oidc/callback.
   • Description - Optional, but useful for identifying the integration later.
5. Save the application. Take note of the Client ID and Client Secret—you'll need these for Outline.

For detailed instructions, see Gitea's official documentation on OAuth2: Gitea OAuth2 Documentation.

2. Configure Outline to Use Gitea

Once you have the Client ID and Client Secret, open your docker.env file and update the following entries under the OIDC section:

OIDC_CLIENT_ID=<your_client_id>
OIDC_CLIENT_SECRET=<your_client_secret>
OIDC_AUTH_URI=https://<YOUR_GITEA_DOMAIN>/login/oauth/authorize
OIDC_TOKEN_URI=https://<YOUR_GITEA_DOMAIN>/login/oauth/access_token
OIDC_USERINFO_URI=https://<YOUR_GITEA_DOMAIN>/api/v1/user
OIDC_USERNAME_CLAIM=preferred_username
OIDC_DISPLAY_NAME=Gitea Login
OIDC_SCOPES=openid profile email

Make sure to replace <YOUR_GITEA_DOMAIN> with your actual domain and paste in the client credentials you obtained from Gitea.

3. Start the Outline Service

After saving your changes to docker.env, restart the Outline container stack to apply the configuration:

docker-compose up -d

Once Outline starts, the login page should show a "Gitea Login" option. You can test the integration by signing in with a Gitea account.