Установка Outline на Ubuntu 20.04 с Docker

TL;DR

Установите Outline на сервер Ubuntu 20.04 с помощью Docker, Docker Compose и Nginx в качестве обратного прокси. В этой пошаговой инструкции — настройка брандмауэра, установка Docker и Docker Compose, создание файлов окружения и docker-compose, получение SSL через Let’s Encrypt, настройка Nginx, интеграция со Slack и S3, а также рекомендации по обновлению, откату и безопасности.

Введение

Логотип и общий вид интерфейса Outline

Outline — это open-source платформа для совместной ведения базы знаний. Подходит для документирования, ведения внутренних вики и обмена заметками. Приложение включает Markdown-редактор и интеграции со Slack, Figma, Airtable, Google Docs, Trello, Zapier, Codepen, Spotify, YouTube и другими сервисами. В Outline есть механизмы прав доступа (группы, чтение/запись), публичный доступ к документам, поддержка RTL и переводы на 13 языков. Технологии: React и Node.js. Вы можете выбрать облачный вариант или развернуть Outline на собственном сервере.

Эта инструкция показывает, как развернуть Outline на сервере с Ubuntu 20.04 с использованием Docker.

Что потребуется

Сервер с Ubuntu 20.04 и минимум 1 ГБ ОЗУ (рекомендовано 2+ ГБ для реальной работы).
Нерутовый пользователь с правами sudo.
Домен, указывающий на сервер; в примерах используется https://outline.example.com.
Набор утилит для работы:

$ sudo apt install nano curl wget unzip gnupg

Важно: для PROD-развертывания рекомендуем минимум 2 ГБ оперативной памяти и выделение места для PostgreSQL и S3-хранилища.

Шаблон ролей и обязанностей (коротко)

Системный администратор: установка Docker, Nginx, настройка брандмауэра, SSL.
DevOps / инженер по платформе: управление контейнерами, резервные копии, обновления.
Владелец продукта/менеджер: конфигурация домена, интеграции (Slack, S3), доступы.
Ответственный за безопасность: аудит прав, политики S3, мониторинг.

Шаг 1 — Настройка брандмауэра (ufw)

Ubuntu включает ufw (Uncomplicated Firewall). Сначала проверьте статус:

$ sudo ufw status

Ожидаемый вывод:

Status: inactive

Разрешите SSH, чтобы не потерять доступ после включения брандмауэра:

$ sudo ufw allow OpenSSH

Разрешите HTTP и HTTPS:

$ sudo ufw allow 80
$ sudo ufw allow 443

Включите ufw:

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Проверьте статус снова:

$ sudo ufw status

Пример вывода:

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80                         ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80 (v6)                    ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Важно: если у вас нестандартный SSH-порт — откорректируйте правила заранее.

Шаг 2 — Установка Docker

Добавьте официальный GPG-ключ Docker:

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Добавьте репозиторий Docker:

$ echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Обновите индекс пакетов и установите Docker:

$ sudo apt update
$ sudo apt install docker-ce

Проверьте версию:

$ docker --version
Docker version 20.10.14, build a224086

Добавьте пользователя в группу docker, чтобы запускать команды без sudo:

$ sudo usermod -aG docker ${USER}
$ su - ${USER}

Совет: выход и повторный вход необходимы для применения membership группы.

Шаг 3 — Установка Docker Compose (v1.x)

В инструкции используется Docker Compose 1.29.2 (v1.x). Скачайте бинарник:

$ sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

Сделайте исполняемым:

$ sudo chmod +x /usr/local/bin/docker-compose

Проверьте:

$ docker-compose --version
docker-compose version 1.29.2, build 5becea4c

Добавьте автодополнение команд:

$ sudo curl \
    -L https://raw.githubusercontent.com/docker/compose/1.29.2/contrib/completion/bash/docker-compose \
    -o /etc/bash_completion.d/docker-compose
$ source ~/.bashrc

Примечание: Compose v2 является плагином Docker и имеет синтаксические отличия; если вы хотите использовать v2, проверьте совместимость файла docker-compose.yml.

Шаг 4 — Создание файла окружения (docker.env)

