Squop Docs
Справка по squopctl
squopctl — основная команда для установки и обслуживания self-hosted версии Squop.
Перед запуском любой команды ознакомьтесь с правилами использования Squop на своём сервере и подтвердите их принятие:
cp .license.example .licenseБез файла .license с подтверждением принятия правил команды squopctl выполняться не будут. Общая справка ./squopctl --help доступна без подтверждения.
Общий формат:
./squopctl [global options] <command> [command options]Все команды пишут подробный лог в state/logs/. Последний лог доступен по пути:
state/logs/latest.logТребования к запуску
Squop требует домен, HTTPS и внешний reverse proxy.
Настроить reverse proxy
Squop слушает 127.0.0.1:8080; внешний web server принимает HTTPS-трафик и проксирует его в Squop.
Укажите домен без https://, пути и порта, например chat.example.com.
Email подставляется в команды и примеры конфигурации ниже.
Необязательно: пустое поле создаст случайный пароль.
Установите Caddy и создайте конфиг, который читает стандартный systemd-сервис:
sudo apt update
sudo apt install -y caddy
sudo tee /etc/caddy/Caddyfile >/dev/null <<'EOF'
your_domain.ru {
reverse_proxy 127.0.0.1:8080 {
header_up Host {host}
header_up X-Forwarded-Host {host}
header_up X-Forwarded-Proto https
header_up X-Forwarded-Port 443
}
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl enable --now caddyНе добавляйте к домену http:// или :80: Caddy сам включит HTTPS. Откройте входящие TCP-порты 80 и 443 в firewall и security group провайдера.
Пример для Nginx:
server {
listen 443 ssl http2;
server_name your_domain.ru;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Port 443;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}Глобальные флаги
Глобальные флаги указываются до имени команды.
| Флаг | Что делает |
|---|---|
--config PATH | Использовать другой deploy.env вместо state/deploy.env. |
--secrets PATH | Использовать другой secrets.env вместо state/secrets.env. |
-h, --help | Показать общую справку по squopctl. |
Пример:
./squopctl --config /srv/squop/deploy.env preflightКоманды
init
Создаёт стартовые конфиги deploy.env и secrets.env.
Технические секреты в secrets.env генерируются автоматически: APP_KEY, пароль БД, пароль первого админа, Reverb и LiveKit ключи. --admin-email задаёт email первого администратора; необязательный --admin-password задаёт его пароль, а без него пароль генерируется автоматически.
После установки secrets.env нельзя перегенерировать для того же instance: DB_PASSWORD должен совпадать с паролем внутри сохранённого тома Docker с базой данных.
Обычно это первая команда на новом сервере.
./squopctl init --domain your_domain.ru --admin-email admin@example.comФлаги:
| Флаг | Что делает |
|---|---|
--domain DOMAIN | Публичный домен, без https://; формирует PUBLIC_URL. |
--admin-email EMAIL | Email первого администратора. |
--admin-password PASSWORD | Необязательный пароль первого администратора, минимум 8 символов. Если не передан, генерируется автоматически. |
--force | Перезаписать существующие deploy.env и secrets.env. |
-h, --help | Показать справку по init. |
Если команда запущена в терминале, она запросит недостающие обязательные значения. В non-interactive режиме для нового конфига необходимо передать --admin-email и --domain.
После успешного install пароль первого администратора показывается в терминале, но не попадает в transcript-логи.
Админ-панель будет доступна по адресу из PUBLIC_URL. По умолчанию путь — admin, то есть PUBLIC_URL/admin.
preflight
Проверяет сервер и конфиг перед установкой.
Команда смотрит Docker, Docker Compose, ресурсы сервера, доступность портов, диапазон UDP-портов 50000-50999, путь для данных и корректность домена и HTTPS-адреса.
Также проверяется ADMIN_PATH: это должен быть относительный путь без ведущего /, например admin или control-panel.
Для новых конфигов DATA_PATH по умолчанию равен /opt/squop, чтобы данные хранились на постоянном диске, а не в часто ограниченном /tmp.
./squopctl preflightФлаги:
| Флаг | Что делает |
|---|---|
-h, --help | Показать справку по preflight. |
apply
Генерирует служебные файлы для запуска из deploy.env и secrets.env.
После выполнения в state/generated/ появляются служебные файлы Docker и настроек. Контейнеры эта команда не запускает.
./squopctl applyФлаги:
| Флаг | Что делает |
|---|---|
-h, --help | Показать справку по apply. |
install
Основная команда установки.
Она запускает preflight, генерирует служебные файлы для запуска, скачивает образы Docker, поднимает контейнеры, выполняет миграции и проверяет результат через verify.
./squopctl installФлаги:
| Флаг | Что делает |
|---|---|
--force | Продолжить после ошибок preflight. Не игнорирует сбои Docker, миграций и verify. |
-h, --help | Показать справку по install. |
status
Показывает текущее состояние self-hosted.
Команда сообщает, есть ли конфиги, где находится state, запущены ли контейнеры и какой следующий шаг обычно нужен.
./squopctl statuslogs
Показывает логи контейнеров.
Можно смотреть все сервисы сразу или указать один/несколько сервисов.
Основные сервисы:
| Сервис | Что это |
|---|---|
proxy | Nginx/proxy, отдаёт сайт, настройки приложения, API и подключения в реальном времени. |
app | Backend-приложение. |
queue-worker | Обработчик фоновых задач. |
scheduler | Планировщик задач приложения. |
reverb | Сервер обмена сообщениями в реальном времени. |
livekit | Сервер голосовых и видеозвонков. |
postgres | База данных. |
redis_app | Redis для приложения. |
beanstalkd | Очередь задач. |
./squopctl logs
./squopctl logs proxy
./squopctl logs app queue-worker --tail 200
./squopctl logs reverb --followФлаги и параметры:
| Флаг или параметр | Что делает |
|---|---|
service ... | Показать логи только выбранных сервисов, например proxy, app, reverb. |
--tail N | Показать последние N строк. По умолчанию показываются последние 100 строк. |
-f, --follow | Продолжать выводить новые строки логов в реальном времени. |
-- | Завершить разбор флагов; всё после -- считается именами сервисов. |
-h, --help | Показать справку по logs. |
verify
Проверяет, что Squop работает после установки.
Команда проверяет работу контейнеров, доступность сайта и API, настройки и подключение авторизованного пользователя.
./squopctl verifyФлаги:
| Флаг | Что делает |
|---|---|
-h, --help | Показать справку по verify. |
restart
Перегенерирует служебные файлы для запуска и пересоздаёт контейнеры.
Используйте после изменения deploy.env или secrets.env. Команда не скачивает новые образы Docker, не запускает миграции и не делает автоматический verify.
./squopctl restart
./squopctl verifyФлаги:
| Флаг | Что делает |
|---|---|
-h, --help | Показать справку по restart. |
down
Останавливает Squop и удаляет контейнеры.
Данные при этом сохраняются: именованные тома Docker, DATA_PATH, локальные конфиги и файлы не удаляются.
./squopctl downФлаги:
| Флаг | Что делает |
|---|---|
-h, --help | Показать справку по down. |
reset
Удаляет данные текущего инстанса.
Команда удаляет тома Docker. Локальные deploy.env, secrets.env, файлы и DATA_PATH остаются на диске.
./squopctl reset --destroy-dataФлаги:
| Флаг | Что делает |
|---|---|
--destroy-data | Обязательное подтверждение удаления named Docker volumes. |
-h, --help | Показать справку по reset. |
check-update
Проверяет, доступна ли новая версия в выбранном канале обновлений.
Команда использует встроенные адреса манифестов. Опытные пользователи могут указать свои адреса через старые поля MANIFESTS_VERSIONS_URL и MANIFESTS_COMPATIBILITY_URL в deploy.env.
./squopctl check-updateФлаги:
| Флаг | Что делает |
|---|---|
--to VERSION | Проверить возможность обновления до конкретной версии. |
-h, --help | Показать справку по check-update. |
update
Обновляет установленный Squop до новой версии.
Команда скачивает информацию о версиях, выбирает версию, сохраняет копию настроек и применяет обновление, скачивает образы Docker, пересоздаёт контейнеры, запускает миграции и выполняет verify.
./squopctl updateФлаги:
| Флаг | Что делает |
|---|---|
--to VERSION | Обновиться до конкретной версии, а не до самой новой доступной. |
-h, --help | Показать справку по update. |
Важно: автоматического отката БД и пользовательских данных сейчас нет. Перед обновлениями с миграциями нужна резервная копия базы данных и DATA_PATH.
support-bundle
Собирает архив для диагностики.
В архив попадают статус, логи, сведения о контейнерах и копии настроек без секретных данных.
./squopctl support-bundleАрхив создаётся в:
state/logs/bundles/Флаги:
| Флаг | Что делает |
|---|---|
-h, --help | Показать справку по support-bundle. |
Частые сценарии
Первый запуск за внешним HTTPS proxy
./squopctl init --domain your_domain.ru --admin-email admin@example.comЗатем проверьте конфиг и запустите установку:
./squopctl preflight
./squopctl install
./squopctl verifyПроверить результат
После успешного verify откройте:
https://your_domain.ru
https://your_domain.ru/adminПосмотреть состояние и логи
./squopctl status
./squopctl logs
./squopctl logs proxy --tail 200Обновить instance
./squopctl check-update
./squopctl update
./squopctl verifyОстановить Squop без удаления данных
./squopctl downЧтобы снова запустить Squop с сохранёнными данными:
./squopctl install
./squopctl verifyПолностью удалить данные Squop из Docker
./squopctl reset --destroy-dataПосле этого следующий install создаст новый том Docker с базой данных и текущим DB_PASSWORD из secrets.env.
Совместимость существующих установок
Существующие HTTPS-установки продолжают работать без изменения конфигов. Старые значения DEPLOY_PROFILE=external-proxy, TLS_MODE=external-proxy и флаг --profile external-proxy принимаются для совместимости. В новых конфигурациях и командах они не нужны.
Переход с sandbox
Запуск и обновление без HTTPS больше не поддерживаются. Остановка через down, просмотр состояния и логов, сбор диагностики остаются доступны.
- Подготовьте домен, DNS и внешний reverse proxy с доверенным HTTPS-сертификатом по инструкции выше.
- Сохраните резервную копию
state/deploy.env,state/secrets.envи данных instance. - Остановите старый runtime командой
./squopctl down. Если он уже остановлен, пропустите этот шаг. Команда сохраняет volumes и данные. - В
state/deploy.envзадайтеPUBLIC_URL=https://your_domain.ru, удалитеDEPLOY_PROFILEиTLS_MODE. УстановитеHTTP_PORT=8080, если reverse proxy направляет запросы на127.0.0.1:8080. Сохраните прежнийDATA_PATH. - Выполните
./squopctl restart, затем./squopctl verify.
Не используйте init --force или reset для перехода. Сохраните существующие секреты, включая пароль базы данных.
Одновременные операции
install, update, restart и reset выполняются по одной в каталоге установки. Если другая операция ещё работает, команда завершится с сообщением: дождитесь её окончания и повторите запуск. Справка и диагностические команды остаются доступны. Блокировка снимается автоматически при завершении процесса; удалять state/runtime.lock не нужно.
Для блокировки требуется flock из пакета util-linux.