How to Use Outline: A Beginner's Guide to the Self-Hosted Team Wiki

CodexFuse Team · 2026-10-31T22:33:26.243Z · 13 min read min read

Install Outline v1.12.0 with Docker, sign in with SSO or magic-link, create your first collection and document, and learn the permissions model teams actually use.

This outline wiki tutorial shows you how to use Outline, the self-hosted team wiki, from a blank server to a workspace your team actually writes in: install it with Docker, get past the one auth surprise that stops every beginner, sign in as your first admin, create your first collection, write your first document, and learn the permissions model before your team grows. First, a disambiguation you need in the first minute: this Outline is the team wiki at getoutline.com (github.com/outline/outline, built by General Outline, Inc.), not the Outline VPN made by Jigsaw, which is a completely different product that happens to share the name. If your first wiki will live in containers, read our Docker beginner guide first so the install section below feels familiar.

Follow this outline for beginners guide in order. Each section opens with the direct answer, then the detail. You will finish with a running Outline instance (current release v1.12.0), one workspace, one collection, one document, and a permissions setup that will not embarrass you later.

What is Outline, exactly?

Outline is a self-hosted, browser-based team wiki in the shape of Notion: documents that nest into trees, collections that group them by team or topic, real-time collaborative editing, full-text search, and fine-grained permissions. You run the server yourself (on your VPS or in your company's network), and your team reads and writes documentation through its clean editor at your own domain. It is built for teams replacing Notion or Confluence with documentation they control — a true self hosted team wiki, where outline self hosted means your data never leaves your server.

Two facts frame everything else. The project is source-available under the Business Source License 1.1, not an OSI open-source license — the licensing section below says what that means for you. And Outline has no native username-and-password login: you sign in with an SSO/OIDC provider (Slack, Google, Microsoft Entra, Discord, or any OIDC provider like Authentik or Keycloak) or with a magic-link email, which is the number-one beginner surprise and has its own section below.

Your first hour with Outline, in order

Here is the whole arc in ten steps. Each one maps to a section below.

1. Understand what Outline is and is not (wiki, not VPN; source-available, not open source).
2. Provision a VPS and a domain — Outline needs a real public URL for auth callbacks.
3. Generate the two random secrets every install needs (openssl rand -hex 32).
4. Start Outline with Docker Compose alongside Postgres and Redis.
5. Configure at least one auth method — SSO/OIDC or magic-link email via SMTP.
6. Sign in for the first time: the first user automatically becomes the admin.
7. Create your first collection and pick who can see it.
8. Write your first document and learn the editor basics.
9. Set up roles and permissions: admins, editors, viewers, and per-collection access.
10. Share your first document with a teammate and review the common mistakes table.

Is Outline open source?

No — Outline is source-available, not open source. The repository is licensed under the Business Source License 1.1 (Licensor: General Outline, Inc., covering Outline 1.12.0), and the license text states plainly that it "is not an Open Source license." Many third-party guides loosely call it open source; the verified legal fact is BSL 1.1.

Practically, the license's additional use grant lets you use, copy, modify, and run Outline in production inside your own company. What you may not do is run it as a "Document Service" — a commercial offering that lets third parties who are not your employees or contractors create their own teams and documents on it. The BSL converts to the Apache License 2.0 on the change date 2030-10-23. For a team self-hosting its own wiki, none of this is a problem; for anyone thinking of building a hosted product on top of Outline's code, it is.

What do you need before installing Outline?

You need a VPS with a public IP, a domain (or subdomain) pointed at it, Docker installed, and about five minutes. Read our what is VPS hosting guide if you have never rented a server before — Outline's stack is a Node.js app plus Postgres and Redis, and all three must be running for the app to start.

Two things beginners underestimate. First, Outline must be reachable at a fully qualified public URL, because the auth callbacks (for example https://wiki.yourcompany.com/auth/oidc.callback) have to match byte-for-byte at your identity provider — localhost or a bare IP will come back to haunt you. Second, plan your auth method before you install: you need either an SSO/OIDC provider or a working SMTP server for magic-link email, and there is no "just add a password" fallback.

How do you install Outline with Docker?

You install Outline with the official outlinewiki/outline Docker image, wired to Postgres and Redis through a compose file and five required environment variables. The app listens on port 3000; a reverse proxy in front handles TLS and the public domain.

Start by generating the two secrets. Never leave placeholder values in place — wrong formats crash the app on boot:

openssl rand -hex 32   # SECRET_KEY
openssl rand -hex 32   # UTILS_SECRET

Then set the five required variables (from the official .env.sample):

SECRET_KEY=...            # from openssl above
UTILS_SECRET=...          # from openssl above
DATABASE_URL=postgres://user:pass@postgres:5432/outline
REDIS_URL=redis://redis:6379
URL=https://wiki.yourcompany.com   # your real public URL

Note the DATABASE_URL host: inside Docker networking it must be the compose service name (postgres), not localhost. Your compose file runs three services — postgres, redis, and outline with env_file: .env pointing at these variables. Bring it up, watch the logs for migrations completing, then open your URL. If the page loads, the install worked; everything from here is configuration.

Why is there no password box? The auth rule.

Because Outline deliberately does not support email-and-password login natively — the official hosting docs state this verbatim. You sign in with SSO/OIDC (Slack, Google, Microsoft Entra, Discord, or any generic OIDC provider — Authentik, Keycloak, Auth0, Okta, Authelia, and Zitadel all work with automatic discovery) or with magic-link email, and at least one auth provider must be configured or the sign-in page will offer you nothing at all.

Each path has one setup cost. OIDC needs a client ID and secret at your provider plus the callback URL registered as https://your-url/auth/oidc.callback — register it exactly, because a trailing-slash or http/https mismatch is the number-one cause of redirect_uri errors. Magic-link needs an SMTP server for transactional email (document updates and sign-in links go through it); without SMTP configured, magic-link sign-in silently cannot work. If you have no identity provider yet and want one you control, our Authentik beginner guide walks through the outline authentik OIDC setup that pairs naturally with Outline.

Who becomes the admin?

The first user to sign in becomes the admin — by default, no setup wizard assigns the role. Sign in yourself first, before you share the URL with anyone, because whoever gets there first gets full control of the workspace including billing and integrations. After that, admins can promote or demote other users from the settings.

Outline's workspace roles are four: Admin (full control), Editor (the default — can view, create, edit, and comment in visible collections), Viewer (view and comment only, can be upgraded per collection or document), and Guest (no access unless explicitly shared something — note that the guest role is not available in the self-hosted community edition). Think of it this way: roles are what a person is; collection permissions are what they can touch.

How do collections work in Outline?

Outline collections group documents by team or topic and act as a permissions boundary — admins choose exactly who can access and edit each one. One team, one collection is the pattern that survives growth: "Engineering", "Support playbooks", "Company handbook", each with its own membership.

Create your first collection from the sidebar, give it a clear name, and decide its visibility before you add documents. A collection can be shared with the whole workspace, with specific groups, or kept private to a few people; documents inside inherit the collection's permissions and can tighten or loosen them individually. The cascade runs one way: collection permissions flow down into documents, and parent documents pass theirs to child documents. The permissions lesson, in one line: decide at the collection level, override at the document level only for exceptions.

How do you write your first document?

You write your first document by clicking New doc inside your collection and typing — the editor handles headings, tables, code blocks, checklists, diagrams, and embeds, and everything saves as you type. Documents nest into trees exactly like folders, so start one "home" document per collection and let structure grow underneath it instead of flattening everything into one long list.

Two editor habits worth building on day one. First, name every document like someone will search for it — Outline's full-text search is the main way people find things, and "Week of Nov 3 standup notes" beats "Notes". Second, reach for templates for anything your team writes repeatedly: a template is just a document with placeholder input fields, and it keeps incident reports, specs, and onboarding docs consistent without anyone thinking about it. Documents also export to Markdown losslessly, so your content is never trapped.

Who can see and edit what? The permissions lesson.

Permissions are set at the collection level and inherited downward, with three levels: read, read_write, and admin — higher includes lower. Outline permissions cascade from collections into documents and from parent documents into their children. An admin grants a user or group a level on a collection; documents inside start at that level and can be adjusted per document or per group.

Group sharing keeps this manageable: instead of adding people one by one, create groups ("Engineering", "Support"), put users in them, and share collections with groups. One more recent fact worth knowing: since October 2026, Outline supports personal documents that stay private even from admins — useful for drafts you are not ready to share.

Outline vs Notion vs Confluence: which should you use?

Use Outline if you want Notion-shaped editing with your data on your own server; stay with Notion if you want zero infrastructure; stay with Confluence if your company already lives in Atlassian. This outline vs notion vs outline vs confluence comparison keeps it honest:

Outline's closest self-hosted cousins are Docmost and BookStack — both stay as comparison members of this guide rather than their own pages, because they serve the same team-wiki intent. Docmost is the lighter, simpler sibling; BookStack organizes strictly as books-chapters-pages; Outline sits between them with the most Notion-like editing and the strongest permissions model. If your team already writes in Notion-style blocks, Outline is the shortest migration.

Outline Cloud or self-hosted: what does it cost?

Self-hosting the Community Edition costs $0 plus your server; Outline Cloud starts at $10/month. The 2026 pricing, verified this week:

Two billing facts that surprise teams: every signed-in role — admin, editor, viewer, even guest — consumes one seat, and non-profits and educational organizations get a 30% discount. For a team wiki, the math is simple: if you already run a VPS, self-hosting is nearly free; if you want someone else to run it, Cloud's flat tiers are predictable until you pass 200 people.

What goes wrong most often? 7 beginner mistakes.

Sources

• Outline GitHub releases API (v1.12.0, released 2026-10-23) — https://api.github.com/repos/outline/outline/releases/latest
• Outline GitHub repository (stars, forks, NOASSERTION license field) — https://github.com/outline/outline
• Outline LICENSE (Business Source License 1.1, change date 2030-10-23) — https://github.com/outline/outline/blob/main/LICENSE
• Outline .env.sample (required env vars, auth providers, SMTP requirement) — https://github.com/outline/outline/blob/main/.env.sample
• Outline hosting docs: Authentication ("does not support email + password authentication natively") — https://docs.getoutline.com/s/hosting/doc/authentication-7ViKRmRY5o
• Outline hosting docs: OIDC (all OIDC-compatible providers, automatic discovery) — https://docs.getoutline.com/s/hosting/doc/oidc-8CPBm6uC0I
• Outline guide docs: Terminology (workspace, collection, document, templates) — https://docs.getoutline.com/s/guide/doc/terminology-fKoXA2YGzH
• Outline guide docs: Users & roles (first user becomes admin) — https://docs.getoutline.com/s/guide/doc/users-roles-cwCxXP8R3V
• Outline pricing (Cloud tiers, self-hosted editions, seat rules) — https://www.getoutline.com/pricing
• Outline changelog: group document membership — https://www.getoutline.com/changelog/group-document-membership

Frequently Asked Questions

Is Outline free to use?

Yes for self-hosting: the Community Edition is free ($0) and you run it on your own server. Outline Cloud is paid ($10–$249/month by workspace size, 30-day free trial). The source is under the Business Source License 1.1, which allows internal production use but is not an open-source license.

Does Outline have a mobile app or desktop app?

Outline is primarily a browser app. The v1.12.0 release notes mention passkey login in the desktop app, so desktop clients exist, but the browser is the canonical experience — everything in this guide happens at your Outline URL.

How is Outline different from the Outline VPN?

They only share a name. Outline (getoutline.com) is the team wiki by General Outline, Inc.; the Outline VPN is a Jigsaw product for running VPN servers, supported at support.getoutline.org. If a search result talks about VPN servers, it is the other product.

Can I migrate my Notion docs to Outline?

Outline is built in Notion's shape — nested documents, collections, blocks — which makes manual migration straightforward, and documents export to Markdown losslessly so you can move content both ways. There is no one-click Notion importer covered here; plan a collection-by-collection move.

Do I need a separate identity provider like Authentik?

No — "outline authentik" is a popular pairing, but running your own identity provider is optional. You need at least one auth method: Slack, Google, Microsoft Entra, Discord, any generic OIDC provider (Authentik, Keycloak, Auth0, Okta), or magic-link email with SMTP. Self-hosted teams often pair Outline with Authentik to keep logins under their own control.