Установка

Установка EduBox Core на сервер Linux

Инструкция для системного администратора: от скачивания до первого входа, резервные копии, обновление и диагностика.

Коротко: скачать и проверить архив (раздел 3) → edubox doctor - что на сервере и как ставить (раздел 4) → edubox install (раздел 5) → edubox setup (раздел 6) → DNS (раздел 7) → HTTPS, на общем сервере - edubox proxy-config (раздел 8) → edubox status (разделы 12, 13).

Что проверено на настоящем сервере

15.11.2026 EduBox установлен на сервер Ubuntu 24.04 (Hetzner), общий с другими проектами: nginx уже занимал порты 80 и 443 (около двадцати сайтов), PostgreSQL 16 самого сервера - порт 127.0.0.1:5432, в Docker работали чужие контейнеры. Проверено:

  • edubox install с базой в контейнере на порту 5433;
  • edubox setup в режиме proxy за существующим nginx (EduBox на 127.0.0.1:8787);
  • служба под systemd со всеми ограничениями песочницы из юнита;
  • edubox backup и edubox restore копии, сделанной на другой машине.

Не проверено на настоящем сервере: режим files (TLS у самого EduBox), режим внешней базы, восстановление службы на втором сервере, срабатывание ежедневного таймера копий.

Команды doctor, proxy-config, внешние проверки status и автоматический выбор портов написаны после этой установки по её итогам - то, что тогда делалось вручную. Они проверены тестами, выводом --dry-run и на macOS (настройки nginx - nginx -t версии 1.29), но на настоящем сервере ещё не запускались.

1. Что получится

Интернет ──► :443 ─┐
                   ├─ edubox serve (служба systemd, пользователь edubox)
Интернет ──► :80 ──┘        │  читает /etc/edubox/edubox.toml
   (или nginx/Caddy,        │  данные в /var/lib/edubox
    который уже стоит)      ▼
              PostgreSQL 17 в контейнере edubox-postgres (только 127.0.0.1, порт 5432
              или первый свободный с 5433) или внешний PostgreSQL по строке подключения

На свободном сервере EduBox сам принимает 80 и 443 (режим files). На общем сервере, где порты уже заняты nginx или другим веб-сервером, EduBox слушает локальный порт за ним (режим proxy) - edubox doctor определяет это сам.

ЧтоГде
Исполняемый файл/usr/local/bin/edubox
Настройки службы (с паролем роли службы, права 0640 root:edubox)/etc/edubox/edubox.toml
Пароль владельца базы (только для команд от root, права 0600 root:root)/etc/edubox/owner.toml
Пароль суперпользователя PostgreSQL в контейнере (0600)/etc/edubox/postgres.env
Шаблоны сайтов/var/lib/edubox/templates
Загруженные файлы/var/lib/edubox/uploads
Резервные копии (по умолчанию, 0700 root)/var/lib/edubox/backups
Служба и ежедневная копия/etc/systemd/system/edubox.service, edubox-backup.service, edubox-backup.timer
Данные PostgreSQLтом Docker edubox-pgdata

В базе две роли:

  • edubox_owner - владелец базы. Ею пользуются только команды, запускаемые от root: edubox migrate, setup, seed, admin create, backup, restore. Её строка подключения migrate_database_url лежит в отдельном файле /etc/edubox/owner.toml (0600 root:root), который служба прочитать не может.
  • edubox_app - роль работающей службы (строка database_url). Может читать и менять строки таблиц, но не может менять схему, удалять таблицы, отключать триггеры журнала действий; в журнал действий может только дописывать.

Служба не применяет миграции сама: если схема базы не совпадает с версией программы, она не запускается и пишет в журнал, что делать (edubox migrate).

Служба не запускается, если пароль владельца доступен ей: когда migrate_database_url записан в /etc/edubox/edubox.toml или задан в переменной окружения EDUBOX_MIGRATE_DATABASE_URL, она отказывается стартовать (см. «Диагностика»). Строке место только в owner.toml.

