# Outline

Outline is a fast, collaborative knowledge base and wiki for teams

[Outline](https://github.com/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.