# Запуск сервера співпраці

Що зберігає Oleafly Server, що йому потрібно і як установити його однією командою, запустити через Docker Compose, Coolify, Render, Railway або як звичайну службу Linux, а потім стати його першим адміністратором.

Oleafly Server є сервером співпраці, що стоїть за спільною роботою в реальному часі. Ваша лабораторія, кафедра чи установа запускає його на власних машинах або у власному хмарному обліковому записі. Люди додають його в Oleafly і входять з уже наявним обліковим записом, як-от GitHub або університетським входом. Коли хтось дає доступ до проєкту на сервері, додані ним люди отримують повну копію, яка залишається синхронізованою, поки вони редагують. Якщо ввімкнено [доступ через браузер](/docs/collaboration/server-access/#browser-access), вони також можуть відкрити його у веббраузері.

Цей посібник призначено для людини, яка запускає сервер для лабораторії, курсу або групи співавторів. Вам має бути зручно працювати в терміналі. У деяких варіантах налаштування доведеться також відредагувати файл конфігурації. Писати код не потрібно.

Для перевірки безпеки прочитайте [Безпека сервера](/security/). Цей документ охоплює власне розміщення, вхід, ключі пристроїв, підписані зміни, журнал безпеки та журнали доступу, а також образ контейнера з переліком його програмних компонентів.

## Що зберігає сервер

Сервер зберігає все в одній теці з даними, яку задає `OLEAFLY_DATA_DIR`:

- **Облікові записи**: показуване ім’я кожного учасника, адресу його аватара, підтверджені адреси електронної пошти, а також його ідентифікатор користувача та логін у сервісі входу. Сервер ніколи не бачить і не зберігає пароль.
- **Пристрої**: кожен комп’ютер, який виконав вхід, з його назвою, операційною системою, відкритим ключем і часом, коли його востаннє було видно. Токени входу зберігаються лише у вигляді хешів.
- **Журнал безпеки**: входи та відхилені входи, додані пристрої та вихід із них, зміни учасників, ролей і налаштувань, надання доступу до проєктів, їх архівація та відновлення, зміни того, хто може відкривати проєкт, і запрошення гостей. Кожен запис містить час і IP-адресу.
- **Налаштування сервера**, які адміністратори змінюють в Oleafly.
- **Журнали доступу до проєктів** для проєктів, у яких власник увімкнув такий журнал: хто відкривав проєкт, приєднувся до нього чи завантажував копію, з назвою пристрою та часом. Читати його може лише власник проєкту.
- **Запрошення гостей**: запрошена адреса електронної пошти, проєкт, роль і те, хто надіслав запрошення.
- **Спільні проєкти**: кожен файл і повна історія змін, а також коментарі, пропозиції, чат і назви версій, що до них належать.
- **Скомпільовані PDF**: для кожного спільного проєкту найновіший PDF і його файл SyncTeX, які застосунок власника чи редактора надіслав після успішної компіляції, а також те, хто й коли скомпілював цей PDF.

Записи в журналі безпеки та журналах доступу, а також прийняті чи прострочені запрошення гостей видаляються через `OLEAFLY_SECURITY_LOG_DAYS` днів, за замовчуванням 365. Файли, яких проєкт більше не використовує, як-от стара копія заміненого рисунка, видаляються через 30 днів після останнього використання їх проєктом. Кожен скомпільований PDF замінює попередній. Коли власник припиняє спільний доступ до проєкту, сервер зберігає його лише для читання `OLEAFLY_ARCHIVE_DAYS` днів, за замовчуванням 30, а потім видаляє. Упродовж цього часу завантажити його можуть лише власник і будь-які адміністратори проєкту.

### Хто може читати проєкти

Проєкти на сервері не шифруються. Будь-хто, хто може читати теку з даними, диск машини або ваші резервні копії, може прочитати кожен проєкт, що там зберігається. Серед них і ті, хто керує машиною, і компанія, яка надає їй хостинг.

Всередині Oleafly правила суворіші. Жодна роль на сервері, зокрема адміністратор, не може відкрити проєкт, якщо власник проєкту не додав цю людину. Якщо проєкт має залишатися недоступним для людей, які керують сервером, запустіть для нього окремий сервер.

Комп’ютер кожного учасника також зберігає повну копію кожного проєкту, доступ до якого йому надано. Попросіть учасників увімкнути шифрування диска, як-от FileVault на macOS, BitLocker на Windows або LUKS на Linux.

## Що вам потрібно

- **Машина, що працює постійно.** Підійде будь-яка машина з Linux або обліковий запис у сервісі хостингу, як-от Render чи Railway. Для початку достатньо невеликої віртуальної машини. Стежте за її пам’яттю та диском у міру зростання проєктів. Сервер працює на x86-64 і ARM.
- **Доменне ім’я** для сервера, як-от `collab.example.org`, із DNS-записом, що вказує на машину. Render і Railway видадуть вам адресу, якщо її немає. Якщо машина не має публічної адреси, прочитайте розділ [Без публічної адреси](#without-a-public-address).
- **Спосіб входу для людей**: щонайменше один провайдер входу, як-от застосунок GitHub OAuth або вхід вашої установи. Без нього сервер не запуститься. Обліковий запис електронної пошти, з якого сервер може надсилати листи, необов’язковий. З ним адміністратор може також дозволити людям входити за посиланням із листа. Прочитайте розділ [Вхід і доступ](/docs/collaboration/server-access/).

Кожен випуск публікується як образ контейнера `ghcr.io/oleafly/oleafly-server`. Інсталятор і його файли Compose лежать на [сторінці випусків Oleafly Server](https://github.com/Oleafly/oleafly-server/releases). Сервер як окрема програма для Linux — на [сторінці випусків Oleafly](https://github.com/Oleafly/Oleafly/releases).

## Виберіть спосіб запуску

| Варіант | Коли використовувати |
| --- | --- |
| [Одна команда](#install-with-one-command) | Машина з Linux, яку ви обслуговуєте. Інсталятор налаштує Docker, Caddy і HTTPS та поставить кілька запитань. Почніть звідси, якщо не впевнені. |
| [Docker Compose вручну](#docker-compose-by-hand) | Ви волієте самі розміщувати й редагувати кожен файл. |
| [Coolify](#coolify) | Ви вже обслуговуєте сервер Coolify. |
| [Render](#render) або [Railway](#railway) | Ви волієте платити сервісу хостингу, а не доглядати машину самостійно. |
| [Linux без Docker](#linux-without-docker) | Університетська віртуальна машина, де не можна використовувати Docker. |

Сервер читає свої налаштування зі змінних середовища. У документі [Сховище, резервні копії та обмеження](/docs/collaboration/server-operations/#settings) перелічено кожну з них.

## Встановлення однією командою

На машині з Linux, яку ви обслуговуєте самі, інсталятор налаштує все і запитає лише те, що йому потрібно знати.

Перед запуском перевірте, що:

- Машина працює на Linux з архітектурою x86-64 або ARM, як-от Ubuntu 24.04 чи Debian 13, і ви можете використовувати на ній `sudo`.
- Нічого іншого на машині не займає порти 80 і 443. Відкрийте TCP-порти 80 і 443 та UDP-порт 443 у будь-якому брандмауері перед нею.
- DNS-запис вашого домену вказує на машину. Якщо ще ні, встановлення все одно завершиться, а Caddy продовжуватиме намагатися отримати сертифікат, доки запис не з’явиться.
- У вас є дані щонайменше одного [способу входу](/docs/collaboration/server-access/#sign-in-providers), наприклад ідентифікатор клієнта та секретний ключ застосунку GitHub OAuth. Для GitHub адреса зворотного виклику — це `https://` і ваш домен, а після них `/auth/callback/github`.

:::note[Період бети]
Установіть реліз-кандидат Oleafly Server 0.1.1-rc, щоб сервер відповідав Oleafly 0.4.7-rc:

```sh
curl -fsSL https://github.com/Oleafly/oleafly-server/releases/download/server-v0.1.1-rc/install.sh | sudo sh
```

Наведена нижче команда встановлює версію 0.1.0, яка старіша. Якщо ви запускаєте образ іншим способом, наприклад через Compose, Coolify, Render чи Railway, використовуйте `ghcr.io/oleafly/oleafly-server:0.1.1-rc`.
:::

Потім запустіть:

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo sh
```

Інсталятор:

1. Перевіряє машину і те, що порти 80 і 443 вільні.
2. Перевіряє наявність Docker. Якщо його немає, інсталятор запитує дозвіл перед установленням його за допомогою власного скрипта Docker.
3. Завантажує файли найновішого випуску зі [сторінки випусків Oleafly Server](https://github.com/Oleafly/oleafly-server/releases) і звіряє кожен із `SHA256SUMS` випуску. Якщо файл не збігається, зупиняється, нічого не змінюючи.
4. Запитує ваш домен, назву сервера і те, як люди входять. Також пропонує налаштувати електронну пошту та зберігати файли в бакеті S3. Обидва варіанти необов’язкові.
5. Показує зведення і запитує підтвердження перед будь-якими змінами. Потім записує свої файли до `/opt/oleafly-server`, а ваші налаштування — до `.env`, який може читати лише root.
6. Запускає сервер із Caddy попереду, чекає, доки ваш домен почне відповідати по HTTPS, і виводить адресу та код налаштування.

Потім [станьте першим адміністратором](#become-the-first-admin).

Інсталятор можна запускати повторно будь-коли. Коли він знаходить сервер у `/opt/oleafly-server`, він лишає `.env` як є, відновлює інші файли та перезапускає сервер. Це виправляє більшість пошкоджених налаштувань.

Ваші дані зберігаються в томі Docker `oleafly-server_oleafly-data`. Щоб установити сервер в інше місце, ніж `/opt/oleafly-server`, задайте `OLEAFLY_DIR`, наприклад `curl -fsSL https://oleafly.com/server/install.sh | sudo OLEAFLY_DIR=/srv/oleafly sh`, і використовуйте цю теку в командах нижче.

### Спочатку прочитайте інсталятор

Якщо ваша установа не дозволяє передавати скрипт одразу в оболонку, завантажте `install.sh` і `SHA256SUMS` з [останнього випуску](https://github.com/Oleafly/oleafly-server/releases/latest) в одну теку. Перевірте скрипт, прочитайте його, а потім запустіть:

```sh
sha256sum --check --ignore-missing SHA256SUMS
sudo sh install.sh
```

### Встановлення без запитань

Для скрипта або інструмента автоматичного розгортання додайте `--yes` і передайте відповіді змінними середовища. `OLEAFLY_INSTALL_DOCKER=yes` дозволяє інсталятору додати Docker, якщо його немає.

```sh
curl -fsSL https://oleafly.com/server/install.sh | sudo \
  OLEAFLY_DOMAIN=collab.example.org \
  OLEAFLY_SERVER_NAME='Smith Lab' \
  OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId \
  OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret \
  OLEAFLY_INSTALL_DOCKER=yes \
  sh -s -- --yes
```

Інсталятор використовує будь-який параметр, знайдений у середовищі, не запитуючи, з `--yes` чи без нього. `sudo sh /opt/oleafly-server/install.sh --help` перелічує їх усі, зокрема OpenID Connect, пошту та S3. Значення, введені в командному рядку, можуть потрапити в історію вашої оболонки, тож інструмент розгортання має передавати секрети з власного сховища секретів.

### Статус, оновлення та видалення

- **Статус**: `sudo sh /opt/oleafly-server/install.sh status` показує, чи працює сервер і чи відповідає ваш домен по HTTPS із чинним сертифікатом.
- **Оновлення**: спершу зробіть резервну копію, як пояснюється в розділі [Оновлення](/docs/collaboration/server-operations/#updating). Потім виконайте наведену нижче команду. Вона завантажує файли та образ найновішого випуску, лишає `.env`, перезапускає сервер і чекає, доки він відповість. Під’єднані люди перепід’єднуються самі. Інсталятор ніколи не переводить сервер на старіший випуск.

  ```sh
  curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update
  ```

- **Видалення**: `sudo sh /opt/oleafly-server/install.sh uninstall` зупиняє контейнери та видаляє їх. Ваші дані й `.env` залишаться, якщо ви не введете `delete`, коли він запитає. Їхнє видалення вилучає кожен спільний проєкт на сервері, кожен обліковий запис і журнал безпеки. Власні копії проєктів лишаються на комп’ютерах людей.

Якщо інсталятор зупиняється з проблемою, яку ви не можете виправити, [повідомте про неї](https://github.com/Oleafly/oleafly-server/issues/new/choose), додавши те, що він вивів.

## Docker Compose вручну

Це налаштування запускає два контейнери. `oleafly-server` — це сервер, і дістатися його можуть лише інші контейнери. `caddy` отримує сертифікат від Let's Encrypt, обслуговує HTTPS на портах 80 і 443 і передає запити серверу, зокрема з’єднання в реальному часі.

1. Установіть Docker Engine і плагін Compose за [інструкціями Docker](https://docs.docker.com/engine/install/).
2. Скеруйте DNS-запис вашого домену на машину. Відкрийте TCP-порти 80 і 443 та UDP-порт 443 у будь-якому брандмауері перед нею. Caddy потрібен порт 80, щоб отримати сертифікат.
3. Створіть теку для сервера, завантажте до неї файли найновішого випуску, перевірте їх і створіть файл налаштувань:

   ```sh
   sudo mkdir -p /opt/oleafly-server && cd /opt/oleafly-server
   base=https://github.com/Oleafly/oleafly-server/releases/latest/download
   for f in docker-compose.yml Caddyfile env.example litestream.yml SHA256SUMS; do sudo curl -fsSLO "$base/$f"; done
   sha256sum --check --ignore-missing SHA256SUMS
   sudo install -m 600 env.example .env
   ```

4. Відредагуйте `.env` командою `sudoedit .env`. Задайте в `OLEAFLY_DOMAIN` ваш домен без `https://`, задайте `OLEAFLY_SERVER_NAME` і заповніть щонайменше один [спосіб входу](/docs/collaboration/server-access/#sign-in-providers). Рядки способів, якими не користуєтесь, залиште порожніми. Беріть значення в одинарні лапки, якщо воно містить `$` або `#`.
5. Запустіть. Перший запуск завантажує образ сервера `ghcr.io/oleafly/oleafly-server` у версії випуску.

   ```sh
   sudo docker compose up -d
   ```

6. Перевірте, що він відповідає. Ця команда виведе `200`:

   ```sh
   curl -sS -o /dev/null -w '%{http_code}\n' https://collab.example.org/healthz
   ```

7. [Станьте першим адміністратором](#become-the-first-admin). Код налаштування є в журналі:

   ```sh
   sudo docker compose logs oleafly-server | grep 'Setup code'
   ```

Ваші дані зберігаються в томі Docker `oleafly-server_oleafly-data`. Caddy зберігає свої сертифікати в `oleafly-server_caddy-data`.

Docker сам відкриває порти 80 і 443, навіть коли ввімкнено брандмауер хоста, як-от `ufw`. Саме це й потрібно Caddy. Не додавайте запис `ports:` до служби `oleafly-server`. Щоб дістатися сервера з самої машини, опублікуйте його як `127.0.0.1:8080:8080`, щоб він не виходив у мережу.

Якщо ви зміните `Caddyfile`, виконайте `sudo docker compose up -d --force-recreate caddy`. Щоб оновитися пізніше, завантажте файли нового випуску так само і знову виконайте `sudo docker compose up -d`.

### Тримайте секрети поза .env

Сім параметрів можуть містити секрети: `OLEAFLY_SETUP_CODE`, `OLEAFLY_GITHUB_CLIENT_SECRET`, `OLEAFLY_OIDC_<NAME>_CLIENT_SECRET`, `OLEAFLY_SMTP_URL`, `OLEAFLY_BLOB_STORE`, `OLEAFLY_S3_ACCESS_KEY_ID` і `OLEAFLY_S3_SECRET_ACCESS_KEY`. Кожен має також версію `_FILE`, що вказує на файл зі значенням. Задавайте щось одне з двох, не обидва.

Наприклад, щоб передати секретний ключ клієнта GitHub як Docker secret, збережіть його в `secrets/github_client_secret` поруч із `docker-compose.yml`, дозвольте користувачеві сервера (ID 10001) читати його та видаліть рядок `OLEAFLY_GITHUB_CLIENT_SECRET` із `.env`:

```sh
sudo chown 10001:10001 secrets/github_client_secret
sudo chmod 400 secrets/github_client_secret
```

Потім створіть `docker-compose.override.yml` поруч із `docker-compose.yml`. Compose читає його автоматично, а інсталятор не чіпає його, коли оновлює інші файли.

```yaml
services:
  oleafly-server:
    environment:
      OLEAFLY_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github_client_secret
    secrets:
      - github_client_secret

secrets:
  github_client_secret:
    file: ./secrets/github_client_secret
```

Знову виконайте `sudo docker compose up -d`.

## Coolify

Coolify ставить власний проксі перед сервером і отримує сертифікат, тож у цьому налаштуванні Caddy немає. Coolify може зібрати сервер із репозиторію Oleafly або запустити [опублікований образ](#deploy-the-published-image), що пропускає збирання.

Перед початком скеруйте DNS-запис вашого домену, як-от `collab.example.org`, на сервер Coolify. Потім створіть застосунок GitHub OAuth, як описано в розділі [GitHub](/docs/collaboration/server-access/#github), з адресою зворотного виклику `https://collab.example.org/auth/callback/github`. Тримайте під рукою його ідентифікатор клієнта та секретний ключ.

### Збирання з репозиторію

1. У своєму проєкті Coolify виберіть **+ New**, потім **Public Repository** і введіть `https://github.com/Oleafly/Oleafly`. Залишіть гілку `main`.
2. Для **Build Pack** виберіть **Docker Compose**, **Base Directory** задайте `/`, а **Docker Compose Location** — `/deploy/server/docker-compose.coolify.yml`, потім виберіть **Continue**.
3. У розділі **Advanced › Build** для **Build arguments** виберіть **Managed manually in Dockerfile**. Образу сервера не потрібні аргументи збирання. Якщо лишити автоматично, Coolify записує кожну змінну, зокрема секрети, в історію збирання образу.
4. У розділі **General** задайте домен `oleafly-server` як `https://collab.example.org:8080` і збережіть. `:8080` повідомляє проксі Coolify, на якому порту сервер очікує з’єднань. Люди як і раніше під’єднуються на звичайному порті HTTPS, а Coolify сам задає в `OLEAFLY_PUBLIC_URL` значення `https://collab.example.org`.
5. У розділі **Environment Variables** заповніть `OLEAFLY_SERVER_NAME`, яку Coolify позначає як обов’язкову, а потім `OLEAFLY_GITHUB_CLIENT_ID` і `OLEAFLY_GITHUB_CLIENT_SECRET`. Змінні, якими не користуєтесь, залиште порожніми.
6. Виберіть **Deploy**. Перше збирання компілює сервер і триває кілька хвилин. Коли воно завершиться, Coolify покаже ресурс як запущений і справний.
7. Відкрийте `https://collab.example.org/healthz` у браузері. Він покаже `{"status":"ok"}`.
8. Відкрийте **Logs**, виберіть контейнер `oleafly-server` і скопіюйте код із найновішого рядка, що починається з `Setup code:`.
9. [Станьте першим адміністратором](#become-the-first-admin) із цим кодом.

Якщо сервер не запускається, його журнал називає параметр, який він не може використати. Якщо там сказано, що `OLEAFLY_PUBLIC_URL` не задано, пропущено крок 4. Домен, що починається з `http://`, відхиляється, бо серверу потрібен HTTPS.

Якщо перед Coolify стоїть Cloudflare, бо ваш DNS-запис проходить через проксі Cloudflare або тунель веде до проксі Coolify, задайте для `OLEAFLY_PROXY_HOPS` значення `2`. Без цього журнал безпеки показує адресу проксі для всіх, і всі ділять одне обмеження входу.

У файлі Coolify передбачено місце для GitHub і одного провайдера OpenID Connect з іменем `UNIVERSITY`. Задайте в `OLEAFLY_OIDC_UNIVERSITY_LABEL` текст, який мають бачити люди, наприклад `GitLab`. Його адреса зворотного виклику закінчується на `/auth/callback/university`. Щоб додати більше провайдерів, розгорніть сервер із форка з власною копією цього файлу.

Дані зберігаються в томі Docker, чиє ім’я закінчується на `oleafly-data`. Знайдіть його командою `docker volume ls --filter name=oleafly-data`. В образі немає оболонки, тож **Terminal** Coolify не може відкрити її в контейнері сервера. Журнали та перевірка стану працюють як завжди.

### Розгортання опублікованого образу

Запуск опублікованого образу пропускає збирання, що пасує невеликому серверу Coolify. Виконайте кроки вище з двома змінами. У кроці 2 задайте для **Docker Compose Location** значення `/deploy/server/docker-compose.coolify-image.yml`. Пропустіть крок 3, бо нічого не збирається. Файл іде за однією серією випусків, тож кожен **Redeploy** підтягує найновіший випуск у ній.

## Render

[Deploy to Render](https://render.com/deploy?repo=https://github.com/Oleafly/Oleafly) читає Blueprint у репозиторії Oleafly. Він створює одну веб-службу з опублікованого образу, з диском на 1 ГБ для теки з даними. Render прикріплює диски лише до платних типів інстансів, тож служба стартує на найменшому з них, у регіоні Render Oregon. Для іншого регіону розгорніть із форка, задавши `region` у `render.yaml`.

1. Відкрийте посилання та увійдіть у Render.
2. Render запитує `OLEAFLY_SERVER_NAME`, а також ідентифікатор клієнта та секретний ключ GitHub. Заповніть назву, а поля GitHub поки залиште порожніми. Їхня адреса зворотного виклику залежить від адреси служби, якої у вас ще немає.
3. Виберіть **Deploy Blueprint**. Коли служба запрацює, її сторінка покаже її адресу, як-от `https://oleafly-server.onrender.com`. Blueprint записує в `OLEAFLY_PUBLIC_URL` цю адресу.
4. Створіть застосунок GitHub OAuth, як описано в розділі [GitHub](/docs/collaboration/server-access/#github), із адресою зворотного виклику: ця адреса, а після неї `/auth/callback/github`. Додайте ідентифікатор клієнта та секретний ключ у розділі **Environment** служби. Render перезапустить сервер із ними.
5. Знайдіть найновіший рядок `Setup code:` у **Logs** служби та [станьте першим адміністратором](#become-the-first-admin).

Якщо ви даєте службі власний домен, задайте для `OLEAFLY_PUBLIC_URL` його значення в розділі **Environment** і відповідно змініть адресу зворотного виклику на GitHub.

Через диск Render зупиняє запущений сервер перед запуском нового, тож кожне розгортання забирає сервер на кілька секунд. Oleafly перепід’єднується сам.

## Railway

Railway запускає опублікований образ, із томом для теки з даними.

1. У проєкті Railway виберіть **+ New**, потім **Docker Image** і введіть `ghcr.io/oleafly/oleafly-server:latest`. Щоб самим обирати час оновлення, використайте натомість власний тег випуску зі [сторінки випусків](https://github.com/Oleafly/Oleafly/releases). Railway може одразу розпочати перше розгортання. Воно зупиниться з `OLEAFLY_PUBLIC_URL is not set`, і на цьому етапі це очікувано.
2. Відкрийте службу. У розділі **Settings › Networking** виберіть **Generate Domain** і введіть порт `8080`. Railway покаже адресу, як-от `oleafly-server-production.up.railway.app`.
3. У розділі **Settings › Deploy** для **Healthcheck Path** задайте значення `/readyz`.
4. Клацніть правою кнопкою на полотні проєкту, додайте том, прикріпіть його до служби сервера та задайте для нього шлях монтування `/data`.
5. У розділі **Variables** відкрийте **Raw Editor** і вставте ці рядки зі своєю назвою сервера. Для значень GitHub дотримуйтеся розділу [GitHub](/docs/collaboration/server-access/#github). Адреса зворотного виклику — це ваша адреса з кроку 2 з `https://` на початку та `/auth/callback/github` після неї.

   ```ini
   OLEAFLY_PUBLIC_URL=https://${{RAILWAY_PUBLIC_DOMAIN}}
   OLEAFLY_BIND=0.0.0.0:8080
   OLEAFLY_DATA_DIR=/data
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   PORT=8080
   RAILWAY_RUN_UID=0
   ```

   Railway монтує томи від імені root. `RAILWAY_RUN_UID=0` запускає сервер від root, щоб він міг писати в том.

6. Розгорніть зміни. Знайдіть найновіший рядок `Setup code:` у **Deploy Logs** служби та [станьте першим адміністратором](#become-the-first-admin).

## Linux без Docker

На машині без Docker сервер працює як окрема програма під systemd, з Caddy попереду для HTTPS.

### Завантаження сервера

Кожен випуск сервера на [сторінці випусків](https://github.com/Oleafly/Oleafly/releases) має готову зібрану програму для x86-64 та для ARM і файл `SHA256SUMS` для перевірки. Програмі більше нічого встановлювати не потрібно.

Завантажте в одну теку архів для вашої машини, що закінчується на `x86_64-unknown-linux-musl.tar.gz` або `aarch64-unknown-linux-musl.tar.gz`, і `SHA256SUMS`. Потім перевірте та встановіть його. На машині з ARM використовуйте `aarch64` замість `x86_64`:

```sh
sha256sum --check --ignore-missing SHA256SUMS
tar -xzf oleafly-server-*-x86_64-unknown-linux-musl.tar.gz
sudo install -m 0755 oleafly-server-*-x86_64-unknown-linux-musl/oleafly-server /usr/local/bin/oleafly-server
oleafly-server --version
```

Із встановленим GitHub CLI команда `gh attestation verify oleafly-server-*-x86_64-unknown-linux-musl.tar.gz --repo Oleafly/Oleafly` додатково підтверджує, що GitHub зібрав архів із репозиторію Oleafly. Архів містить юніт systemd `oleafly-server.service`.

Щоб натомість зібрати програму самостійно, виконайте цю команду з клону репозиторію Oleafly на будь-якому комп’ютері з Docker. Для сервера з ARM використовуйте `--platform linux/arm64`.

```sh
docker buildx build --platform linux/amd64 --target binary --output type=local,dest=dist -f crates/oleafly-server/Dockerfile .
```

Це запише `dist/oleafly-server`. Скопіюйте його на сервер до `/usr/local/bin/oleafly-server` і зробіть виконуваним.

### Запуск під systemd

1. Створіть файл налаштувань. Читати його може лише root:

   ```sh
   sudo install -d -m 0755 /etc/oleafly-server
   sudo install -m 0600 /dev/null /etc/oleafly-server/oleafly-server.env
   sudoedit /etc/oleafly-server/oleafly-server.env
   ```

   Розміщуйте один параметр на рядок. `OLEAFLY_BIND=127.0.0.1:8080` тримає сервер поза мережею, щоб до нього міг дістатися лише Caddy. Не задавайте `OLEAFLY_DATA_DIR`, бо його задає юніт.

   ```ini
   OLEAFLY_PUBLIC_URL=https://collab.example.org
   OLEAFLY_BIND=127.0.0.1:8080
   OLEAFLY_BEHIND_PROXY=true
   OLEAFLY_SERVER_NAME=Smith Lab
   OLEAFLY_GITHUB_CLIENT_ID=Ov23liExampleClientId
   OLEAFLY_GITHUB_CLIENT_SECRET=example-client-secret
   ```

2. Установіть і запустіть юніт із розпакованого архіву або з теки `deploy/server` у клоні репозиторію. Потім знайдіть код налаштування:

   ```sh
   sudo install -m 0644 oleafly-server.service /etc/systemd/system/oleafly-server.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now oleafly-server
   sudo journalctl -u oleafly-server | grep 'Setup code'
   ```

Юніт запускає сервер від імені користувача, якого systemd створює для нього, з доступом до решти системи лише для читання. Єдине місце, куди він може писати, — це `/var/lib/oleafly-server`, де він зберігає свої дані. На диску ця тека має шлях `/var/lib/private/oleafly-server`.

Щоб тримати секретний ключ клієнта поза файлом налаштувань, використайте credential systemd. Збережіть секрет у `/etc/oleafly-server/github-client-secret` із правами 600, видаліть рядок `OLEAFLY_GITHUB_CLIENT_SECRET` із файла налаштувань, виконайте `sudo systemctl edit oleafly-server` і додайте:

```ini
[Service]
LoadCredential=github-client-secret:/etc/oleafly-server/github-client-secret
Environment=OLEAFLY_GITHUB_CLIENT_SECRET_FILE=%d/github-client-secret
```

Потім виконайте `sudo systemctl restart oleafly-server`.

### HTTPS попереду

Установіть Caddy за [інструкціями для вашого дистрибутива](https://caddyserver.com/docs/install). Замініть `/etc/caddy/Caddyfile` цими рядками та виконайте `sudo systemctl reload caddy`. Caddy отримає сертифікат і пропускатиме з’єднання в реальному часі.

```
collab.example.org {
	reverse_proxy 127.0.0.1:8080
}
```

Для nginx чи Apache, або веб-сервера, який ваш університет уже використовує, прочитайте розділ [За зворотним проксі](/docs/collaboration/server-operations/#behind-a-reverse-proxy).

## Без публічної адреси

Якщо машина не має публічної адреси, наприклад це комп’ютер у вашій лабораторії за університетським брандмауером, Cloudflare Tunnel може зробити її доступною. Вам потрібен обліковий запис Cloudflare, до якого додано ваш домен. Cloudflare обслуговує HTTPS для цього імені хоста, тож запити розшифровуються в мережі Cloudflare, перш ніж дістатися вашої машини. Зарахуйте Cloudflare до сторін, які можуть читати трафік до вашого сервера.

1. Виконайте кроки з розділу [Docker Compose вручну](#docker-compose-by-hand) до редагування `.env`. Задайте в `OLEAFLY_DOMAIN` ім’я хоста, яким ви користуватиметесь, як-от `collab.example.org`. Інсталятор однією командою тут не підходить, бо він запускає Caddy.
2. Запустіть лише сервер. Caddy тут не потрібен:

   ```sh
   sudo docker compose up -d oleafly-server
   ```

3. На панелі Cloudflare перейдіть до **Networking › Tunnels**, виберіть **Create Tunnel**, дайте йому ім’я та знову виберіть **Create Tunnel**. Скопіюйте токен із показаної команди встановлення.
4. Запустіть тунель поруч із сервером. Команда `read` чекає, доки ви вставите токен, і не показує його:

   ```sh
   read -rs TUNNEL_TOKEN && export TUNNEL_TOKEN
   sudo --preserve-env=TUNNEL_TOKEN docker run -d --name oleafly-tunnel --restart unless-stopped --network oleafly-server_default -e TUNNEL_TOKEN cloudflare/cloudflared:2026.10.0 tunnel --no-autoupdate run
   ```

5. Повернувшись на панель, відкрийте тунель. У розділі **Routes** виберіть **Add route**, потім **Published application**. У полі **Hostname** введіть піддомен і виберіть ваш домен. Для **Service URL** задайте значення `http://oleafly-server:8080` і виберіть **Add route**.
6. Перевірте, що сервер відповідає на `https://collab.example.org/healthz`, потім [станьте першим адміністратором](#become-the-first-admin).

На машині без Docker установіть `cloudflared` із [репозиторію пакунків Cloudflare](https://pkg.cloudflare.com/), виконайте `sudo cloudflared service install`, а після нього — токен, і задайте для **Service URL** значення `http://127.0.0.1:8080`.

Cloudflare пропускає з’єднання в реальному часі та ставить адресу відвідувача в `X-Forwarded-For` останньою, тож лишайте `OLEAFLY_BEHIND_PROXY=true`. Якщо тунель веде до іншого проксі, як-от проксі Coolify, а не безпосередньо до сервера, також задайте `OLEAFLY_PROXY_HOPS=2`. Cloudflare відхиляє запити більші за 100 МБ у планах Free і Pro, тож задайте для `OLEAFLY_MAX_PROJECT_MB` значення 100 або менше, інакше завантаження великих проєктів провалиться. Не ставте Cloudflare Access перед сервером, бо Oleafly не може обійти його сторінку входу.

Коли пізніше оновлюватимете сервер, завантажте файли нового випуску та вкажіть службу, щоб Caddy не запускався: `sudo docker compose up -d oleafly-server`.

## Станьте першим адміністратором

На новому сервері немає адміністратора. Поки хтось не завершить налаштування, сервер щоразу під час запуску створює новий одноразовий код налаштування і записує його у свій журнал.

1. Знайдіть у журналі найновіший рядок, що починається з `Setup code:`:
   - Встановлення однією командою: інсталятор виводить його після завершення. Щоб побачити його знову, виконайте `cd /opt/oleafly-server && sudo docker compose logs oleafly-server | grep 'Setup code'`
   - Docker Compose вручну: `sudo docker compose logs oleafly-server | grep 'Setup code'` у теці сервера
   - Coolify: журнали служби `oleafly-server`
   - systemd: `sudo journalctl -u oleafly-server | grep 'Setup code'`
2. В Oleafly відкрийте **Налаштування → Співпраця**, виберіть **Додати сервер** і введіть адресу вашого сервера. Oleafly побачить, що сервер потребує налаштування, і запитає **Код налаштування**.
3. Введіть код і увійдіть будь-яким налаштованим способом входу. Ви стаєте адміністратором сервера, а код перестає діяти.

Будь-хто, у кого є код, доки ви його не використали, може зробити себе адміністратором, тож вставляйте його лише в Oleafly.

Ви можете також обрати код самостійно за допомогою `OLEAFLY_SETUP_CODE`: щонайменше 12 літер або цифр, за бажанням з дефісами чи пробілами. Тоді сервер ніколи не виводить його. У журналі буде лише `Setup code: set by OLEAFLY_SETUP_CODE`, а ви вводите значення, яке задали. Приберіть його з налаштувань, щойно налаштування буде завершено.

Далі додайте людей. У розділі [Вхід і доступ](/docs/collaboration/server-access/#access-rules) пояснено, як це зробити.

## Перевірка сервера

- При встановленні однією командою `sudo sh /opt/oleafly-server/install.sh status` перевіряє контейнери й HTTPS за один раз.
- `https://collab.example.org/healthz` відповідає `200`, доки працює процес сервера.
- `/readyz` відповідає `200`, лише доки сервер може писати у свою базу даних і теку з даними. Коли не може, наприклад заповнився диск, він відповідає `503` і називає, що відмовило: `database` або `storage`.
- Образ Docker сам перевіряє `/readyz`, тож `docker ps` і Coolify показують сервер як unhealthy, а не як запущений, який нічого не може зберегти.
- У Oleafly **Перевірити з’єднання** у **Налаштування → Співпраця** перевіряє адресу, HTTPS, версію, з’єднання в реальному часі, варіанти входу та годинник сервера. **Перевірки з’єднання** в [консолі адміністратора](/docs/collaboration/server-access/#admin-console) виконують ті самі перевірки.