Outline требует провайдера авторизации и ряда секретов. Ниже — последовательность действий.

Настройка Slack для логина

Войдите в Slack и откройте Slack API Apps.

Страница Slack API для создания приложений

Нажмите Create an App, выберите From Scratch и задайте имя приложения и рабочее пространство.

Окно создания приложения Slack

Настройте описание, иконку и цвет, затем сохраните.

Параметры нового приложения Slack

В разделе OAuth and Permissions добавьте Redirect URL:

https://outline.example.com/auth/slack.callback

Поле Redirect URL в настройках Slack

В User Token Scopes добавьте: identity.avatar, identity.basic, identity.email, identity.team.

Выбор прав доступа Slack для identity

Скопируйте Client ID и Client Secret из Basic Information.

Данные клиента Slack: Client ID и Client Secret

Настройте Slash Command /outline с Request URL https://outline.example.com/api/hooks.slack.

Создание Slash-команды в Slack

В Features → Interactivity and Shortcuts включите Interactivity и укажите Request URL https://outline.example.com/api/hooks.interactive.

Включение интерактивности Slack для Outline

Установите приложение на рабочее пространство и сохраните App ID и Verification Token.

Установка приложения Slack в рабочее пространство

Настройка хранилища S3

Создайте S3-бакет в AWS или совместимом S3-сервисе для загрузки медиа Outline.
Добавьте CORS-политику (замените AllowedOrigins на ваш домен):

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST"
        ],
        "AllowedOrigins": [
            "https://docs.mycompany.com"
        ],
        "ExposeHeaders": []
    },
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": []
    }
]

Создайте IAM-пользователя с минимальными правами для работы с указанным бакетом (пример политики ниже — замените my-bucket-name):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor",
            "Effect": "Allow",
            "Action": [
                "s3:GetObjectAcl",
                "s3:DeleteObject",
                "s3:PutObject",
                "s3:GetObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::my-bucket-name/*"
        }
    ]
}

Сгенерируйте Access Key и Secret для этого пользователя и храните их в безопасном месте.

Создание секретных ключей

Сгенерируйте SECRET_KEY и UTILS_SECRET:

$ openssl rand -hex 32

Сохраните оба значения — они потребуются в файле docker.env.

Создайте и отредактируйте docker.env

Подготовьте каталог для конфигурации Docker:

$ mkdir ~/outline
$ cd ~/outline
$ nano docker.env

Вставьте (и отредактируйте) следующий шаблон, заменив значения на реальные:

# –––––––––––––––– REQUIRED ––––––––––––––––
SECRET_KEY=generate_a_new_key
UTILS_SECRET=generate_a_new_key

POSTGRES_USER=outlinepg
POSTGRES_PASSWORD=yourpassword
POSTGRES_DB=outline
DATABASE_URL=postgres://outlinepg:yourpassword@localhost:5432/outline
DATABASE_URL_TEST=postgres://outlinepg:yourpassword@localhost:5432/outline-test
PGSSLMODE=disable
REDIS_URL=redis://localhost:6379

URL=https://docs.example.com
PORT=3000

AWS_ACCESS_KEY_ID=get_a_key_from_aws
AWS_SECRET_ACCESS_KEY=get_the_secret_of_above_key
AWS_REGION=us-east-2
AWS_S3_UPLOAD_BUCKET_URL=https://my-bucket-name.s3.us-east-2.amazonaws.com
AWS_S3_UPLOAD_BUCKET_NAME=my-bucket-name
AWS_S3_UPLOAD_MAX_SIZE=26214400
AWS_S3_FORCE_PATH_STYLE=true

# –––––––––––––– AUTHENTICATION ––––––––––––––
SLACK_KEY=
SLACK_SECRET=

# –––––––––––––––– OPTIONAL ––––––––––––––––
GOOGLE_ANALYTICS_ID=UA-XXXXXXX-1

SLACK_VERIFICATION_TOKEN=your_token
SLACK_APP_ID=A0XXXXXXX
SLACK_MESSAGE_ACTIONS=true

FORCE_HTTPS=false
ENABLE_UPDATES=true
WEB_CONCURRENCY=2

