Self-Hosting Outline: A Modern Team Wiki and Knowledge Base

If your team has ever struggled to find that one document buried in a shared drive, lost context during onboarding, or watched critical knowledge walk out the door when someone leaves, you already know why a wiki matters. Outline is one of the best self-hosted options available — a fast, modern knowledge base that feels more like Notion than a traditional wiki, but runs entirely on your own infrastructure.

Photo by Jainath Ponnala on Unsplash

What Makes Outline Different

Outline stands apart from older wiki tools like MediaWiki or DokuWiki in several ways. It uses a block-based Markdown editor that supports slash commands, drag-and-drop reordering, and real-time collaborative editing. Documents are organized into collections (think folders with permissions), and the search is genuinely fast — it uses PostgreSQL full-text search with ranking.

Key features:

• Real-time collaboration — Multiple people can edit the same document simultaneously with live cursors
• Markdown-native — Write in Markdown, paste from anywhere, export cleanly
• Nested documents — Unlimited depth, drag-and-drop reordering
• Granular permissions — Collection-level and document-level access control
• API-first — Full REST API for automation and integrations
• Slash commands — Type / for blocks: tables, code, embeds, images, math (KaTeX)
• SSO support — OIDC, SAML, Google, Slack, Azure AD, GitLab

Prerequisites

You'll need:

• Docker and Docker Compose
• PostgreSQL 12+ (included in the Compose file below)
• Redis 5+ (included below)
• S3-compatible storage (MinIO works great for self-hosting)
• A reverse proxy with HTTPS (Caddy, Traefik, or Nginx Proxy Manager)
• An OIDC provider or Slack workspace for authentication

Outline requires at least 1 GB of RAM and 2 CPU cores for a small team. Larger deployments (50+ users) should allocate 2-4 GB.

Docker Compose Setup

Create a directory for your Outline deployment:

mkdir -p ~/outline && cd ~/outline

Generate the required secrets:

openssl rand -hex 32  # SECRET_KEY
openssl rand -hex 32  # UTILS_SECRET

Create your docker-compose.yml:

services:
  outline:
    image: docker.getoutline.com/outlinewiki/outline:latest
    env_file: .env
    ports:
      - "3000:3000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: outline
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: outline
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "outline"]
      interval: 10s
      timeout: 5s
      retries: 3
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3
    restart: unless-stopped

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${AWS_ACCESS_KEY_ID}
      MINIO_ROOT_PASSWORD: ${AWS_SECRET_ACCESS_KEY}
    volumes:
      - minio-data:/data
    ports:
      - "9000:9000"
      - "9001:9001"
    restart: unless-stopped

volumes:
  postgres-data:
  minio-data:

Create the .env file:

# Outline
SECRET_KEY=<your-generated-secret>
UTILS_SECRET=<your-generated-utils-secret>
DATABASE_URL=postgres://outline:${POSTGRES_PASSWORD}@postgres:5432/outline
REDIS_URL=redis://redis:6379
URL=https://wiki.example.com
PORT=3000
FORCE_HTTPS=true

# PostgreSQL
POSTGRES_PASSWORD=<strong-password>

# S3 / MinIO
AWS_ACCESS_KEY_ID=outline-minio
AWS_SECRET_ACCESS_KEY=<strong-password>
AWS_REGION=us-east-1
AWS_S3_UPLOAD_BUCKET_URL=https://s3.example.com
AWS_S3_UPLOAD_BUCKET_NAME=outline
AWS_S3_FORCE_PATH_STYLE=true
AWS_S3_ACL=private

# Authentication (OIDC example)
OIDC_CLIENT_ID=outline
OIDC_CLIENT_SECRET=<your-oidc-secret>
OIDC_AUTH_URI=https://auth.example.com/authorize
OIDC_TOKEN_URI=https://auth.example.com/token
OIDC_USERINFO_URI=https://auth.example.com/userinfo
OIDC_DISPLAY_NAME=SSO Login

Before starting Outline, create the MinIO bucket:

docker compose up -d minio
# Wait a few seconds, then create the bucket
docker run --rm --network outline_default \
  minio/mc alias set local http://minio:9000 outline-minio <password> && \
  minio/mc mb local/outline && \
  minio/mc anonymous set download local/outline