2. Требования

  • Linux x86_64 или aarch64 с systemd (Ubuntu 22.04+, Debian 12+, Astra Linux SE 1.7+, RHEL/Alma/Rocky 9 и подобные). Программа собрана статически и не зависит от версии glibc.
  • Доступ root (sudo).
  • Для PostgreSQL на этом же сервере: Docker (команда docker и служба docker) и доступ к образу docker.io/library/postgres:17 (или его копия во внутреннем реестре, см. «Диагностика»). Порт 5432 может быть занят другим PostgreSQL - тогда база EduBox получит первый свободный порт с 5433.
  • Либо внешний PostgreSQL 17 и на этом сервере клиентские программы pg_dump/pg_restore версии 17 (пакет postgresql-client-17) - они нужны для резервных копий.
  • Домен для портала, например edu.example.kz, и возможность создать в DNS запись для него и для *.edu.example.kz.
  • Сертификат TLS на edu.example.kz и *.edu.example.kz (wildcard) - на обратном прокси или в файлах на этом сервере (раздел 8). Это могут быть и два разных сертификата.
  • Свободные порты 80 и 443 (если TLS у самого EduBox) или уже работающий веб-сервер (nginx, Caddy, Apache), за которым встанет EduBox.
  • Место на диске: от 10 ГБ для начала; загруженные файлы и копии растут со временем. Копии лучше держать на отдельном диске.

3. Скачивание и проверка

Скачайте архив под архитектуру сервера (uname -m: x86_64 или aarch64) и файл контрольной суммы рядом с ним:

edubox-0.1.0-linux-x86_64.tar.gz
edubox-0.1.0-linux-x86_64.tar.gz.sha256

Проверьте и распакуйте:

sha256sum -c edubox-0.1.0-linux-x86_64.tar.gz.sha256     # должно быть: OK
tar -xzf edubox-0.1.0-linux-x86_64.tar.gz
cd edubox-0.1.0-linux-x86_64
sha256sum -c SHA256SUMS                                   # все файлы: OK
./edubox --version

Внутри: edubox (программа, админка уже внутри), templates/ (шаблоны сайтов), docs/install.md (этот файл), SHA256SUMS.

Контрольную сумму архива сверяйте с той, что получена по отдельному доверенному каналу (не с того же сервера, откуда скачан архив). Подпись выпусков появится позже.

4. Проверка сервера: edubox doctor

Первый шаг на любом сервере - особенно на общем, где уже работают другие сайты:

sudo ./edubox doctor --domain edu.example.kz

Ничего не меняет. Показывает:

  • кто занимает порты 80 и 443 (nginx, apache, caddy, контейнер Docker или неизвестная программа) и порт 127.0.0.1:5432;
  • есть ли и работает ли Docker, есть ли systemd, сколько места там, где будут данные;
  • установлен ли EduBox уже (файл настроек, служба, контейнер базы);
  • куда указывают записи DNS домена и *.домена (см. раздел 12 «Проверки снаружи») - до того, как заказывать сертификат;
  • рекомендацию простыми словами: режим HTTPS (files, если 80 и 443 свободны; proxy, если их уже занял веб-сервер), свободный локальный порт для EduBox в режиме proxy (первый свободный с 127.0.0.1:8080), порт базы (5432 или первый свободный с 5433), готовые команды install, setup, proxy-config и предупреждения, например «nginx is running: EduBox will be installed behind it».

Пример на общем сервере:

Server
  port 80          in use by nginx (0.0.0.0:80, [::]:80)
  port 443         in use by nginx (0.0.0.0:443, [::]:443)
  127.0.0.1:5432   in use by postgres (127.0.0.1:5432)
…
Recommended
  HTTPS            proxy: nginx already owns ports 80 and 443: EduBox will listen on a local port behind it
  behind proxy     yes
  listen           127.0.0.1:8080 (a free local port the nginx forwards to)
  database port    127.0.0.1:5433 (127.0.0.1:5432 is used by postgres (another PostgreSQL); …)