Подсказка по WEB_CONCURRENCY: разделите доступную оперативную память на 512 МБ и примерно укажите число воркеров. Например, 2 ГБ → WEB_CONCURRENCY=4 (ориентировочно).

Сохраните файл (Ctrl+X → Y).

Шаг 5 — Создание docker-compose.yml

Создайте docker-compose.yml в той же директории:

$ nano docker-compose.yml

Вставьте:

version: "3"
services:

  outline:
    image: outlinewiki/outline:latest
    restart: always
    command: sh -c "yarn sequelize:migrate --env=production-ssl-disabled && yarn start --env=production-ssl-disabled"
    env_file: ./docker.env
    ports:
      - "3000:3000"
    depends_on:
      - postgres
      - redis

  redis:
    image: redis
    restart: always
    env_file: ./docker.env
    ports:
      - "6379:6379"
    volumes:
      - ./redis.conf:/redis.conf
    command: ["redis-server", "/redis.conf"]

  postgres:
    image: postgres
    restart: always
    env_file: ./docker.env
    ports:
      - "5432:5432"
    volumes:
      - database-data:/var/lib/postgresql/data

volumes:
  database-data:

Сохраните файл.

Примечание: для production-окружения рассмотрите отдельный volume для бэкапов, резервного копирования WAL (pgbackrest/pgdump) и мониторинга дискового пространства.

Шаг 6 — Запуск Outline (контейнеры)

Запустите контейнеры в фоне:

$ docker-compose up -d

Проверьте состояние:

$ docker ps

Параметры миграции выполняются автоматически при старте контейнера outline (см. команду в docker-compose).

Шаг 7 — Получение SSL через Let’s Encrypt (Certbot)

Установите snapd и Certbot:

$ sudo apt install snapd
$ sudo snap install core && sudo snap refresh core
$ sudo snap install --classic certbot
$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Сгенерируйте сертификат (замените email и домен):

$ sudo certbot certonly --standalone --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d outline.example.com

Сертификат будет в /etc/letsencrypt/live/outline.example.com.

Сгенерируйте Diffie-Hellman группу:

$ sudo openssl dhparam -out /etc/ssl/certs/dhparam.pem 2048

Создайте webroot для автоматического обновления и добавьте cron-задачу:

$ sudo mkdir -p /var/lib/letsencrypt
$ sudo nano /etc/cron.daily/certbot-renew

Вставьте:

#!/bin/sh
certbot renew --cert-name outline.example.com --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"

Сделайте исполняемым:

$ sudo chmod +x /etc/cron.daily/certbot-renew

Проверьте ручное обновление для проверки:

$ sudo certbot renew --dry-run

Шаг 8 — Установка Nginx (последняя стабильная версия)

Добавьте ключ подписи Nginx и репозиторий:

$ curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
    | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \
http://nginx.org/packages/ubuntu `lsb_release -cs` nginx" \
    | sudo tee /etc/apt/sources.list.d/nginx.list

$ sudo apt update
$ sudo apt install nginx

Проверьте версию и включите службу:

$ nginx -v
nginx version: nginx/1.20.2
$ sudo systemctl enable nginx

Шаг 9 — Конфигурация Nginx как обратного прокси

Создайте конфигурацию для вашего домена:

$ sudo nano /etc/nginx/conf.d/outline.conf

Вставьте (скорректируйте server_name и пути к сертификатам):

server {
        server_name outline.example.com;

        listen 443 ssl http2;
        listen [::]:443 ssl http2;

        access_log /var/log/nginx/outline.access.log;
        error_log /var/log/nginx/outline.error.log;

        ssl_certificate /etc/letsencrypt/live/outline.example.com/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/outline.example.com/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/outline.example.com/chain.pem;
        ssl_session_timeout 1d;
        ssl_session_cache shared:MozSSL:10m;
        ssl_session_tickets off;

        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;

        ssl_stapling on;
        ssl_stapling_verify on;
        ssl_dhparam /etc/ssl/certs/dhparam.pem;
 
        location / {
                proxy_pass http://localhost:3000;
                
                proxy_set_header Upgrade $http_upgrade;
                proxy_set_header Connection "Upgrade";
                proxy_set_header Host $host;
        
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Scheme $scheme;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_redirect off;
        }
}

