Outline

Overview

Outline is a modern team knowledge base and wiki platform deployed as part of the Mondo Open Platform Service (MOPS). This document covers the deployment and configuration of Outline using Docker Compose with Traefik as a reverse proxy.

Service Details

Component	Value
URL	https://wiki.trymondo.com
Image	outlinewiki/outline:0.82.0
Database	PostgreSQL 17.4
Cache	Redis 7.4.2
Networks	traefik-net, outline-net

Architecture

Outline is deployed as a multi-container application with the following components:

                      ┌─────────────┐
                      │   Traefik   │
                      └──────┬──────┘
                             │ HTTPS
                             ▼
┌─────────────┐      ┌──────────────┐
│    Redis    │◄────▶│    Outline   │
└─────────────┘      └──────┬───────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  PostgreSQL  │
                     └──────────────┘

Outline: Main application container serving the wiki interface and API
PostgreSQL: Database for storing wiki content, users, and metadata
Redis: In-memory cache for improved performance

Prerequisites

Docker Engine (24.0+)
Docker Compose v2
Traefik reverse proxy configured and running
External networks: traefik-net and outline-net
DNS configured for wiki.trymondo.com
Auth0 or other compatible OIDC provider
SMTP credentials for email notifications

Deployment Configuration

Environment Variables

Create a .env file with the following variables:

# Security
OUTLINE_SECRET_KEY=random_32_character_string
OUTLINE_UTILS_SECRET=another_random_32_character_string

# Authentication
OIDC_CLIENT_ID=your_oidc_client_id
OIDC_CLIENT_SECRET=your_oidc_client_secret
AUTH0_DOMAIN=your_auth0_domain

# Email
SMTP_HOST=smtp.mailersend.net
SMTP_USER=your_smtp_username
SMTP_PASS=your_smtp_password
SMTP_FROM_EMAIL=info@trymondo.com

Generate secure, random strings for OUTLINE_SECRET_KEY and OUTLINE_UTILS_SECRET. These are used to encrypt sensitive data and sign sessions.

You can generate secure random strings with: bash openssl rand -hex 16

Docker Compose File

    openssl rand -hex 16
    ```

### Docker Compose File

```yaml
services:
  outline:
    image: outlinewiki/outline:0.82.0
    container_name: outline
    depends_on:
      - postgres
      - redis
    environment:
      - NODE_ENV=production
      - URL=https://wiki.trymondo.com
      - SECRET_KEY=${OUTLINE_SECRET_KEY}
      - UTILS_SECRET=${OUTLINE_UTILS_SECRET}
      - DATABASE_URL=postgres://outline:outline@postgres:5432/outline
      - REDIS_URL=redis://redis:6379
      - FILE_STORAGE=local
      - FILE_STORAGE_LOCAL_ROOT_DIR=/opt/outline/storage
      - FILE_STORAGE_UPLOAD_MAX_SIZE=26214400
      - SMTP_HOST=${SMTP_HOST}
      - SMTP_PORT=587
      - SMTP_USERNAME=${SMTP_USER}
      - SMTP_PASSWORD=${SMTP_PASS}
      - SMTP_FROM_EMAIL=${SMTP_FROM_EMAIL}
      - PGSSLMODE=disable
      - DATABASE_CONNECTION_POOL_MIN=2
      - DATABASE_CONNECTION_POOL_MAX=10
      - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
      - OIDC_AUTH_URI=https://${AUTH0_DOMAIN}/authorize
      - OIDC_TOKEN_URI=https://${AUTH0_DOMAIN}/oauth/token
      - OIDC_USERINFO_URI=https://${AUTH0_DOMAIN}/userinfo
      - OIDC_DISPLAY_NAME=Auth0
    labels:
      - 'traefik.enable=true'
      - 'traefik.http.routers.outline.rule=Host(`wiki.trymondo.com`)'
      - 'traefik.http.routers.outline.entrypoints=websecure'
      - 'traefik.http.routers.outline.tls=true'
      - 'traefik.http.routers.outline.tls.certresolver=production'
      - 'traefik.http.services.outline.loadbalancer.server.port=3000'
      - 'traefik.http.routers.outline.middlewares=secureHeaders@file'
    networks:
      - traefik-net
      - outline-net
    restart: unless-stopped
    user: '1001:1001'
    volumes:
      - ./data/uploads:/opt/outline/storage/uploads
      - ./data/logs:/opt/outline/logs

  postgres:
    image: postgres:17.4
    container_name: outline_postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=outline
      - POSTGRES_PASSWORD=outline
      - POSTGRES_DB=outline
    volumes:
      - ./data/db:/var/lib/postgresql/data
    networks:
      - outline-net

  redis:
    image: redis:7.4.2
    container_name: outline_redis
    restart: unless-stopped
    networks:
      - outline-net

networks:
  traefik-net:
    external: true
  outline-net:

Network Configuration

Before deployment, ensure the required networks exist:

# Create external networks if they don't exist
docker network create outline-net
docker network create traefik-net

Deployment Instructions

Create the deployment directory structure:

mkdir -p /opt/apps/outline/data/{uploads,logs,db}

Create the configuration files:

nano /opt/apps/outline/.env
nano /opt/apps/outline/docker-compose.yml

Deploy the service:

cd /opt/apps/outline
docker compose up -d

Verify the services are running:
```
docker compose ps
```
Access Outline at https://wiki.trymondo.com and sign in using your Auth0 credentials.

Auth0 Configuration

Before deploying Outline, you need to configure Auth0:

