Outline

Outline is a team wiki with real-time collaborative editing, a Notion-style editor and integrations with Slack, GitHub and more. It is a Node.js application using PostgreSQL and Redis, built with Yarn and Vite. Outline is published under the Business Source License 1.1, which permits self-hosting for your own organization but not offering it as a document service to third parties.

Requirements

Create a PostgreSQL database and a Redis database on the app's Databases tab. Hatchbox attaches them as DATABASE_URL and REDIS_URL, which are the names Outline expects.

Outline has no built-in username and password login. You must configure at least one sign-in provider: Google, Slack, Microsoft Entra, Discord or a generic OIDC provider.

The Vite build needs several GB of RAM. Build on a server with at least 4 GB free.

Repository

Fork the upstream repository and deploy your fork from a release tag such as v1.10.1 rather than main.

https://github.com/outline/outline.git

In your fork, change .nvmrc from 26 to 26.3.0. Outline's package.json only supports Node 26 <26.3.1 (or 24 <24.17.0), but with .nvmrc set to 26 Hatchbox would install the newest 26.x. Then add the .hatchbox/post-build script below.

Environment Variables

NODE_ENV=production
URL=https://wiki.example.com
SECRET_KEY=...                   # `openssl rand -hex 32`
UTILS_SECRET=...                 # `openssl rand -hex 32`
PGSSLMODE=disable
FORCE_HTTPS=false
FILE_STORAGE=local
FILE_STORAGE_LOCAL_ROOT_DIR=/home/deploy/outline/shared/data
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

URL is the public address of your Domains tab entry. PGSSLMODE=disable is needed because Outline connects to PostgreSQL over SSL in production by default and Hatchbox databases do not use SSL. FORCE_HTTPS=false leaves HTTPS redirection to Caddy. Replace the Google variables with the provider you use; see .env.sample in the repository for the Slack, Azure, Discord and OIDC names, and for SMTP settings if you want email notifications.

To store attachments in S3 instead of on disk, set FILE_STORAGE=s3 with the AWS_* variables from .env.sample.

Build Scripts

Hatchbox runs yarn install. The script below compiles the app and, on the cron server only, applies database migrations. The --env=production-ssl-disabled flag matches PGSSLMODE=disable above.

.hatchbox/post-build

#!/usr/bin/env bash
set -e

export NODE_OPTIONS="--max-old-space-size=4096"
yarn build

if [ "$CRON" = "true" ]; then
  mkdir -p $DIR/shared/data
  yarn db:migrate --env=production-ssl-disabled
fi

Make the file executable before committing it.

Processes

Outline reads PORT from the environment. One process runs the web server, websockets, collaboration server and background worker together:

• web: yarn start

To split the worker onto worker servers instead, use yarn start --services=web,websockets,collaboration on the web servers and yarn start --services=worker on the worker servers.

First Login

Open your domain and sign in with the provider you configured. The first user creates the workspace and becomes its admin.

Notes

With FILE_STORAGE=local, uploads live in $DIR/shared/data on a single server; use S3 for multi-server clusters. To update, merge a newer release tag into your fork and deploy; the build script applies migrations, and Outline checks for pending migrations at startup.