## HTTPS Redirect
server {
        listen 80; 
        listen [::]:80;
        server_name outline.example.com;
        return 301 https://$host$request_uri;
}

Добавьте параметр в основной nginx.conf (если необходимо):

$ sudo nano /etc/nginx/nginx.conf

Добавьте строку перед include /etc/nginx/conf.d/*.conf;:

server_names_hash_bucket_size  64;

Проверьте синтаксис и перезапустите nginx:

$ sudo nginx -t
$ sudo systemctl start nginx

Заметка: в конфигурации обратного прокси важно корректно проксировать заголовки X-Forwarded-Proto и Host, чтобы Outline корректно определял HTTPS и строил ссылки.

Шаг 10 — Доступ и тестирование

Откройте https://outline.example.com в браузере. На экране входа вы увидите кнопку Continue with Slack для входа через Slack.

Страница входа Outline

Авторизуйтесь через Slack:

Окно подтверждения авторизации Slack для Outline

После входа вы попадёте на главную страницу Outline и сможете создавать документы.

Главная страница Outline

Интеграция со Slack позволяет выполнять поиск по документам и вставлять ссылки через Slash-команду /outline <поисковый_запрос>.

Пример сообщения Slack с результатом поиска Outline

Демонстрация результата поиска Outline в Slack

Шаг 11 — Обновление Outline и откат

Процесс обновления:

Остановите и удалите старые контейнеры (без удаления данных):

$ docker-compose down --remove-orphans

Заберите новые образы:

$ docker-compose pull

Выполните миграции БД:

$ docker-compose run --rm outline yarn db:migrate --env=production-ssl-disabled

Запустите контейнеры с новыми образами:

$ docker-compose up -d

Откат (быстрый runbook):

Если после обновления приложение не работает — немедленно остановите контейнеры и запустите предыдущую версию образа (если у вас сохранён тег предыдущей версии). Практика: не используйте тег latest в production — фиксируйте теги образов.
Вариант отката по шагам:
1. docker-compose down
2. В docker-compose.yml заменить image: outlinewiki/outline:latest на конкретный тег предыдущей рабочей версии, например outlinewiki/outline:2022-08-01
3. docker-compose up -d
4. Если требуется, откатить схему БД вручную — имейте полную резервную копию БД перед миграцией.

Критериям отката и бэкапа посвящён раздел «Резервные копии» ниже.

Резервные копии и восстановление

PostgreSQL: регулярно делайте pg_dump (полные бэкапы) и сохраняйте за пределами сервера (S3). Для больших баз используйте WAL-архивирование и инструмент pgbackrest.
Redis: снимайте rdb/а типа бэкапы или используйте репликацию.
Файловые объекты: если вы используете локальный storage — копируйте директории; при S3 — объектное хранилище уже надёжно хранит объекты (но контролируйте версии и права доступа).

Пример простого ежедневного бэкапа PostgreSQL в S3 (скрипт, упрощённо):

pg_dump -U outlinepg -h localhost outline | gzip > /tmp/outline-$(date +%F).sql.gz
aws s3 cp /tmp/outline-$(date +%F).sql.gz s3://my-backups-bucket/outline/

Важно: храните бэкапы не только локально на том же сервере.

Безопасность и жёсткие рекомендации

Минимизируйте IAM-права для S3-пользователя (принцип наименьших прав).
Храните SECRET_KEY и UTILS_SECRET в защищённом хранилище (Vault/Secrets Manager) и не коммитьте docker.env в git.
Регулярно проверяйте обновления безопасности для контейнеров и хоста.
Включите мониторинг (CPU, RAM, диск) и алертинг для критических метрик.
Защитите административный интерфейс Slack-приложения и следите за разрешениями.
При использовании внешних интеграций — применяйте HTTPS и проверяйте whitelisted redirect URLs.

Критерии приёмки

Веб-интерфейс доступен по HTTPS без ошибок сертификата.
Вход через Slack работает: пользователь может авторизоваться и создать документ.
Медиа-файлы загружаются в S3 и доступны по публичным или приватным ссылкам согласно настройкам.
База данных и Redis поднимаются и данные сохраняются после перезапуска контейнеров.
Автообновление SSL (certbot renew) проходит успешно (dry-run).

Чек-лист перед запуском в production

SECRET_KEY и UTILS_SECRET сгенерированы и сохранены.
Docker и Docker Compose установлены, сервисы тестированы.
Бэкапы PostgreSQL настроены и проверены на восстановление.
S3 и IAM настроены минимальными правами и CORS.
Nginx настроен и сертификаты установлены.
Мониторинг и алертинг настроены (prometheus, grafana, или облачные аналоги).

Альтернативные варианты развертывания

Развернуть Outline на Kubernetes (Helm chart) — для кластерного окружения и автоматического масштабирования.
Использовать managed PostgreSQL и managed Redis (RDS, ElastiCache) для упрощения операций.
Использовать Docker Swarm или Nomad как альтернативы Kubernetes.

Когда не подходит этот рецепт

Если у вас требование к высокой доступности (HA) на уровне приложения и БД — одно-node docker-compose не обеспечит отказоустойчивость.
Для крупных команд с высокой нагрузкой потребуются отдельные слои (балансировщик, несколько реплик Outline, логирование, шардирование БД).

Быстрая шпаргалка переменных (cheat sheet)

SECRET_KEY — секрет приложения (32 байта hex), обязательный.
UTILS_SECRET — дополнительный секрет для утилит.
DATABASE_URL — строка подключения к PostgreSQL.
REDIS_URL — адрес Redis.
URL — публичный URL вашего приложения (https).
AWS_S3_UPLOAD_BUCKET_NAME — имя S3-бакета для загрузок.
SLACK_KEY / SLACK_SECRET — OAuth-креды Slack.
WEB_CONCURRENCY — число рабочих процессов Node; ориентируйтесь: ОЗУ/512.

Рольовые чек-листы перед обновлением

Администратор приложения:

Проверил доступность бэкапов и их целостность.
Убедился, что в конфигурации указаны конкретные теги образов.

DevOps:

Проверил логи после запуска миграций в тестовом окружении.
Подготовил план отката и проверил доступность старых образов.

Менеджер продукта:

Согласовал окно обслуживания и уведомил пользователей.

Короткий runbook на случай инцидента

Если сайт недоступен:
- Проверить docker ps и журналы: docker-compose logs outline
- Проверить состояние nginx: sudo systemctl status nginx && sudo nginx -t
Если проблема в миграции БД:
- Восстановить из последнего бэкапа: pg_restore или восстановление WAL (в зависимости от стратегии).
При проблемах с SSL:
- Выполнить certbot renew –dry-run и проверить логи /var/log/letsencrypt.

Когда и как масштабировать

Вертикально: увеличьте ресурсы VM (CPU/RAM) и скорректируйте WEB_CONCURRENCY.
Горизонтально: используйте Kubernetes и настройте несколько реплик Outline с внешней БД и Redis-кластером.

Совместимость и миграция версий

Проверяйте CHANGELOG проекта Outline перед обновлением.
Не обновляйте до мажорной версии без тестирования в staging.
Для перехода между major-версиями иногда требуются дополнительные миграции БД — держите бэкапы.

Заключение

Эта инструкция покрывает полный путь установки Outline на Ubuntu 20.04 с Docker: от настройки брандмауэра и установки Docker до получения SSL, настройки Nginx и интеграции со Slack и S3. Настройте резервное копирование, мониторинг и процесс обновлений, чтобы поддерживать сервис в рабочем состоянии.

Важно: перед развёртыванием в production протестируйте процесс обновления и восстановления на отдельной тестовой среде.

Если у вас возникли вопросы по настройке — опишите проблему и шаги, которые вы уже предприняли, чтобы получить целевой совет.

Краткое содержание (summary):

Установите Docker и Docker Compose, создайте docker.env и docker-compose.yml.
Настройте Slack и S3 для интеграций и хранения медиа.
Получите SSL через Let’s Encrypt и настройте Nginx как обратный прокси.
Настройте бэкапы, мониторинг, процесс обновлений и план отката.