Outline

Last reviewed Aug 26, 2026 · 987 words

Outline has no username-and-password login. Not disabled by default, not hidden behind a flag: it does not exist. Before you can create the first account on your own instance you need either an OIDC provider or a working SMTP server for magic-link sign-in, and most first attempts stall for an hour at exactly this step. Decide which one you are using before you pull the image, and the rest of the install is a pleasant afternoon: Postgres, Redis, one container, about 1 GB of RAM, and the nicest editor in the self-hosted wiki space.

Pick the login before the compose file

You have two realistic routes. If you already run Authentik, Authelia, or Keycloak, point Outline at it with the generic OIDC variables and every user gets single sign-on on day one. The SSO walkthrough covers the provider side. If you do not run an identity provider and do not want one for a 3-person wiki, configure SMTP instead: Outline emails a sign-in link, the user clicks it, done. Google, Slack, Azure, GitHub, and Discord logins are also built in, but they tie your wiki to an outside account system, which is the thing many people were self-hosting to avoid.

The SMTP route is the one I recommend for households and small teams. It needs five variables and any mail relay that can send outbound, including a free-tier transactional provider.

The stack, minus the parts that don't matter

Outline wants Postgres and Redis and will not run without them. Everything else in the official example is optional. This is the shape I run:

services:
  outline:
    image: outlinewiki/outline:latest
    ports:
      - "3000:3000"
    environment:
      - URL=https://wiki.example.com
      - SECRET_KEY=replace-with-openssl-rand-hex-32
      - UTILS_SECRET=replace-with-a-second-hex-32
      - DATABASE_URL=postgres://outline:outline@postgres:5432/outline
      - PGSSLMODE=disable
      - REDIS_URL=redis://redis:6379
      - FILE_STORAGE=local
      - FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
      - FILE_STORAGE_UPLOAD_MAX_SIZE=262144000
      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USERNAME=outline
      - SMTP_PASSWORD=change-me
      - [email protected]
    volumes:
      - ./outline-data:/var/lib/outline/data
    depends_on: [postgres, redis]
    restart: unless-stopped
  postgres:
    image: postgres:16
    environment:
      - POSTGRES_USER=outline
      - POSTGRES_PASSWORD=outline
      - POSTGRES_DB=outline
    volumes:
      - ./pg:/var/lib/postgresql/data
    restart: unless-stopped
  redis:
    image: redis:7
    restart: unless-stopped

Generate both secrets with openssl rand -hex 32 and never reuse them between instances; SECRET_KEY encrypts data at rest and changing it later is a rebuild. URL must be the exact public address, scheme included, because Outline builds every link, cookie, and OIDC callback from it. Put a reverse proxy with TLS in front; Outline enforces HTTPS by default and gets confused behind plain HTTP.

Local file storage, not S3

For years the documentation assumed S3 or MinIO for attachments, and a surprising number of guides still say you need an object store. You do not. FILE_STORAGE=local writes uploads to the mounted directory, which is what a homelab wants: one folder to back up next to the Postgres dump. Reach for S3-compatible storage only when you have several Outline replicas or a multi-hundred-gigabyte attachment library. The 250 MB upload cap in the example above is generous for screenshots and PDFs; raise it if people will drop videos in.

Backups are two artefacts: pg_dump of the database and a copy of the data directory. Outline also exports any collection, or the whole workspace, as a zip of Markdown files from the settings page. I schedule that monthly as a human-readable insurance policy, because a folder of .md files is useful even if the software that wrote it disappears.

BSL 1.1 is not open source, and it does not matter for you

The catalogue is right to flag the licence. Business Source License 1.1 lets you run, modify, and self-host Outline freely, but forbids offering it as a competing hosted service, and each release converts to a normal open-source licence 4 years after publication. For a company running its own wiki, or a family, none of the restrictions apply. It matters if you were planning to sell Outline hosting, and it matters to people who only run OSI-approved software as policy. The BSL text itself is short and worth the 5 minutes if policy is your concern. The hosted product costs about $10 per user per month at last check, which is the number to weigh your afternoon against.

Where it beats the alternatives, and where it doesn't

Against Notion and Confluence, the alternatives page covers the switch, and the short version is that Outline's editor is closer to Notion's feel than any other self-hosted option: slash commands, real-time cursors, nested documents, a search that returns results as you type. Import from both is built in.

Against the self-hosted field, it loses on two axes. BookStack has plain password login, a lighter stack, and a book-chapter-page hierarchy that non-technical staff find easier than free-form nesting. Docmost is the younger project chasing the same Notion-like target under a fully open licence. Outline wins on polish, search speed, and the Slack and API integrations, and it has 40,000 GitHub stars and 9 years of history behind those.

What I'd do

If you have an identity provider, wire OIDC and enjoy a wiki that logs everyone in automatically. If you do not, set up SMTP magic links and do not build an identity provider just for this. Run the compose stack above on a box with 2 GB spare, local file storage, nightly pg_dump, monthly Markdown export. For a team that lives in documents all day, Outline is the self-hosted wiki I would put in front of them; for a two-person homelab that wants a quick notes tool, BookStack is less ceremony for the same job.