Deploy Outline with the outline-docs template

Stand up Outline, an open-source team knowledge base, on a single Quake AI instance using the validated OpenTofu template outline-docs. You apply the template, point a domain at the host and serve it over HTTPS, configure an auth provider, run the database migration, sign in through single sign-on, create your first collection and document, and invite a teammate.

Outline keeps your team's documentation on infrastructure you own. You run it yourself; this is a self-hosted tool you operate, not a managed service.

Prerequisites#

You need:

• OpenTofu 1.6.0 or later (or Terraform 1.6.0 or later) installed locally.
• Your OpenStack credentials sourced into the shell (source openrc.sh). See the OpenStack CLI guide.
• An SSH keypair that already exists in your project. Record its name for the key_name variable.
• A copy of the outline-docs template directory from the template reference page.
• A domain you can point at the instance. Outline needs a stable public URL.
• An identity provider you can configure for OIDC (any standards-compliant provider, Google, Slack, or Azure AD). Outline does not serve the wiki without one.

Step 1: Apply the template#

Copy the template's example variables file and set key_name:

cp terraform.tfvars.example terraform.tfvars

key_name = "YOUR_KEY_NAME"

Leave file_storage at its default local to keep uploads on the data volume. Initialize, preview, and apply:

tofu init
tofu plan
tofu apply

OpenTofu provisions a private network, a router, a security group, a block volume mounted at /var/lib/docker, an instance, and a floating IP. On first boot, cloud-init installs Docker Engine, generates Outline's secret keys and the database password into /opt/outline/.env, and starts PostgreSQL and Redis. Outline itself starts after you finish configuration in the next steps.

Read the outputs and record floating_ip and app_url:

tofu output

Step 2: Point a domain at the host and serve HTTPS with Caddy#

Outline builds absolute links and auth callbacks from its public URL, so it needs a domain with TLS before it serves the wiki.

1. Create a DNS A record for your domain (for example docs.example.com) pointing at YOUR_FLOATING_IP. Follow How to point a domain at a Quake AI resource. Wait until it resolves:

dig +short docs.example.com

1. SSH to the instance and create /opt/outline/Caddyfile:

docs.example.com {
  reverse_proxy 127.0.0.1:3000
}

1. Add Caddy to /opt/outline/docker-compose.yml:

services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    network_mode: host
    volumes:
      - /opt/outline/Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
volumes:
  caddy_data:

For background on certificates, see How to issue and auto-renew a TLS certificate with Let's Encrypt.

Step 3: Configure the auth provider#

Outline authenticates users through an external identity provider. Register an application in your provider, set the redirect URI to https://docs.example.com/auth/oidc.callback, and note the client ID, client secret, and the provider's authorization, token, and userinfo URLs.

Edit /opt/outline/.env on the instance. Set the public URL and fill in the OIDC block:

URL=https://docs.example.com
OIDC_CLIENT_ID=YOUR_CLIENT_ID
OIDC_CLIENT_SECRET=YOUR_CLIENT_SECRET
OIDC_AUTH_URI=https://idp.example.com/authorize
OIDC_TOKEN_URI=https://idp.example.com/oauth/token
OIDC_USERINFO_URI=https://idp.example.com/userinfo
OIDC_DISPLAY_NAME=SSO

Step 4: Migrate the database and start Outline#

Run the one-time database migration, then bring up the full stack:

cd /opt/outline
sudo docker compose run --rm outline yarn db:migrate
sudo docker compose up -d
sudo docker compose ps

The outline container joins the running PostgreSQL and Redis. Confirm it reports healthy.

Step 5: Sign in and create your first collection#

1. Open https://docs.example.com. Outline redirects you to your identity provider. Sign in; the first account to sign in becomes the workspace admin.
2. Create a collection (for example Engineering). Collections group related documents.
3. Inside the collection, select New doc, give it a title such as Runbook: deploy, and write a few lines. Outline saves as you type and supports Markdown, slash commands, and nested documents.

Step 6: Invite a teammate#

1. Go to Settings > Members > Invite people.
2. Enter a teammate's email, or share the workspace URL so they sign in through the same identity provider. Set their role (member or admin).
3. Confirm they can sign in and reach the collection you created.

What you built#

• Applied the outline-docs template to provision a network, security group, data volume, instance, and floating IP, with PostgreSQL and Redis started by cloud-init
• Served Outline over HTTPS by pointing a domain at the floating IP and routing it through a Caddy reverse proxy
• Configured an OIDC auth provider, which Outline requires before it serves the wiki
• Migrated the database and started the app
• Created a collection and a document and invited a teammate

Scope of this deployment#

This template runs a single-VM Outline host, not a managed knowledge-base cloud. The instance is CPU-only and runs in one region, and it bundles PostgreSQL and Redis as containers on the same host. You operate the instance, Docker, Outline, the database, Redis, and the data volume yourself: back them up, patch them, and snapshot the volume before you resize or rebuild. For a larger team, move PostgreSQL and Redis onto their own instances and size the app host up.

Next steps#

• Outline knowledge-base template: the template reference, parameters, and resource map
• Self-managed PostgreSQL template: the database to point at when you outgrow the bundled one
• Deploy n8n with the n8n-workflow template: add workflow automation to your project tooling
• How to store application secrets and inject them at runtime: manage the OIDC and storage credentials
• Security hardening checklist: tighten SSH access and exposure before you serve real traffic

Clean up#

When you no longer need the deployment, destroy everything the template created:

tofu destroy

Then remove the DNS A record you created in step 2 and the application you registered in your identity provider. Because Outline, its database, Redis, and local uploads all live on the instance and its attached volume, tofu destroy removes them along with the infrastructure. Export any documents you want to keep first; Outline supports a workspace export from Settings.