How to Deploy Outline - Open-Source Knowledge Base Platform

Outline is an open-source knowledge base and team documentation platform designed for creating, organizing, and sharing internal documentation. It provides a clean and collaborative writing experience, real-time editing, collections for structured content, and integrations with popular authentication providers.

This article explains how to deploy Outline on a Linux server using Docker Compose with PostgreSQL as the database, Redis for caching, and Traefik for automatic HTTPS with Let's Encrypt. It covers directory setup, environment configuration, accessing the web interface, and creating team documentation within your workspace.

Prerequisites

Before you begin, you need to:

• Have access to a Linux-based server with a minimum of 2 CPU cores and 4 GB RAM as a non-root user with sudo privileges.
• Install Docker and Docker Compose.
• Create a DNS A record pointing to your server's IP address (for example, outline.example.com).
• (Optional) Have SMTP credentials for email authentication. Outline can run without SMTP, but features like user invitations, password resets, and email notifications require it.

Set Up the Directory Structure, Configuration, and Environment Variables

Outline requires a project directory with persistent storage for the database, uploads, and certificates. Environment variables control the application configuration and service connections.

1. Create the project directory.

   CONSOLE

   Copy

   $ mkdir -p ~/outline/{data,pgdata,redis,letsencrypt}

   Explain Code

   Powered by Vultr AgentBeta
   • data/: Stores Outline attachments, uploads, and other file-based data.
   • pgdata/: Persists PostgreSQL database files.
   • redis/: Stores Redis data for caching and sessions.
   • letsencrypt/: Stores Traefik ACME certificates for HTTPS renewal.

2. Navigate to the project directory.

   CONSOLE

   Copy

   $ cd ~/outline

   Explain Code

   Powered by Vultr AgentBeta

3. Generate strong random secrets for the application.

   CONSOLE

   Copy

   $ openssl rand -hex 32

   Explain Code

   Powered by Vultr AgentBeta

   Run the command twice and save both outputs. Use one value for SECRET_KEY and the other for UTILS_SECRET in the next steps.

4. Create the environment file.

   CONSOLE

   Copy

   $ nano .env

   Explain Code

   Powered by Vultr AgentBeta

5. Add the following configuration. Replace outline.example.com with your domain name, admin@example.com with your email address, STRONG_DATABASE_PASSWORD with a secure password, and the secret placeholders with the generated values.

   INI

   Copy

   NODE_ENV=production
   DOMAIN=outline.example.com
   LETSENCRYPT_EMAIL=admin@example.com
   
   URL=https://outline.example.com
   PORT=3000
   SECRET_KEY=FIRST_GENERATED_SECRET
   UTILS_SECRET=SECOND_GENERATED_SECRET
   
   POSTGRES_DB=outline
   POSTGRES_USER=outline
   POSTGRES_PASSWORD=STRONG_DATABASE_PASSWORD
   DATABASE_URL=postgres://outline:${POSTGRES_PASSWORD}@postgres:5432/outline
   PGSSLMODE=disable
   
   REDIS_URL=redis://redis:6379
   
   FILE_STORAGE=local
   FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
   
   LOG_LEVEL=info
   
   # Optional: SMTP Configuration for outgoing emails
   # SMTP_HOST=smtp.example.com
   # SMTP_PORT=587
   # SMTP_USERNAME=SMTP_USERNAME
   # SMTP_PASSWORD=SMTP_PASSWORD
   # SMTP_FROM_ADDRESS=noreply@outline.example.com
   # SMTP_SECURE=false

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

Deploy with Docker Compose

Docker Compose orchestrates Outline with PostgreSQL as the backend database, Redis for caching, and Traefik as the reverse proxy for automatic HTTPS. This configuration is based on the official Outline Docker Compose example, adapted to use environment variables and persistent storage.

1. Create the Docker Compose file.

   CONSOLE

   Copy

   $ nano docker-compose.yml

   Explain Code

   Powered by Vultr AgentBeta

