DEPLOYING OUTLINE WIKI

Документации — важная часть в мире технологий, и обычно это вики. На самом деле во многих платформах (таких как GitHub, GitLab, BitBucket, Gitea  и пр.) уже есть встроенная вики! Однако она не такая гибкая и дружелюбная и чаще всего представляет обычный редактор MarkDown или Html.

Поэтому мы развернем Outline в качестве нашей вики и базы знаний, с помощью Docker.

Что такое Outline

Outline — это вики нового поколения. В принципе по стилю и дизайну она чем-то напоминает notion. Быстро ознакомиться можете здесь

Собираем Docker Compose

Для Outline требуется несколько вспомогательных сервисов:

• Redis
• Postgres
• Minio

С первыми двумя надеюсь более менее ясно, но что такое Minio? MinIO – автономное хранилище объектов, совместимое с Amazon S3. Нам он нужен для того чтобы сохранять сторонние ресурсы - изображения, видео, архивы, другие не текстовые форматы. Подробнее изучите на официальном сайте Minio.

Outline не имеет своей авторизации, она использует OpenID

В качестве сервиса для авторизации я использовал GitLab (хотя с этим и были проблемы, но об этом позже), но так же можно использовать Google, Azure, Slack.

Итак вот конфигурация docker-compose.yml:

version: "2"

networks:
  outline-internal:
    
services:
  outline_redis:
    image: redis
    restart: always
    container_name: outline_redis
    networks:
      - outline-internal

  outline_postgres:
    image: postgres:13
    restart: always
    container_name: outline_postgres
    environment:
      - POSTGRES_PASSWORD=outline
      - POSTGRES_USER=outline
      - POSTGRES_DB=outline
    networks:
      - outline-internal
    volumes:
      - ./data/postgres:/var/lib/postgresql/data:Z

  outline_minio:
    image: minio/minio
    restart: always
    container_name: outline_minio
    command: server --console-address 0.0.0.0:9001 /data
    volumes:
      - ./data/minio-data:/data:Z
    environment:     
      - MINIO_ROOT_USER=minio
      - MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}   
      - MINIO_BROWSER_REDIRECT_URL=${MINIO_BROWSER_REDIRECT_URL}  
    ports:
      - 8001:9001
      - 8000:9000

  outline:
    image: outlinewiki/outline
    user: root
    restart: always
    container_name: outline
    command: sh -c "yarn sequelize:migrate --env=production-ssl-disabled && yarn start --env=production-ssl-disabled"    
    depends_on:
      - outline_postgres
      - outline_redis
      - outline_minio
    environment:
      - PGSSLMODE=disable
      - SECRET_KEY=${SECRET_KEY}
      - UTILS_SECRET=${UTILS_SECRET}
      - DATABASE_URL=postgres://outline:outline@outline_postgres:5432/outline
      - REDIS_URL=redis://outline_redis:6379
      - URL=${WIKI_URL}
      - PORT=9000
      - AWS_ACCESS_KEY_ID=minio
      - AWS_REGION=us-east-1
      - AWS_SECRET_ACCESS_KEY=${MINIO_ROOT_PASSWORD}
      - AWS_S3_UPLOAD_BUCKET_URL=${WIKIDATA_URL}
      - AWS_S3_UPLOAD_BUCKET_NAME=outline
      - AWS_S3_UPLOAD_MAX_SIZE=26214400
      - AWS_S3_FORCE_PATH_STYLE=true
      - AWS_S3_ACL=private
      - OIDC_CLIENT_ID=${AUTH_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${AUTH_SECRET}
      - OIDC_AUTH_URI=http://gitlab.com/oauth/authorize
      - OIDC_TOKEN_URI=http://gitlab.com/oauth/token
      - OIDC_USERINFO_URI=http://gitlab.com/api/v4/user
      - OIDC_USERNAME_CLAIM=username
      - OIDC_DISPLAY_NAME=GitLab
      - OIDC_SCOPES=api     
      - FORCE_HTTPS=false      
      - DEPLOYMENT=hosted      
    ports:
      - 9000:9000
    networks:
      - outline-internal
      - reverseproxy-nw     

Так же создаем файл с переменными .env

SECRET_KEY=<the first hex key you generated>
UTILS_SECRET=<the second hex key you generated>
WIKI_URL=<http://wiki.mydomen.org>
WIKIDATA_URL=<http://wikidata.mydomen.org>
MINIO_BROWSER_REDIRECT_URL=<wikidata-admin.mydomen.org>

AUTH_CLIENT_ID=<gitlab_app_id>
AUTH_SECRET=<gitlab_secret>

MINIO_ROOT_PASSWORD=minio_password

С помощью openssl сгенерируем ключи для SECRET_KEY и UTILS_SECRET

openssl rand -hex 32

А ссылки указать те по которым у вас будет доступ. Я настраивал доступ через Nginx

GitLab

Теперь настроим авторизацию через GitLab

У меня по началу авторизация через GitLab не работала и пришлось немного менять исходник outline, тем самым я обрубил альтернативы авторизации через другие OpenID. Если вы не планируете авторизацию через GitLab то пропустите этот блок.

Outline получает информацию с помощью OpenID в gitlab через api пользователя: http://gitlab.com/api/v4/user

Из этого json парсит данные необходимые для регистрации и авторизации. Но так OpenID формат везде разный а больше был нацелен на Google данные, то пытается обратиться к полям которых в gitlab api просто нет, и возникает ошибка при авторизации:

"WHERE parameter \"providerId\" has invalid \"undefined\" value"

Поэтому мы изменим код и скомпилируем Outline для нашего случая.

Скачиваем исходники:

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

Далее редактируем файл server/routes/auth/providers/oidc.ts

Мы поменяли поля для получение avatarUrl и providerId

Теперь чтобы всё это скомпилировать и использовать в докер, добавим в корневом каталоге исходника docker-compose.yml и .env с содержимым выше, изменим сценарий получения. Теперь мы будем не забирать с хаба образ outline, а компилировать его сами. Добавьте секцию build:

  outline:
    image: outlinewiki/outline
    user: root
    restart: always
    container_name: outline
    command: sh -c "yarn sequelize:migrate --env=production-ssl-disabled && yarn start --env=production-ssl-disabled"
    build:
      context: .
      dockerfile: Dockerfile
      args:
        pull: 1

Запуск и настройка

Теперь наконец можно запустить.

$ docker-compose.yml
$ docker-compose up -d

Есть маленькая особенность. У меня outline стартовал раньше postgres и поэтому не мог подключиться пока postgres не стартанет и не инициализирует бд. Рекомендую подождать 2 минуты после запуска.

Поздравляю, мы смогли это запустить. Но это еще не всё. Теперь настроим хранилище Minio. Открываем http://localhost:8001

Вводим логин и пароль что указали в .env. В панели администратора необходимо создать bucker c именем outline

Теперь мы можем загружать изображения и другие медиа-файлы в нашу wiki

Итог

Наконец-то удалось развернуть мощную вики для документации с помощью docker.

Outline, вероятно, один из не простых контейнер Docker, который мне приходилось развертывать, но всё удалось сделать.

Основано на статье gurucomputing (Оригинал)