Запуск сервера
Сховище, резервні копії та обмеження
Усі налаштування Oleafly Server, зберігання файлів на диску або в бакеті S3, скомпільовані PDF, робота за проксі, обмеження для класів в одній мережі та для кожного облікового запису, журнали, резервні копії, відновлення та оновлення.
Ця сторінка описує щоденну роботу з Oleafly Server. Щоб його встановити, почніть зі сторінки Запуск сервера співпраці.
Налаштування
Розділ «Налаштування»Сервер читає свої налаштування зі змінних середовища. Змінна, що задана, але порожня, вважається незаданою. Якщо налаштування бракує або воно неправильне, сервер не запускається, а його журнал називає його.
| Змінна | Що робить | Типове значення |
|---|---|---|
OLEAFLY_PUBLIC_URL | HTTPS-адреса, яку люди вводять в Oleafly. Вона може містити шлях, наприклад https://www.cs.example.edu/oleafly. Обов’язкова. Файли Compose і Coolify задають її за вас. | Немає |
OLEAFLY_BIND | Адреса і порт, на яких сервер очікує з’єднання. | 0.0.0.0:8080 |
OLEAFLY_DATA_DIR | Тека для бази даних і збережених файлів. | /data |
OLEAFLY_SERVER_NAME | Назва, яку люди бачать в Oleafly, наприклад Smith Lab. | Oleafly Server |
OLEAFLY_SERVER_ICON_URL | HTTPS-адреса квадратного зображення, показаного поруч із назвою. | Немає |
OLEAFLY_SETUP_CODE | Ваш власний одноразовий код налаштування: щонайменше 12 букв або цифр, за бажанням з дефісами чи пробілами. Без нього сервер створює код сам. | Створюється автоматично |
OLEAFLY_GITHUB_CLIENT_ID, OLEAFLY_GITHUB_CLIENT_SECRET | Увімикають вхід через GitHub. | Вимкнено |
OLEAFLY_GITHUB_URL | Адреса GitHub Enterprise Server. | https://github.com |
OLEAFLY_GITHUB_API_URL | Адреса API GitHub, якщо ваша незвичайна. | https://api.github.com, або /api/v3 під OLEAFLY_GITHUB_URL |
OLEAFLY_GITHUB_LABEL | Текст на кнопці входу через GitHub. | GitHub |
OLEAFLY_OIDC_<NAME>_ISSUER, OLEAFLY_OIDC_<NAME>_CLIENT_ID, OLEAFLY_OIDC_<NAME>_CLIENT_SECRET | Увімикають провайдер OpenID Connect з назвою <NAME>. | Вимкнено |
OLEAFLY_OIDC_<NAME>_LABEL | Текст на його кнопці входу, наприклад University login. | <NAME> |
OLEAFLY_OIDC_<NAME>_TRUST_EMAIL | Вважати кожну адресу електронної пошти від цього провайдера підтвердженою. Спершу прочитайте Підтверджені адреси електронної пошти. | false |
OLEAFLY_SMTP_URL, OLEAFLY_MAIL_FROM | Електронна пошта. Прочитайте Електронна пошта. | Вимкнено |
OLEAFLY_OPEN_SIGNUP | Давати кожному, хто входить через один із ваших провайдерів, обліковий запис учасника. Прочитайте Відкрита реєстрація. | false |
OLEAFLY_WEB | Увімикає доступ через браузер. Прочитайте Доступ через браузер. | false |
OLEAFLY_BLOB_STORE | Місце зберігання файлів, як-от рисунків і PDF. fs зберігає їх у OLEAFLY_DATA_DIR. Адреса на кшталт s3://lab-bucket або s3://lab-bucket/oleafly зберігає їх у бакеті. | fs |
OLEAFLY_S3_ENDPOINT | Адреса сховища, сумісного з S3, іншого ніж Amazon S3, наприклад MinIO або Cloudflare R2. Для Amazon S3 залиште її порожньою. | Amazon S3 |
OLEAFLY_S3_REGION | Регіон бакета. | us-east-1 |
OLEAFLY_S3_ACCESS_KEY_ID, OLEAFLY_S3_SECRET_ACCESS_KEY | Ключ, яким сервер користується для бакета. Обов’язкові з адресою s3://. | Немає |
OLEAFLY_MAX_PROJECT_MB | Найбільший проєкт, який сервер приймає, у мегабайтах. | 200 |
OLEAFLY_MAX_FILE_MB | Найбільший один файл, у мегабайтах. | 50 |
OLEAFLY_MAX_MEMBERS_PER_PROJECT | Найбільше людей в одному проєкті. | 20 |
OLEAFLY_ACCOUNT_STORAGE_MB | Найбільший обсяг, який можуть зберігати проєкти, що належать одному обліковому запису, у мегабайтах. Прочитайте Обмеження для облікового запису. | Без обмеження, або 100 з відкритою реєстрацією |
OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | Найбільше спільних проєктів, якими може володіти один обліковий запис. | Без обмеження, або 50 з відкритою реєстрацією |
OLEAFLY_UPLOADS_PER_HOUR | Скільки вивантажень файлів і знімків може зробити один обліковий запис за годину. | Без обмеження, або 300 з відкритою реєстрацією |
OLEAFLY_SIGN_IN_BURST | Скільки запитів на вхід може зробити одна мережева адреса сплеском. Один вхід забирає приблизно шість, тож типове значення вистачає на 50 людей з однієї адреси, що входять одночасно. | 300 |
OLEAFLY_SIGN_IN_PER_MINUTE | Скільки запитів на вхід отримує одна мережева адреса щохвилини після сплеску. | 120 |
OLEAFLY_EMAIL_LINKS_PER_IP | Скільки листів для входу сервер надсилає людям з однієї мережевої адреси за 15 хвилин. | 100 |
OLEAFLY_EMAIL_LINKS_PER_ADDRESS | Скільки листів для входу може отримати одна адреса електронної пошти за 15 хвилин. Не може бути більше ніж OLEAFLY_EMAIL_LINKS_PER_IP. | 3 |
OLEAFLY_DEVICE_CODES_PER_IP | Скільки кодів входу можуть запросити люди з однієї мережевої адреси за 10 хвилин. | 100 |
OLEAFLY_SNAPSHOT_MEMORY_MB | Скільки пам’яті в мегабайтах сервер може використовувати для побудови знімків проєктів. | Половина ліміту пам’яті контейнера або 1024 без ліміту |
OLEAFLY_BEHIND_PROXY | Брати адресу кожної людини із заголовка X-Forwarded-For, який додає ваш проксі. Файли Compose, Coolify і Render увімкують це. | false |
OLEAFLY_PROXY_HOPS | Скільки проксі проходить кожен запит, перш ніж дістається сервера. Потребує OLEAFLY_BEHIND_PROXY=true. | 1 |
OLEAFLY_LOG_LEVEL | Скільки сервер пише в журнал: error, warn, info, debug або trace. Бібліотеки, якими користується сервер, пишуть лише попередження, якщо ви не виберете debug або trace. | info |
OLEAFLY_SECURITY_LOG_DAYS | Скільки днів зберігати записи журналу безпеки, записи журналів доступу до проєктів і виконані чи прострочені запрошення гостей. | 365 |
OLEAFLY_ARCHIVE_DAYS | Скільки днів зберігати проєкт після того, як його власник припиняє спільний доступ. | 30 |
OLEAFLY_POLL_HOLD_SECONDS | Скільки секунд сервер тримає відкритим запит довгого опитування, коли правок у черзі немає: від 1 до 40 секунд. Тримайте це на кілька секунд меншим за тайм-аут простою будь-якого проксі перед сервером. | 25 |
У Compose-файлі .env беріть значення в одинарні лапки, якщо воно містить $ або #. Налаштування з таємницями можна також читати з файлів. Прочитайте Таємниці поза .env.
Сховище
Розділ «Сховище»Типово сервер зберігає все в OLEAFLY_DATA_DIR: базу даних, файли, якими люди діляться, і знімки проєктів. Знімки — це збережені копії кожного проєкту, завдяки яким люди приєднуються і швидко дотягуються до актуального стану.
Файли в бакеті
Розділ «Файли в бакеті»Натомість сервер може зберігати файли й знімки в Amazon S3 або в іншому сховищі з API, сумісним із S3, як-от MinIO або Cloudflare R2. Так чи інакше база даних лишається в OLEAFLY_DATA_DIR, тож сервер усе одно потребує своєї теки даних.
-
Створіть бакет і заблокуйте до нього публічний доступ.
-
Створіть ключ, який може читати, записувати й видаляти об’єкти в цьому бакеті й нічого більше. На Amazon S3 це
s3:GetObject,s3:PutObjectіs3:DeleteObjectдляarn:aws:s3:::lab-bucket/*або дляarn:aws:s3:::lab-bucket/oleafly/*, якщо ви користуєтеся текою. -
Задайте змінні, наприклад у
.env:Вікно термінала OLEAFLY_BLOB_STORE=s3://lab-bucket/oleaflyOLEAFLY_S3_REGION=eu-west-1OLEAFLY_S3_ACCESS_KEY_ID=your-access-key-idOLEAFLY_S3_SECRET_ACCESS_KEY=your-secret-access-key
Для сховища, відмінного від Amazon S3, також задайте OLEAFLY_S3_ENDPOINT його адресою, наприклад https://minio.example.org:9000 або https://<account-id>.r2.cloudflarestorage.com, і задайте OLEAFLY_S3_REGION регіоном, якого воно очікує (auto для R2). Звичайний http:// теж працює, але користуйтеся ним, лише коли сховище перебуває в тій самій приватній мережі, що й сервер.
Частина після назви бакета — це необов’язкова тека. Кожен файл має назву за своїм хешем SHA-256 і лежить під першими двома символами цього хешу, тож файл, чий хеш починається з 3f9a, зберігається як oleafly/3f/3f9a.... У знімків є власна тека snapshots з окремою текою для кожного проєкту. Коли сервер зчитує файл або знімок назад, він звіряє байти з хешем і відкидає той, що не збігається. Без бакета так само все розкладено в теці blobs всередині OLEAFLY_DATA_DIR.
Якщо бакет відмовляє запиту, це завантаження або звантаження не вдається, і журнал сервера показує, що сказав бакет, наприклад 403 Forbidden (AccessDenied). Помилка сервера, тайм-аут або обірване з’єднання — це інше: сервер пробує до трьох разів із короткою випадковою паузою між ними. Якщо об’єкт не вдається видалити, сервер про це записує і пробує знову на кожному проході обслуговування, кожні 6 годин, тож збій не лишає по собі об’єктів.
Знімки й пам’ять
Розділ «Знімки й пам’ять»Коли проєкт отримує спільний доступ, застосунок власника вивантажує його перший знімок і підписує його ключем цього пристрою. Відтоді сервер будує кожен знімок сам — з попереднього знімка та змін, які люди надіслали відтоді. Новий знімок будується, щойно в проєкту накопичиться 1,000 змін після останнього. Сервер завжди зберігає щонайменше останні 2,000 змін, тож пристрій, який ненадовго зник, дотягується з них і не звантажує весь проєкт знову.
Побудова знімка потребує приблизно вдесятеро більше за розмір попереднього знімка плюс зміни відтоді. Сервер розпочинає лише ту побудову, що вміщується в OLEAFLY_SNAPSHOT_MEMORY_MB, а побудови, що йдуть одночасно, ділять цей обсяг між собою. Якщо побудова не вміщується, сервер пропускає її, записує в журнал, скільки пам’яті їй потрібно, і зберігає всі зміни проєкту. Пристрої тоді дотягуються з цих змін по кілька мегабайтів за раз. Підніміть налаштування — і наступний знімок буде побудовано. Сервер не зберігає знімок, більший за OLEAFLY_MAX_PROJECT_MB.
Скомпільовані PDF
Розділ «Скомпільовані PDF»Коли власник або редактор успішно компілює спільний проєкт, його застосунок надсилає PDF на сервер разом із файлом SyncTeX, якщо він є. Для кожного проєкту застосунок надсилає щонайбільше один PDF на хвилину. Сервер зберігає по одному PDF і одному файлу SyncTeX на проєкт, із назвою головного файла, а також тим, хто й коли його скомпілював. Доступ через браузер показує цей PDF людям у проєкті.
Кожне вивантаження замінює попереднє, а старий файл видаляється, щойно його ніщо не використовує. Скомпільовані файли зберігаються разом з іншими файлами, на диску або в бакеті, і видаляються разом зі своїм проєктом. Скомпільований файл може мати розмір до OLEAFLY_MAX_FILE_MB. Він зараховується до сховища облікового запису власника, але не до вивантажень на годину.
Кожен учасник проєкту може читати його скомпільовані файли. Замінювати їх можуть лише власники та редактори.
За зворотним проксі
Розділ «За зворотним проксі»Сервер розмовляє звичайним HTTP, тож HTTPS обробляє щось перед ним: Caddy у Compose-налаштуванні, проксі Coolify або вебсервер, який ви вже ведете, наприклад університетський. Що б не стояло попереду, воно мусить:
- приймати запити розміром аж до
OLEAFLY_MAX_PROJECT_MB - додавати адресу клієнта до
X-Forwarded-For
Воно також має пропускати WebSocket-оновлення до /ws і тримати ці з’єднання відкритими щонайменше годину. Редагування в реальному часі користується ними, коли може. Якщо ввімкнено доступ через браузер, воно мусить пропускати їх і до /web/ws, бо браузерний застосунок не має повільнішого запасного варіанта.
Запускайте сервер там, де до нього дістається лише проксі. На тій самій машині задайте OLEAFLY_BIND=127.0.0.1:8080. Потім задайте OLEAFLY_BEHIND_PROXY=true.
Коли з’єднання WebSocket заблоковані
Розділ «Коли з’єднання WebSocket заблоковані»Деякі мережі блокують з’єднання WebSocket — часто це університетська чи корпоративна мережа з фільтрувальним проксі. Редагування в реальному часі там усе одно працює, тільки повільніше. Коли дві спроби WebSocket поспіль зазнають невдачі, а сервер усе ще відповідає по HTTPS, Oleafly переходить на довге опитування по HTTP. Він надсилає правки на /api/v1/projects/<project>/frames і чекає на правки інших людей на /api/v1/projects/<project>/poll, тримаючи кожен запит відкритим до OLEAFLY_POLL_HOLD_SECONDS секунд. Кожна правка все одно прибуває. Oleafly щохвилини пробує WebSocket знову і повертається до нього, щойно один з’єднується.
Перевірити з’єднання в Oleafly і Перевірки з’єднання в консолі адміністратора кажуть, коли це стається: «Зміни в реальному часі йдуть повільнішим шляхом, бо ця мережа блокує звичайний. Вони все одно доходять.»
Якщо ви ведете проксі перед сервером, усе одно пропускайте WebSocket-оновлення. Довге опитування працює, але кожен пакет правок коштує додаткового запиту і трохи більшої затримки.
Деякі проксі закривають запит, який мовчить менш ніж 30 секунд, — nginx із коротким proxy_read_timeout, наприклад. Такі проксі відповідають на запити довгого опитування помилкою 502 або 504, і правки прибувають із запізненням. Задайте OLEAFLY_POLL_HOLD_SECONDS на кілька секунд меншим за цей тайм-аут, наприклад 8 для 10-секундного тайм-ауту.
Що змінює OLEAFLY_BEHIND_PROXY
Розділ «Що змінює OLEAFLY_BEHIND_PROXY»Сервер занотовує адресу клієнта у двох місцях: у журналі безпеки і в обмеженнях на те, як часто одна адреса може починати вхід або відкривати живе з’єднання.
Без цього налаштування сервер користується адресою того, хто до нього під’єднався. За проксі це завжди проксі, тож усі ділять одне обмеження, а журнал безпеки показує лише адресу проксі.
З OLEAFLY_BEHIND_PROXY=true сервер читає заголовок X-Forwarded-For і користується останньою адресою в ньому — тією, яку додав ваш проксі. Якщо заголовка немає або в ньому немає чинної адреси, сервер повертається до адреси того, хто з’єднався. Більше нічого не змінюється. Сервер не бере до уваги X-Forwarded-Proto, X-Forwarded-Host і Forwarded, а кожну адресу, яку роздає, будує з OLEAFLY_PUBLIC_URL.
Увімкніть це, лише коли кожен запит іде через ваш проксі. Якщо люди можуть дістати до сервера й напряму, будь-хто зможе надіслати вигаданий X-Forwarded-For, поставити будь-яку адресу в журнал безпеки й обійти ліміт входу.
З двома проксі поспіль, наприклад Cloudflare перед проксі Coolify, задайте OLEAFLY_PROXY_HOPS=2. Тоді сервер бере другу адресу з кінця. Рахуйте лише ті проксі, які проходить кожен запит. Cloudflare Tunnel, що веде просто до сервера, рахується за один.
Щоб перевірити це число, увійдіть зі свого комп’ютера і відкрийте Журнал безпеки в консолі адміністратора. Найновіший запис має показувати вашу публічну адресу — ту, яку називає сайт на кшталт ifconfig.me. Якщо замість неї показується приватна адреса чи адреса Cloudflare, підніміть OLEAFLY_PROXY_HOPS на одиницю.
Caddy
Розділ «Caddy»Caddy пропускає з’єднання WebSocket і X-Forwarded-For без додаткових налаштувань і сам дістає сертифікат. Повний Caddyfile є в розділі Поставте HTTPS попереду.
nginx
Розділ «nginx»Спершу дістаньте сертифікат для домену, наприклад через certbot. Потім збережіть це як /etc/nginx/conf.d/oleafly.conf і виконайте sudo nginx -t && sudo systemctl reload nginx:
map $http_upgrade $connection_upgrade { default upgrade; '' close;}
server { listen 443 ssl; server_name collab.example.org; ssl_certificate /etc/letsencrypt/live/collab.example.org/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/collab.example.org/privkey.pem;
location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_set_header X-Forwarded-For $remote_addr; proxy_read_timeout 1h; proxy_send_timeout 1h; client_max_body_size 200m; }}client_max_body_size відповідає типовому OLEAFLY_MAX_PROJECT_MB у 200. Якщо піднімете одне, підніміть і друге.
Apache
Розділ «Apache»Потрібен Apache 2.4.47 або новіший, який є в Debian 12 та Ubuntu 22.04 і новіших. Увімкніть модулі:
sudo a2enmod proxy proxy_http sslЗбережіть це як /etc/apache2/sites-available/oleafly.conf, потім виконайте sudo a2ensite oleafly && sudo systemctl reload apache2:
<VirtualHost *:443> ServerName collab.example.org SSLEngine on SSLCertificateFile /etc/letsencrypt/live/collab.example.org/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/collab.example.org/privkey.pem
ProxyPreserveHost On ProxyPass / http://127.0.0.1:8080/ upgrade=websocket timeout=3600 ProxyPassReverse / http://127.0.0.1:8080/</VirtualHost>upgrade=websocket пропускає з’єднання WebSocket, а timeout=3600 тримає їх відкритими годину. Apache сам додає адресу клієнта до X-Forwarded-For.
Під шляхом
Розділ «Під шляхом»Якщо сервер живе під шляхом, включіть цей шлях у OLEAFLY_PUBLIC_URL, наприклад https://www.cs.example.edu/oleafly, і в адреси зворотного виклику, які ви реєструєте у провайдерів входу. Сервер відповідає і з цим шляхом, і без нього, тож ваш проксі може передавати його далі або зрізати. У nginx використайте location /oleafly/ { з тими самими рядками всередині й лишіть proxy_pass http://127.0.0.1:8080; без шляху, щоб nginx передавав шлях далі.
Обмеження для класу в одній мережі
Розділ «Обмеження для класу в одній мережі»Цілий клас часто входить з однієї мережевої адреси, наприклад з університетського NAT. Типові значення задані саме для цього:
- Входи: одна адреса отримує сплеск із 300 запитів на вхід, потім по два на секунду. Один вхід забирає приблизно шість, тож 50 людей можуть увійти одночасно. Змініть це через
OLEAFLY_SIGN_IN_BURSTіOLEAFLY_SIGN_IN_PER_MINUTE. - Листи для входу: 100 на одну мережеву адресу за 15 хвилин і 3 на одну адресу електронної пошти. Змініть це через
OLEAFLY_EMAIL_LINKS_PER_IPіOLEAFLY_EMAIL_LINKS_PER_ADDRESS. - Коди входу: 100 кодів і 10 неправильних кодів з однієї адреси за 10 хвилин. Змініть це через
OLEAFLY_DEVICE_CODES_PER_IP. - Живі з’єднання мають власне, більше обмеження, щоб цілий клас за однією адресою міг перепід’єднатися одразу після перезапуску. Його витрачають лише з’єднання, яким не вдається довести свою сесію: сплеск із 300, потім по десять на секунду. З’єднання, яке доводить свою сесію, рахується натомість на свій пристрій, який може перепід’єднатися 60 разів у сплеску, потім раз на секунду.
Усі адреси IPv6 в одній мережі /64 рахуються за одну адресу. Ці обмеження працюють на кожну людину окремо лише тоді, коли сервер бачить справжню адресу кожного, тож налаштуйте свій проксі як слід.
Сервер пінгує кожне живе з’єднання що 30 секунд. Він закриває з’єднання, яке 90 секунд не відповідає на ці пінги, і те, що перестає читати те, що сервер надсилає.
Обмеження проєктів стосуються всіх: OLEAFLY_MAX_PROJECT_MB на цілий проєкт (типово 200 МБ), OLEAFLY_MAX_FILE_MB на один файл (50 МБ) і OLEAFLY_MAX_MEMBERS_PER_PROJECT на людей в одному проєкті (20). Поточні обмеження показує Огляд у консолі адміністратора.
Обмеження для облікового запису
Розділ «Обмеження для облікового запису»Для кожного облікового запису діють три обмеження. Вони вимкнені, доки ви їх не задасте, якщо тільки не ввімкнено відкриту реєстрацію. Вона вмикає їх із такими типовими значеннями:
| Обмеження | Налаштування | З відкритою реєстрацією |
|---|---|---|
| Сховище для проєктів, якими володіє обліковий запис | OLEAFLY_ACCOUNT_STORAGE_MB | 100 МБ |
| Спільні проєкти, якими володіє обліковий запис | OLEAFLY_MAX_PROJECTS_PER_ACCOUNT | 50 |
| Вивантаження, які обліковий запис робить за годину | OLEAFLY_UPLOADS_PER_HOUR | 300 |
Значення, яке ви задали, завжди переважає типове. Кожне має бути цілим числом, не меншим за 1.
- Сховище підсумовує файли та історію змін кожного проєкту, яким володіє обліковий запис, зокрема архівованих, а також їхні скомпільовані PDF. Знімки не враховуються. Файл, який будь-хто додає до проєкту, зараховується власникові проєкту. Щойно сховище власника заповнене, сервер не приймає нових файлів і скомпільованих PDF для його проєктів, а сам власник не може поділитися ще одним проєктом. Файл залишається на комп’ютері людини, яка його додала. Текст, який набирають люди, і далі синхронізується.
- Спільні проєкти рахує проєкти, якими ділиться обліковий запис, зокрема ті, що ще вивантажуються. Архівовані проєкти не враховуються, тож припинення спільного доступу до одного з них звільняє місце.
- Вивантаження рахує кожне вивантаження файла чи знімка в межах однієї години. Скомпільовані PDF не враховуються. Відхилений файл Oleafly сам надішле пізніше ще раз.
Огляд у консолі адміністратора не показує цих обмежень. Коли ввімкнено відкриту реєстрацію, журнал сервера називає їх щоразу під час запуску.
Журнали
Розділ «Журнали»- Журнал сервера — це те, що показують
docker compose logs oleafly-server, Logs у Coolify абоjournalctl -u oleafly-server.OLEAFLY_LOG_LEVELзадає, скільки в нього сказано. - Журнал безпеки записує входи та відмовлені входи, пристрої, людей, ролі, налаштування, проєкти й гостей, кожен запис з часом і IP-адресою. Адміністратори та супровідники читають його в розділі Журнал безпеки в консолі адміністратора. Записи старші за
OLEAFLY_SECURITY_LOG_DAYSднів видаляються. - Журнали доступу до проєктів записують, хто відкрив проєкт, приєднався до нього або звантажив копію, із назвою пристрою і часом. Власник проєкту вмикає такий журнал, коли ввімкнено Дозволити журнали доступу до проєктів, і читати його може лише цей власник. Застосовується той самий строк зберігання.
Резервні копії
Розділ «Резервні копії»Що потрібно для повної резервної копії, залежить від того, де зберігаються файли:
- Файли на диску (
OLEAFLY_BLOB_STORE=fs, типово): база даних, файли й знімки — усе в теці даних. Робіть резервну копію всієї теки. - Файли в бакеті: тека даних тримає базу даних, а бакет — файли й знімки. Копія бази даних разом із бакетом — це повна резервна копія. Увімкніть версіонування бакета, щоб випадково видалений об’єкт можна було повернути.
Робіть резервні копії регулярно і тримайте їх приватними, адже вони містять усі проєкти. Ваших налаштувань, як-от .env, у теці даних немає, тож тримайте ще й їхню копію.
З Docker сервер на кілька секунд зупиняється, поки ви копіюєте том. Oleafly перепід’єднується сам. Виконайте ці команди в теці сервера — /opt/oleafly-server, якщо ви користувалися установником.
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo docker run --rm -v oleafly-server_oleafly-data:/data:ro -v "$PWD":/backup debian:13.7-slim tar -C /data -czf /backup/oleafly-data-$(date +%F).tar.gz .sudo docker compose start oleafly-serverЗ systemd:
sudo systemctl stop oleafly-serversudo tar -C /var/lib/private/oleafly-server -czf /root/oleafly-data-$(date +%F).tar.gz .sudo systemctl start oleafly-serverСкопіюйте архів на іншу машину.
На Coolify назва тому починається з ID ресурсу. Знайдіть її командою docker volume ls --filter name=oleafly-data, підставте замість oleafly-server_oleafly-data, а сервер зупиняйте й запускайте з панелі Coolify замість docker compose.
Тренування з відновлення
Розділ «Тренування з відновлення»Резервна копія, яку ви жодного разу не відновлювали, — це лише надія. Це тренування запускає другу копію сервера з резервної копії, не чіпає ту, що працює, і перевіряє, що обидві — той самий сервер. Підставте дату власного архіву замість 2026-10-11.
cd /opt/oleafly-serversudo docker volume create oleafly-restore-drillsudo docker run --rm -v oleafly-restore-drill:/data -v "$PWD":/backup:ro debian:13.7-slim tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gzsudo docker run -d --name oleafly-restore-drill -v oleafly-restore-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"sudo docker run --rm --network container:oleafly-restore-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-servercurl -fsS https://collab.example.org/.well-known/oleafly-serverserver_id у двох відповідях мусить збігатися. У тренувальної копії є фіктивний вхід через GitHub, який нікого не впускає, і немає відкритого порта, тож нею ніхто не може скористатися. Вилучіть її, коли закінчите:
sudo docker rm -f oleafly-restore-drillsudo docker volume rm oleafly-restore-drillВідновлення
Розділ «Відновлення»Щоб відновити насправді з Docker Compose, зупиніть сервер, замініть вміст тому архівом і знову запустіть його:
cd /opt/oleafly-serversudo docker compose stop oleafly-serversudo docker run --rm -v oleafly-server_oleafly-data:/data -v "$PWD":/backup:ro debian:13.7-slim sh -c 'find /data -mindepth 1 -delete && tar -C /data -xzf /backup/oleafly-data-2026-10-11.tar.gz'sudo docker compose start oleafly-serverЗ systemd:
sudo systemctl stop oleafly-serversudo find /var/lib/private/oleafly-server -mindepth 1 -deletesudo tar -C /var/lib/private/oleafly-server -xzf /root/oleafly-data-2026-10-11.tar.gzsudo systemctl start oleafly-serverНа відновленому сервері бракує змін, які люди зробили після резервної копії. Кожен застосунок помічає це при перепід’єднанні — чи він лишався відкритим, чи його відкрили пізніше — і знову надсилає власні відсутні зміни. Ніхто не мусить нічого для цього робити. Зміна, що спирається на чужу відсутну зміну, чекає, поки та людина відкриє проєкт, бо лише її застосунок може надіслати її зміни. Попросіть кожного, хто редагував близько часу збою, один раз відкрити проєкт.
Безперервні копії з Litestream
Розділ «Безперервні копії з Litestream»Архів містить лише те, що було на момент його створення. Litestream (відкривається в новій вкладці) копіює кожну зміну в базі даних сервера до бакета, сумісного з S3, приблизно за секунду після того, як вона стається. Compose-файл містить його як необов’язкову службу.
Litestream копіює лише базу даних. Якщо файли в бакеті, бакет уже тримає файли й знімки, тож копія Litestream разом із бакетом може повернути втрачений диск. Якщо файли на диску, далі робіть архіви тому, бо Litestream не копіює теку blobs.
-
Створіть бакет або теку в ньому, якою користується лише Litestream цього сервера. Не діліть його з
OLEAFLY_BLOB_STORE. Дайте Litestream ключ, який може перелічувати бакет і читати, записувати й видаляти об’єкти в ньому. -
Додайте дані до
.env:Вікно термінала LITESTREAM_REPLICA_URL=s3://lab-backups/oleafly-serverLITESTREAM_REGION=eu-west-1LITESTREAM_ACCESS_KEY_ID=your-access-key-idLITESTREAM_SECRET_ACCESS_KEY=your-secret-access-keyCOMPOSE_PROFILES=litestreamДля сховища, відмінного від Amazon S3, також задайте
LITESTREAM_ENDPOINTйого адресою іLITESTREAM_REGIONрегіоном, якого воно очікує (autoдля R2).COMPOSE_PROFILESзмушує кожну командуdocker composeвключати Litestream. -
Запустіть його:
Вікно термінала sudo docker compose up -d -
Перевірте, що базу даних скопійовано. Це надрукує рядок із
snapshot complete:Вікно термінала sudo docker compose logs litestream | grep 'snapshot complete'
Litestream робить повну копію раз на день і тримає тиждень копій та зміни між ними. Розклад задано в litestream.yml.
Тренування з відновлення з Litestream
Розділ «Тренування з відновлення з Litestream»Це тренування відновлює базу даних з бакета в тимчасовий том, запускає на ньому другу копію сервера і перевіряє, що обидві — той самий сервер. Сервер, що працює, не чіпається.
cd /opt/oleafly-serversudo docker run --rm -v oleafly-litestream-drill:/data "$(sudo docker compose images -q oleafly-server)" --versionsudo docker compose run --rm --no-deps -v oleafly-litestream-drill:/restore litestream restore -config /etc/litestream.yml -o /restore/oleafly-server.sqlite3 /data/oleafly-server.sqlite3sudo docker run -d --name oleafly-litestream-drill -v oleafly-litestream-drill:/data -e OLEAFLY_PUBLIC_URL=https://restore-drill.invalid -e OLEAFLY_GITHUB_CLIENT_ID=restore-drill -e OLEAFLY_GITHUB_CLIENT_SECRET=restore-drill "$(sudo docker compose images -q oleafly-server)"sudo docker run --rm --network container:oleafly-litestream-drill curlimages/curl:8.22.0 -fsS --retry 10 --retry-connrefused --retry-delay 1 http://127.0.0.1:8080/.well-known/oleafly-servercurl -fsS https://collab.example.org/.well-known/oleafly-serverПерша команда створює тимчасовий том із власником, який потрібен серверу. server_id у двох останніх відповідях мусить збігатися. Вилучіть копію, коли закінчите:
sudo docker rm -f oleafly-litestream-drillsudo docker volume rm oleafly-litestream-drillВідновлення бази даних з Litestream
Розділ «Відновлення бази даних з Litestream»Коли файл бази даних пошкоджений або зник, а решта теки даних у порядку, зупиніть сервер і Litestream, вилучіть те, що лишилося від бази даних, відновіть її і запустіть знову:
cd /opt/oleafly-serversudo docker compose stop oleafly-server litestreamsudo docker run --rm -v oleafly-server_oleafly-data:/data debian:13.7-slim rm -rf /data/oleafly-server.sqlite3 /data/oleafly-server.sqlite3-wal /data/oleafly-server.sqlite3-shm /data/.oleafly-server.sqlite3-litestreamsudo docker compose run --rm --no-deps litestream restore -config /etc/litestream.yml /data/oleafly-server.sqlite3sudo docker compose up -dПісля втрати диска, коли файли були в бакеті, виконайте команди вище на новому порожньому томі й лишіть ті самі налаштування бакета в .env. Кожен проєкт повертається зі своїми файлами й знімками.
Після втрати диска, коли файли були на диску, відновіть свій найновіший архів і на цьому зупиніться. Не кладіть новішу базу даних з Litestream поверх старішого архіву. База вказувала б на файли й знімки, яких в архіві немає, і такі проєкти не відкривалися б.
Оновлення
Розділ «Оновлення»Спершу зробіть резервну копію. Сервер оновлює свою базу даних при першому запуску нового релізу, тож повернення до старішого релізу означає відновлення копії, зробленої перед оновленням.
- Встановлення однією командою: виконайте
curl -fsSL https://oleafly.com/server/install.sh | sudo sh -s -- update. Воно зберігає.env, дістає файли й образ нового релізу та перезапускає сервер. - Docker Compose власноруч: звантажте файли нового релізу в теку сервера, як описано в Docker Compose власноруч, потім виконайте
sudo docker compose up -d. - Coolify: виберіть Redeploy. З опублікованим образом це підтягує найновіший реліз під тегом образу.
- Render: відкрийте службу і запустіть ручне розгортання, яке знову підтягує образ.
- Railway: розгорніть службу знову з її меню. Railway також може сам оновлювати образ із реєстру GitHub.
- systemd: установіть новий реліз, як описано в Завантаження сервера, потім виконайте
sudo systemctl restart oleafly-server.
Oleafly перевіряє версію сервера при кожному з’єднанні. Якщо застосунок і сервер не можуть працювати разом, Oleafly каже, якому з них потрібне оновлення.