Start everything:

docker compose up -d

Outline runs database migrations automatically on first start. Check the logs:

docker compose logs -f outline

Authentication Options

Outline requires an external authentication provider — there's no built-in username/password login. This is a deliberate security decision. Your options:

OIDC (Recommended)

Works with Authentik, Keycloak, Authelia, or any OIDC-compliant provider. Set the OIDC_* variables in your .env file. This is the most flexible option and integrates well with other self-hosted services.

Slack

If your team already uses Slack, this is the easiest path. Create a Slack app, enable OAuth, and set:

SLACK_CLIENT_ID=<your-client-id>
SLACK_CLIENT_SECRET=<your-client-secret>

Google Workspace

For organizations using Google Workspace:

GOOGLE_CLIENT_ID=<your-client-id>
GOOGLE_CLIENT_SECRET=<your-client-secret>

Collections and Permissions

Outline organizes documents into collections. Each collection can have its own:

• Visibility: Public (all team members) or Private (invited members only)
• Permissions: View, Edit, or Manage per user or group
• Color and icon: For visual organization in the sidebar

A good starting structure for a team wiki:

• Engineering — Architecture decisions, runbooks, onboarding
• Product — Specs, roadmaps, release notes
• Operations — Processes, policies, vendor info
• General — Company handbook, benefits, office info

API and Integrations

Outline's API covers everything the UI can do. Generate an API key from Settings > API:

# List all documents
curl -s https://wiki.example.com/api/documents.list \
  -H "Authorization: Bearer ol_api_xxx" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data[].title'

# Search documents
curl -s https://wiki.example.com/api/documents.search \
  -H "Authorization: Bearer ol_api_xxx" \
  -H "Content-Type: application/json" \
  -d '{"query": "deployment process"}' | jq '.data[].document.title'

# Create a document
curl -s https://wiki.example.com/api/documents.create \
  -H "Authorization: Bearer ol_api_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Runbook",
    "text": "## Steps\n\n1. First step...",
    "collectionId": "<collection-uuid>",
    "publish": true
  }'

Built-in integrations include Slack notifications, webhook events, and embeds from Figma, Loom, YouTube, Google Docs, and more.

Backups

Back up both PostgreSQL and MinIO data:

#!/bin/bash
# Backup PostgreSQL
docker compose exec -T postgres pg_dump -U outline outline | \
  gzip > "outline-db-$(date +%Y%m%d).sql.gz"

# Backup MinIO data (or use mc mirror)
docker run --rm --network outline_default \
  -v ./backups:/backups \
  minio/mc alias set local http://minio:9000 outline-minio <password> && \
  minio/mc mirror local/outline /backups/outline-s3/

Outline also supports document export in Markdown or HTML format, both per-document and as a full collection export from the UI.

Comparison: Outline vs BookStack vs Wiki.js

Choose Outline if you want the most modern editing experience with real-time collaboration. Choose BookStack if you prefer a more traditional, structured wiki with chapters and pages. Choose Wiki.js if you need maximum flexibility in editor formats and authentication providers.

Tips and Gotchas

• OIDC is required — You can't skip authentication setup. If you don't have an OIDC provider, Authentik or Keycloak are the easiest to self-host alongside Outline
• S3 is required — Outline stores all file uploads in S3. MinIO is the standard self-hosted option, but any S3-compatible service works
• Websocket support — Your reverse proxy must support WebSocket connections for real-time collaboration to work. In Caddy this works automatically; in Nginx you need explicit proxy_set_header Upgrade directives
• Email notifications — Configure SMTP if you want email notifications for mentions, document updates, and invitations
• Updates — Outline releases frequently. Pin to a specific version tag in production rather than using latest

Conclusion

Outline fills a genuine gap in the self-hosted ecosystem — a knowledge base that's actually pleasant to use. The real-time collaboration, clean Markdown editor, and solid API make it a strong Notion replacement for teams that want to keep their data on their own infrastructure. The trade-off is complexity: you need PostgreSQL, Redis, S3, and an OIDC provider, which means more moving parts than simpler wikis. For teams already running these services, adding Outline is straightforward. For smaller setups, BookStack might be a more pragmatic choice.