2. Add the following configuration.

   YAML

   Copy

   services:
     traefik:
       image: traefik:v3.6.15
       container_name: traefik
       restart: unless-stopped
       command:
         - "--providers.docker=true"
         - "--providers.docker.exposedbydefault=false"
         - "--entrypoints.web.address=:80"
         - "--entrypoints.websecure.address=:443"
         - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
         - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge=true"
         - "--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web"
         - "--certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}"
         - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
       ports:
         - "80:80"
         - "443:443"
       volumes:
         - "./letsencrypt:/letsencrypt"
         - "/var/run/docker.sock:/var/run/docker.sock:ro"
   
     postgres:
       image: postgres:16-alpine
       container_name: outline-postgres
       restart: unless-stopped
       environment:
         POSTGRES_DB: ${POSTGRES_DB}
         POSTGRES_USER: ${POSTGRES_USER}
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
       volumes:
         - "./pgdata:/var/lib/postgresql/data"
       healthcheck:
         test: ["CMD", "pg_isready", "-d", "${POSTGRES_DB}", "-U", "${POSTGRES_USER}"]
         interval: 10s
         timeout: 5s
         retries: 5
   
     redis:
       image: redis:7-alpine
       container_name: outline-redis
       restart: unless-stopped
       command: ["redis-server", "--appendonly", "yes"]
       volumes:
         - "./redis:/data"
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 10s
         timeout: 5s
         retries: 3
   
     outline:
       image: docker.getoutline.com/outlinewiki/outline:1.7.0
       container_name: outline
       restart: unless-stopped
       env_file:
         - .env
       depends_on:
         postgres:
           condition: service_healthy
         redis:
           condition: service_healthy
       expose:
         - "3000"
       labels:
         - "traefik.enable=true"
         - "traefik.http.routers.outline.rule=Host(`${DOMAIN}`)"
         - "traefik.http.routers.outline.entrypoints=websecure"
         - "traefik.http.routers.outline.tls.certresolver=letsencrypt"
         - "traefik.http.services.outline.loadbalancer.server.port=3000"
       volumes:
         - "./data:/var/lib/outline/data"
   

   Explain Code

   Powered by Vultr AgentBeta

   Save and close the file.

   In the above manifest:

   • traefik: Serves as the reverse proxy and TLS termination point. It listens on ports 80 and 443, automatically redirects HTTP to HTTPS, and provisions Let's Encrypt certificates using the email address defined in LETSENCRYPT_EMAIL.
   • postgres: Runs PostgreSQL 16 as the primary database. It uses credentials from the .env file and includes a health check to ensure readiness before Outline starts.
   • redis: Runs Redis 7 (Alpine) for caching, sessions, and real-time features. Data persists in the ./redis directory.
   • outline: Runs the official Outline application, loads configuration from the .env file, connects to PostgreSQL and Redis, and registers with Traefik for secure domain access.

3. Start all services in detached mode.

   CONSOLE

   Copy

   $ docker compose up -d

   Explain Code

   Powered by Vultr AgentBeta

4. Verify that all containers are running.

   CONSOLE

   Copy

   $ docker compose ps -a

   Explain Code

   Powered by Vultr AgentBeta

   The output displays four running containers: Outline, PostgreSQL, Redis, and Traefik. Outline, PostgreSQL, and Redis show a healthy state; Traefik shows as running since it has no configured health check.

5. View the logs for the services.

   CONSOLE

   Copy

   $ docker compose logs

   Explain Code

   Powered by Vultr AgentBeta

   For more information on managing a Docker Compose stack, see the How To Use Docker Compose article.

Access and Configure the Outline Web Interface

After deployment, access Outline through your domain and complete the initial workspace setup.

1. Replace outline.example.com with your configured domain and open https://outline.example.com in a web browser.

2. On the Create Workspace screen, enter your Workspace name, Admin name, and Admin email to create the super admin account.

3. Click Continue.

Application Use Case

Collections organize documents into categories, and documents support real-time collaborative editing. This section demonstrates creating a collection, publishing a document, and inviting team members.

Create a Collection

A collection groups related documents under a shared access policy.

1. In the left sidebar, click New Collection and enter a name (for example, March Articles).

2. Choose the default access level: Can edit (members can view and edit), View only (members can only read), or No access (only explicitly invited users can access).

3. Click Advanced options to configure template permissions, public sharing, and commenting settings.

4. Click Create.

Create a Document

Documents live inside a collection and support real-time collaborative editing.

1. From the upper right, click + New doc.

2. Enter a document title (for example, How to Deploy Outline).

3. Use the rich text editor to write content. Type / to insert headings, lists, tables, or code blocks.

Invite Team Members

Invitations grant workspace access with a role that controls what each member can do.

1. From the bottom-left of the sidebar, click + Invite people.

2. Select a role for each invite: Admin (manage workspace settings), Editor (create and edit documents), or Viewer (view and comment).

3. Enter the email address and name for each person. Click + Add another to invite multiple people.

4. Click Send Invites.

Conclusion

You have deployed Outline on a Linux server using Docker Compose with PostgreSQL for data storage, Redis for caching, and Traefik for automatic HTTPS. Your self-hosted instance provides a collaborative knowledge base with real-time editing, document collections, and team sharing while keeping data on your own infrastructure. For more information and advanced configuration, refer to the official Outline documentation.