--json - то же для сценариев; --offline - без проверок по сети. Код выхода 1, если установка откажется (строки «Install would refuse») или проверки снаружи нашли проблему. Без --domain берётся домен из уже записанных настроек.

Как это определяется и где может ошибаться:

  • Занятые порты читаются из /proc/net/tcp и /proc/net/tcp6, имя программы - через /proc/<pid>/fd. Без sudo имена чужих программ не видны: порт будет «in use by a program that could not be identified». Порт, проброшенный Docker без docker-proxy ("userland-proxy": false), в этих таблицах не виден.
  • Docker: команда docker version; «installed, not answering» - служба не запущена или нет прав.
  • Если EduBox уже установлен, его собственные порты (служба, контейнер базы) не считаются занятыми - повторная установка их сохраняет.

5. Установка: edubox install

Сначала посмотрите, что будет сделано, - ничего не меняется, пароли скрыты:

sudo ./edubox install --dry-run

Вывод начинается с итогов проверки сервера (строки # environment: …, # HTTPS: …, # database port …: … - какой порт базы выбран и почему), затем перечисляет каждый файл с содержимым и каждую команду. Строки # would refuse: … означают, что установка откажется (не root, нет systemd, нет docker).

Порт базы выбирается сам. Если 127.0.0.1:5432 занят (например, PostgreSQL самого сервера), install берёт первый свободный порт с 5433 и пишет, почему. Явный --db-port 5440 всегда главнее; занятый явный порт - отказ. При повторной установке остаётся порт, записанный в настройках.

Затем установка:

sudo ./edubox install

Она:

  1. создаёт системного пользователя edubox без входа в систему;
  2. создаёт /etc/edubox и /var/lib/edubox с подпапками и правами из таблицы выше;
  3. копирует программу в /usr/local/bin/edubox и шаблоны в /var/lib/edubox/templates (поставляемые шаблоны обновляются; свои шаблоны держите в папках с другими именами);
  4. запускает контейнер edubox-postgres (PostgreSQL 17, только на 127.0.0.1, порт 5432 или выбранный, том edubox-pgdata, перезапуск unless-stopped), ждёт его готовности, создаёт роли edubox_owner, edubox_app и базу edubox со случайными паролями;
  5. пишет два файла: /etc/edubox/edubox.toml (0640 root:edubox) со строкой подключения службы и /etc/edubox/owner.toml (0600 root:root) со строкой владельца базы. Если в edubox.toml осталась строка migrate_database_url от прежней версии, она переносится в owner.toml и из edubox.toml удаляется;
  6. пишет и включает службу edubox и таймер ежедневной копии (служба запустится после setup).

Повторный запуск безопасен: существующие пользователь, контейнер и пароли сохраняются, ключи, записанные setup, не трогаются.

Служба работает с ограничением памяти: MemoryHigh=1536M (выше ядро начинает жёстко отбирать память), MemoryMax=2G (при превышении служба завершается), MemorySwapMax=0 (без подкачки), и перезапускается после сбоя (Restart=on-failure, через 5 секунд). Изменить ограничения: sudo systemctl edit edubox, в открывшемся файле [Service] и новые значения, затем sudo systemctl restart edubox.

Внешний PostgreSQL

Если база на отдельном сервере, контейнер не нужен. Попросите администратора базы создать роли и базу (пароли придумайте свои):

CREATE ROLE edubox_owner LOGIN PASSWORD '…';
CREATE ROLE edubox_app   LOGIN PASSWORD '…';
CREATE DATABASE edubox OWNER edubox_owner ENCODING 'UTF8' TEMPLATE template0;
REVOKE ALL ON DATABASE edubox FROM PUBLIC;
GRANT CONNECT, TEMPORARY ON DATABASE edubox TO edubox_app;

Права edubox_app на таблицы выдаёт сама команда edubox migrate после каждой миграции. Установка (строка владельца попадёт в /etc/edubox/owner.toml, строка службы - в /etc/edubox/edubox.toml):

sudo ./edubox install \
  --database-url         'postgres://edubox_app:ПАРОЛЬ@db.example.kz:5432/edubox' \
  --migrate-database-url 'postgres://edubox_owner:ПАРОЛЬ@db.example.kz:5432/edubox'

Особые символы в пароле в строке подключения кодируются как в адресах (@ → %40). Для TLS к базе добавьте ?sslmode=require (или verify-full).

6. Настройка: edubox setup

sudo edubox setup

Вопросы:

ВопросПримерЧто значит
Домен порталаedu.example.kzсайты будут <имя>.edu.example.kz, админка admin.edu.example.kz. Кириллический домен - в punycode (xn--…)
Почта первого администратораadmin@example.kzему печатается ссылка-приглашение
Название корневой организации (каз., затем рус.)Абай облысының білім басқармасыкорневой узел портала
Как обеспечивается HTTPSproxy или filesраздел 8; по умолчанию - рекомендация проверки сервера
Адрес, который слушает EduBox127.0.0.1:8080для proxy - локальный порт, куда прокси передаёт запросы (по умолчанию свободный, найденный проверкой); для files - 0.0.0.0:443
Путь к сертификату и ключу (для files)/etc/edubox/tls/fullchain.pemPEM-файлы
Стоит ли перед EduBox обратный прокси, который ставит X-Forwarded-Foryes / noсм. ниже
Папка для резервных копий/backup/eduboxлучше отдельный диск

Перед вопросами setup печатает ту же рекомендацию, что edubox doctor; в квадратных скобках стоит рекомендованный ответ - Enter принимает его. Если выбранный адрес уже занят другой программой (и её удалось опознать), setup отказывается и предлагает свободный.

Вопрос о прокси задаётся всегда и намеренно. Если ответить неверно, все посетители за прокси будут выглядеть как один адрес, и ограничение попыток входа заблокирует всех сразу; или, наоборот, любой сможет подделать свой адрес. Поэтому setup не принимает противоречивые ответы: при proxy ответ должен быть yes, при files - no.

Затем setup пишет настройки, создаёт схему базы (миграции ролью-владельцем), выдаёт права роли службы и проверяет, что служба может подключиться, заносит справочники (языки, уровни, типы разделов) и корневой узел (без демонстрационных организаций), печатает ссылку-приглашение администратора, нужные записи DNS и запускает службу.

Без вопросов, для сценариев:

sudo edubox setup --non-interactive \
  --domain edu.example.kz --admin-email admin@example.kz \
  --root-name 'Абай облысының білім басқармасы' \
  --root-name-ru 'Управление образования области Абай' \
  --tls proxy --behind-proxy yes --backup-dir /backup/edubox

Без --listen в режиме proxy берётся свободный локальный порт (первый с 127.0.0.1:8080, при повторном запуске - прежний); --listen 127.0.0.1:8787 задаёт его явно. --tls (если его нет в прежних настройках) и --behind-proxy в таком запуске обязательны: при их отсутствии setup называет рекомендованное значение, но сам его не подставляет.

В режиме proxy setup заканчивается подсказкой, как получить настройки веб-сервера: sudo edubox proxy-config --server nginx --write /etc/nginx/sites-available/edubox.conf.

Повторный setup безопасен: меняет настройки, переименовывает корень и печатает новую ссылку (если пользователь уже есть - ссылку сброса пароля).

7. DNS

У регистратора или в DNS-сервере создайте две записи на публичный адрес сервера (или прокси):

edu.example.kz.     A   203.0.113.10
*.edu.example.kz.   A   203.0.113.10

Wildcard покрывает admin.edu.example.kz и все сайты. Проверка: dig +short admin.edu.example.kz или sudo edubox doctor --domain edu.example.kz - он сравнивает ответ DNS с адресами самого сервера (до заказа сертификата: без записей DNS сертификат не выдадут).

8. HTTPS

Режим proxy: за nginx, Caddy или другим прокси

EduBox слушает локальный адрес (listen в настройках, например 127.0.0.1:8080), прокси принимает 80 и 443 и передаёт запросы, сохраняя заголовок Host и добавляя адрес клиента в X-Forwarded-For. EduBox берёт самый правый адрес из X-Forwarded-For - тот, что добавил ближайший прокси.

Настройки для прокси пишет сама программа - для настроенного домена и адреса:

sudo edubox proxy-config --server nginx                    # напечатать
sudo edubox proxy-config --server nginx \
  --write /etc/nginx/sites-available/edubox.conf            # записать в файл
sudo edubox proxy-config --server caddy --write /etc/caddy/edubox.caddy

В настройках nginx: перенаправление HTTP → HTTPS (кроме /.well-known/acme-challenge/ - для выпуска сертификатов через /var/www/html), отдельный блок для edu.example.kz и отдельный для *.edu.example.kz (у них могут быть разные сертификаты), www.edu.example.kz → edu.example.kz, Host сохраняется, X-Forwarded-For дополняется, X-Forwarded-Proto, предел тела запроса 51m (загрузки до 50 МБ), таймауты 5 с на соединение и 120 с на ответ. Строка listen 443 ssl http2; выбрана намеренно: её понимают и nginx 1.24 (Ubuntu 24.04), и новые версии; nginx 1.25.1 и новее печатают при nginx -t безвредное предупреждение the "listen ... http2" directive is deprecated (новой формы http2 on; в 1.24 нет).

Пути к сертификатам:

ПараметрПо умолчанию
--cert, --key - для edu.example.kznginx: /etc/letsencrypt/live/edu.example.kz/fullchain.pem, privkey.pem; Caddy: выпускает сам
--wildcard-cert, --wildcard-key - для *.edu.example.kzте же, что для основного домена

Если файлов ещё нет или сертификат не покрывает нужное имя либо истекает через 14 дней и раньше, команда предупреждает. Веб-сервер она не перезагружает - печатает точные команды:

sudo ln -sf /etc/nginx/sites-available/edubox.conf /etc/nginx/sites-enabled/edubox.conf
sudo nginx -t && sudo systemctl reload nginx

Для Caddy - import /etc/caddy/edubox.caddy в /etc/caddy/Caddyfile, затем caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy. Caddy сам перенаправляет на HTTPS и выпускает сертификат для основного домена; сертификат на *.edu.example.kz он может получить только через DNS, для этого нужна сборка Caddy с модулем DNS-провайдера (в выводе есть закомментированный пример) - или укажите готовые файлы --wildcard-cert/--wildcard-key.

Если прокси на другой машине, укажите в setup --listen внутренний адрес этого сервера и закройте порт межсетевым экраном для всех, кроме прокси.

Общий сервер: EduBox за уже работающим nginx

Так прошла первая установка. Порядок:

sudo ./edubox doctor --domain edu.example.kz   # nginx на 80/443, 5432 занят → proxy, порты
sudo ./edubox install                          # сам берёт порт базы, например 5433
sudo edubox setup                              # Enter на рекомендованных ответах: proxy, yes,
                                               # свободный 127.0.0.1:8080 (или --listen …)
sudo edubox proxy-config --server nginx --write /etc/nginx/sites-available/edubox.conf
                                               # сертификаты: --cert/--key, --wildcard-cert/--wildcard-key
sudo ln -sf /etc/nginx/sites-available/edubox.conf /etc/nginx/sites-enabled/edubox.conf
sudo nginx -t && sudo systemctl reload nginx
sudo edubox status                             # база, DNS, HTTPS обоих имён

Чужие сайты и их настройки не затрагиваются: EduBox добавляет только свой файл с блоками server_name edu.example.kz, *.edu.example.kz, www.edu.example.kz. Если на сервере уже есть блок с таким же server_name (например, старая заглушка домена), nginx -t предупредит conflicting server name - отключите старый блок (уберите ссылку из sites-enabled).

Режим files: TLS у самого EduBox

EduBox слушает 443 с сертификатом и ключом из PEM-файлов и отвечает на 80 перенаправлением на https. Права на порты даёт служба (CAP_NET_BIND_SERVICE), root не нужен. Файлы должны читаться пользователем edubox:

sudo install -d -m 0750 -o root -g edubox /etc/edubox/tls
sudo install -m 0640 -o root -g edubox fullchain.pem /etc/edubox/tls/fullchain.pem
sudo install -m 0640 -o root -g edubox privkey.pem   /etc/edubox/tls/privkey.pem

В fullchain.pem сначала сертификат сайта, затем промежуточные. После замены файлов:

sudo systemctl reload edubox     # перечитывает сертификат без остановки (SIGHUP)

Если новые файлы не читаются, остаётся прежний сертификат, а в журнале - ошибка. Срок действия показывает edubox status.

Сертификат на все поддомены вручную

Автоматического выпуска сертификатов пока нет. Сертификат на *.edu.example.kz (его требуют admin.edu.example.kz и все сайты школ) Let's Encrypt выдаёт только с проверкой через DNS: нужно создать запись TXT. Так сделано при первой установке:

  1. Сертификат на основной домен edu.example.kz - обычным способом, например sudo certbot --nginx -d edu.example.kz (проверка по HTTP; certbot продлевает его сам).

  2. Сертификат на поддомены - вручную через DNS:

    sudo certbot certonly --manual --preferred-challenges dns -d '*.edu.example.kz' \
      --cert-name edu.example.kz-wildcard
    

    certbot покажет значение для одной записи TXT _acme-challenge.edu.example.kz. Создайте её у DNS-провайдера, дождитесь, пока она видна (dig +short TXT _acme-challenge.edu.example.kz), нажмите Enter. Файлы появятся в /etc/letsencrypt/live/edu.example.kz-wildcard/.

  3. Подключите оба сертификата:

    sudo edubox proxy-config --server nginx \
      --wildcard-cert /etc/letsencrypt/live/edu.example.kz-wildcard/fullchain.pem \
      --wildcard-key  /etc/letsencrypt/live/edu.example.kz-wildcard/privkey.pem \
      --write /etc/nginx/sites-available/edubox.conf
    sudo nginx -t && sudo systemctl reload nginx
    

Ограничения, честно:

  • Сертификат действует около 90 дней и сам не продлевается: certbot renew для сертификата, полученного с --manual, не сработает без скрипта для DNS-провайдера. Каждые два–три месяца процедуру надо повторять (с новым значением TXT). edubox status напоминает за 14 дней: «expires in N days: renew it».
  • Значение TXT каждый раз новое; старую запись можно удалить после выпуска.
  • Если просить сразу -d edu.example.kz -d '*.edu.example.kz', certbot попросит два значения для одной и той же записи _acme-challenge - оба нужно добавить в неё, а продлевать такой сертификат тоже придётся вручную. Поэтому основной домен лучше держать отдельным сертификатом с автоматическим продлением.
  • В режиме files (TLS у самого EduBox) нужен один сертификат на оба имени: тогда запросите оба имени сразу и скопируйте файлы, как показано выше для режима files.

Сертификат от другого удостоверяющего центра: закажите на edu.example.kz и *.edu.example.kz, ключ создайте у себя:

openssl req -new -newkey rsa:3072 -nodes -keyout privkey.pem -out request.csr \
  -subj "/CN=edu.example.kz" -addext "subjectAltName=DNS:edu.example.kz,DNS:*.edu.example.kz"

Полученный сертификат и цепочку соедините: cat cert.pem intermediate.pem > fullchain.pem.

9. Первый вход

setup печатает ссылку вида https://admin.edu.example.kz/invite/?token=…. Откройте её, задайте пароль - вы администратор корневого узла. Ссылка потерялась или истекла:

sudo edubox admin create --email admin@example.kz

Эта же команда - аварийный вход: для существующего пользователя печатает ссылку сброса пароля.

10. Резервные копии

Таймер edubox-backup.timer каждый день около 02:30 делает копию и оставляет 14 последних. Вручную:

sudo edubox backup                 # одна копия в backup_dir
sudo edubox backup --keep 30       # и удалить старше 30 последних
systemctl list-timers edubox-backup.timer
journalctl -u edubox-backup -n 20

Копия - один файл edubox-backup-ГГГГММДД-ЧЧММСС.tar.gz (время UTC): дамп базы, загруженные файлы, копии обоих файлов настроек - config/edubox.toml и config/owner.toml (пароли базы в них заменены на REDACTED) - и manifest.json с версией программы, версией схемы и контрольными суммами всех файлов.

Символические ссылки и особые файлы (каналы, сокеты, устройства) в папке загруженных файлов в копию не попадают и не разыменовываются: команда перечисляет пропущенное в своём выводе и в журнале. Обычно таких файлов там нет; если они появились, выясните, откуда.

Копии на этом же сервере не спасут при потере сервера. Пока автоматической отправки нет, копируйте их регулярно на другую машину, например:

rsync -a /backup/edubox/ backup-host:/srv/edubox-backups/

Восстановление

sudo edubox restore /backup/edubox/edubox-backup-20261115-023012.tar.gz

Команда распаковывает архив во временную папку, принадлежащую root, вне папки данных (/var/tmp, если она есть, иначе системная временная папка), проверяет контрольные суммы и версию схемы (копию из более новой версии программы не примет), спрашивает подтверждение (--yes - без вопроса), останавливает службу, делает копию текущего состояния (…-pre-restore.tar.gz; пропустить - --no-safety-backup), заменяет базу и загруженные файлы, доводит схему до версии программы и запускает службу. Загруженные файлы копируются из временной папки без перехода по символическим ссылкам. Прежние файлы остаются в /var/lib/edubox/uploads.before-restore-… - удалите, когда убедитесь, что всё в порядке. Файлы настроек (edubox.toml, owner.toml) не заменяются; их копии из архива (с паролями REDACTED) кладутся в папку копий как restored-config-…toml и restored-owner-…toml.

На новом сервере: install, затем setup с теми же ответами (домен, TLS, прокси - их можно посмотреть в config/edubox.toml внутри архива: tar -xzOf АРХИВ config/edubox.toml), затем restore. Приглашение, напечатанное setup, после восстановления недействительно - входите прежними учётными записями.

11. Обновление (пока вручную)

# скачать и проверить новый архив (раздел 3), распаковать, перейти в папку
sudo edubox backup
sudo systemctl stop edubox
sudo install -m 0755 ./edubox /usr/local/bin/edubox
sudo cp -r ./templates/. /var/lib/edubox/templates/
sudo edubox migrate
sudo systemctl start edubox
sudo edubox status

Откат: верните прежний файл программы. Если новая версия уже применила миграции, прежняя откажется запускаться («the database was migrated by a newer EduBox») - тогда восстановите копию, сделанную перед обновлением, прежней версией программы.

Обновление с проверкой подписи и автоматическим откатом появится позже.

12. Проверки снаружи (DNS, HTTPS)

edubox status и edubox doctor смотрят на установку и со стороны сети:

  • DNS. Основной домен и проверочное имя edubox-check-….edu.example.kz (проверяет запись *.edu.example.kz) должны указывать на адрес этого сервера. Адреса сервера берутся из таблиц ядра (/proc/net/fib_trie, /proc/net/if_inet6). Если у сервера нет публичного адреса (он за NAT или балансировщиком), программа пишет «could not determine», а не гадает. Если имя на самом сервере указывает на 127.0.0.1 (запись в /etc/hosts), проверка тоже не делается - проверьте с другой машины: dig +short edu.example.kz.
  • HTTPS (только в режиме proxy): запросы https://edu.example.kz/healthz и https://admin.edu.example.kz/api/health, а также рукопожатие TLS с проверочным именем поддомена. Для каждого - ответ, действительность сертификата (по встроенному списку корневых центров, как в браузере) и срок. Проблема, если сертификат недействителен, не покрывает *.edu.example.kz («the wildcard certificate is missing») или истекает через 14 дней и раньше, а также если прокси отвечает 502 (EduBox не запущен или прокси смотрит не туда).

У каждой сетевой операции короткий таймаут (3–4 с), все идут параллельно. Если сети нет или ответа не дождались, пункт помечается «not checked: …» и не считается проблемой (код выхода не меняется). --offline пропускает эти проверки совсем.

13. Диагностика

sudo edubox doctor            # что на сервере: порты, Docker, systemd, место, DNS; рекомендация
sudo edubox status            # версия, схема, база, место, последняя копия, сертификат, DNS, HTTPS
sudo edubox status --json     # то же для мониторинга; код выхода 1 при проблемах
sudo edubox status --offline  # без проверок по сети
journalctl -u edubox -f       # журнал службы
systemctl status edubox
docker logs edubox-postgres   # журнал PostgreSQL
ПризнакПричина и что делать
refusing to start: the database schema is behind this binaryпосле обновления не выполнена sudo edubox migrate
refusing to start: the database has no EduBox schema yetне выполнен sudo edubox setup
base_domain is not setне выполнен sudo edubox setup
refusing to start: migrate_database_url …пароль владельца базы доступен службе: строка migrate_database_url есть в /etc/edubox/edubox.toml или задана EDUBOX_MIGRATE_DATABASE_URL. Перенесите строку в /etc/edubox/owner.toml (0600 root:root) - это делает повторный sudo edubox install, - уберите её из edubox.toml и из окружения службы (systemctl cat edubox), затем sudo systemctl start edubox
reading /etc/edubox/owner.toml (run this command as root)команды migrate, setup, seed, admin create, backup, restore запускайте через sudo
служба перезапускается сама, в журнале oom-kill или memoryупёрлась в MemoryMax=2G; посмотрите, что её нагружает, при необходимости поднимите предел через sudo systemctl edit edubox
binding 0.0.0.0:443: Permission deniedслужба запущена не из юнита (нет CAP_NET_BIND_SERVICE) - запускайте через systemctl
binding …: Address in useпорт занят другой программой: sudo edubox doctor покажет какой; для режима proxy выберите свободный адрес (setup --listen), затем proxy-config заново
reading /etc/edubox/tls/…: Permission deniedправа на файлы сертификата: группа edubox, режим 0640, папка 0750
connecting to PostgreSQLконтейнер не запущен: docker ps -a, docker start edubox-postgres; внешняя база - проверьте строку и доступ
установка: port 5440 on 127.0.0.1 (given with --db-port) is in useявно указанный порт базы занят: уберите --db-port (свободный выберется сам) или укажите другой
status: DNS edu.example.kz: does not resolve / points to …нет записи A или она указывает не на этот сервер (раздел 7)
status: the wildcard certificate is missingпрокси отдаёт для поддоменов сертификат без *.edu.example.kz: раздел «Сертификат на все поддомены вручную», затем proxy-config --wildcard-cert …
status: expires in N days: renew itпродлите сертификат; полученный вручную через TXT сам не продлится
status: answered 502прокси не достучался до EduBox: systemctl status edubox; адрес в настройках прокси должен совпадать с listen в /etc/edubox/edubox.toml
nginx -t: conflicting server nameна сервере уже есть блок с тем же доменом (заглушка): уберите его ссылку из sites-enabled
образ postgres:17 не скачивается (нет интернета)на машине с интернетом docker pull postgres:17 && docker save postgres:17 -o pg17.tar, перенести, docker load -i pg17.tar и повторить install
страница «сайт не найден»нет записи DNS (sudo edubox status) или узел с таким коротким именем не создан/не опубликован
все входы блокируются разомза прокси ответили no на вопрос о прокси или прокси не ставит X-Forwarded-For - повторите setup
копии не делаютсяjournalctl -u edubox-backup; для внешней базы нужен pg_dump версии 17

Подробный журнал: sudo systemctl edit edubox, добавить [Service] / Environment=RUST_LOG=edubox=debug,tower_http=debug, затем systemctl restart edubox.