# Deploy Outline with the outline-docs template
Source: https://docs.quake.ai/resources/deployments/deploy-outline-docs-template
Markdown: https://docs.quake.ai/resources/deployments/deploy-outline-docs-template.md
---
# Deploy Outline with the outline-docs template
Stand up [Outline](https://www.getoutline.com), an open-source team knowledge base, on a single Quake AI instance using the [validated OpenTofu template](/docs/platform/validation#how-infrastructure-templates-are-checked) `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.
```d2
direction: right
user: Team member {shape: person}
idp: Identity provider\n(OIDC)
fip: Floating IP
instance: Ubuntu instance {
caddy: Caddy\nreverse proxy
outline: Outline\nwiki
db: PostgreSQL
redis: Redis
caddy -> outline: proxies 443 to 3000
outline -> db: documents
outline -> redis: jobs + cache
}
user -> fip: HTTPS
fip -> instance.caddy
instance.outline -> idp: sign-in redirect
```
## 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](/docs/tools/openstack-cli).
- 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](/resources/iac-templates/outline-docs).
- 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`:
```bash
cp terraform.tfvars.example terraform.tfvars
```
```hcl
key_name = "YOUR_KEY_NAME"
```
Leave `file_storage` at its default `local` to keep uploads on the data volume. Initialize, preview, and apply:
```bash
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`:
```bash
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](/docs/network/how-to/point-domain-to-quake-ai). Wait until it resolves:
```bash
dig +short docs.example.com
```
2. SSH to the instance and create `/opt/outline/Caddyfile`:
```text
docs.example.com {
reverse_proxy 127.0.0.1:3000
}
```
3. Add Caddy to `/opt/outline/docker-compose.yml`:
```yaml
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](/docs/network/how-to/lets-encrypt-certificate).
## 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:
```text
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
```
To use Google, Slack, or Azure AD instead, set that provider's variables (for example `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`) in place of the `OIDC_*` block. Outline reads whichever provider you configure. Keep every secret in `/opt/outline/.env` on the instance, never in `terraform.tfvars` or the repo.
## Step 4: Migrate the database and start Outline
Run the one-time database migration, then bring up the full stack:
```bash
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](/resources/iac-templates/outline-docs): the template reference, parameters, and resource map
- [Self-managed PostgreSQL template](/resources/iac-templates/self-managed-postgres): the database to point at when you outgrow the bundled one
- [Deploy n8n with the n8n-workflow template](/resources/deployments/deploy-n8n-workflow-template): add workflow automation to your project tooling
- [How to store application secrets and inject them at runtime](/docs/security/how-to/inject-app-secrets): manage the OIDC and storage credentials
- [Security hardening checklist](/docs/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:
```bash
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**.