Create a new application in Auth0
Set the application type to “Regular Web Application”
Configure the following URLs:
- Allowed Callback URLs: https://wiki.trymondo.com/auth/oidc.callback
- Allowed Logout URLs: https://wiki.trymondo.com
Note the Client ID and Client Secret for the .env file

Traefik Integration

Outline is configured with the following Traefik settings:

Host Rule: wiki.trymondo.com
Entrypoint: websecure (HTTPS)
TLS: Enabled with production certificate resolver
Backend Port: 3000
Middleware: secureHeaders for enhanced security

Configuration Highlights

File Storage

Outline is configured to use local file storage with the following settings:

Storage Directory: /opt/outline/storage
Maximum Upload Size: 25MB (26,214,400 bytes)
Storage Path: Mounted to ./data/uploads on the host

Database Connection Pool

PostgreSQL connection pooling is configured for optimal performance:

Minimum Connections: 2
Maximum Connections: 10

Maintenance

Backup Strategy

Back up Outline regularly using the following steps:

# Stop the containers
cd /opt/apps/outline
docker compose stop

# Backup the database
docker compose exec postgres pg_dump -U outline -d outline > outline_backup_$(date +%Y%m%d).sql

# Backup uploaded files
tar -czf outline_uploads_$(date +%Y%m%d).tar.gz -C /opt/apps/outline/data uploads

# Restart the containers
docker compose start

!!! note Consider scheduling regular backups using cron and storing them offsite.

Updates

To update Outline:

Update the image tag in docker-compose.yml

Apply the update:

cd /opt/apps/outline
docker compose pull
docker compose up -d

Check logs for any issues:
```
docker compose logs
```

Always back up your data before updating Outline to a new version.

Troubleshooting

Auth0 Connection Issues

If you can’t sign in with Auth0:

Verify Auth0 configuration:
- Check the callback URL in Auth0
- Verify Client ID and Secret in .env

Check Outline logs for auth errors:

docker compose logs outline | grep -i "auth"

Database Connection Problems

If Outline can’t connect to the database:

Verify PostgreSQL container is running:
```
docker compose ps postgres
```
Check database logs:
```
docker compose logs postgres
```

Test database connection:

docker compose exec postgres psql -U outline -c "SELECT 1;"

File Upload Issues

If file uploads aren’t working:

Check permissions on the upload directory:
```
ls -la /opt/apps/outline/data/uploads
```
Verify the user ID matches what’s in the docker-compose.yml file:
```
id -u outline
```

Check for storage-related errors in logs:

docker compose logs outline | grep -i "storage"

User Management

Adding Users

Outline uses Auth0 for authentication, so users are managed through Auth0:

Users must be able to sign in through Auth0
On first login, users will be created in Outline
Admin users can promote others to admin through the Outline UI

Setting Up Teams

To organize users into teams:

Sign in as an admin
Go to Settings > Teams
Create new teams and invite members by email

Document Structure

Outline uses a hierarchical document structure:

Collections: Top-level containers for related documents
Documents: Individual wiki pages within collections
Sections: Hierarchical organization within documents

Integration Examples

Slack Integration

To integrate Outline with Slack:

Go to Settings > Integrations
Click on Slack and follow the configuration steps
Users will be able to share and search Outline documents directly from Slack

API Usage

Outline provides a REST API for integration with other systems:

Generate an API token in Settings > API Tokens

Use the token to authenticate API requests:

curl -H "Authorization: Bearer YOUR_API_TOKEN" https://wiki.trymondo.com/api/documents

Additional Resources

Best Practices

Enable regular backups of database and uploads
Monitor disk space usage on the uploads directory
Update Outline regularly for security patches
Use document templates for consistent content
Organize collections by team or project area

Introduction

Infrastructure

Applications

Overview

Service Details

Architecture

Prerequisites

Deployment Configuration

Environment Variables

Docker Compose File

Network Configuration

Deployment Instructions

Auth0 Configuration

Traefik Integration

Configuration Highlights

File Storage

Database Connection Pool

Maintenance

Backup Strategy

Updates

Troubleshooting

Auth0 Connection Issues

Database Connection Problems

File Upload Issues

User Management

Adding Users

Setting Up Teams

Document Structure

Integration Examples

Slack Integration

API Usage

Additional Resources

Best Practices

Introduction

Infrastructure

Applications

​Overview

​Service Details

​Architecture

​Prerequisites

​Deployment Configuration

​Environment Variables

​Docker Compose File

​Network Configuration

​Deployment Instructions

​Auth0 Configuration

​Traefik Integration

​Configuration Highlights

​File Storage

​Database Connection Pool

​Maintenance

​Backup Strategy

​Updates

​Troubleshooting

​Auth0 Connection Issues

​Database Connection Problems

​File Upload Issues

​User Management

​Adding Users

​Setting Up Teams

​Document Structure

​Integration Examples

​Slack Integration

​API Usage

​Additional Resources

​Best Practices

Overview

Service Details

Architecture

Prerequisites

Deployment Configuration

Environment Variables

Docker Compose File

Network Configuration

Deployment Instructions

Auth0 Configuration

Traefik Integration

Configuration Highlights

File Storage

Database Connection Pool

Maintenance

Backup Strategy

Updates

Troubleshooting

Auth0 Connection Issues

Database Connection Problems

File Upload Issues

User Management

Adding Users

Setting Up Teams

Document Structure

Integration Examples

Slack Integration

API Usage

Additional Resources

Best Practices