Squop Docs

Справка по squopctl

squopctl — основная команда для установки и обслуживания self-hosted версии Squop.

Перед запуском любой команды ознакомьтесь с правилами self-hosted использования и подтвердите их принятие:

bash

cp .license.example .license

Без файла .license с подтверждением принятия правил команды squopctl выполняться не будут. Общая справка ./squopctl --help доступна без подтверждения.

Общий формат:

bash

./squopctl [global options] <command> [command options]

Все команды пишут подробный лог в state/logs/. Последний лог доступен по пути:

text

state/logs/latest.log

Поддерживаемые сценарии

squopctl поддерживает два сценария запуска:

DEPLOY_PROFILE=external-proxy — основной вариант для своего сервера
DEPLOY_PROFILE=sandbox — простой тестовый запуск без полноценного HTTPS

Глобальные флаги

Глобальные флаги указываются до имени команды.

Флаг	Что делает
`--config PATH`	Использовать другой deploy.env вместо state/deploy.env.
`--secrets PATH`	Использовать другой secrets.env вместо state/secrets.env.
`-h`, `--help`	Показать общую справку по squopctl.

Пример:

bash

./squopctl --config /srv/squop/deploy.env preflight

Создаёт стартовые конфиги deploy.env и secrets.env. Технические секреты в secrets.env генерируются автоматически: APP_KEY, пароль БД, пароль первого админа, Reverb и LiveKit ключи. Перед установкой нужно задать INITIAL_ADMIN_EMAIL; сгенерированный INITIAL_ADMIN_PASSWORD можно оставить или заменить вручную.

После установки secrets.env нельзя перегенерировать для того же instance: DB_PASSWORD должен совпадать с паролем внутри сохранённого Postgres volume.

Обычно это первая команда на новом сервере.

bash

./squopctl init --profile sandbox

Флаги:

Флаг	Что делает
`--profile sandbox`	Создать конфиг для простого HTTP/sandbox запуска. Используется по умолчанию.
`--profile external-proxy`	Создать шаблон конфига для запуска за внешним HTTPS reverse proxy.
`--force`	Перезаписать существующие `deploy.env` и `secrets.env` только если для instance нет runtime и Docker volumes.
`-h`, `--help`	Показать справку по `init`.

Важно: для external-proxy нужно заменить placeholder-значение PUBLIC_URL.

Админка доступна на том же origin, что и PUBLIC_URL, по пути из ADMIN_PATH. Дефолт: ADMIN_PATH=admin, то есть PUBLIC_URL/admin.

`preflight`

Проверяет сервер и конфиг перед установкой.

Команда смотрит Docker, Docker Compose, ресурсы сервера, доступность портов, LiveKit UDP-диапазон 50000-50999, путь для данных и корректность выбранного профиля. Также проверяется ADMIN_PATH: это должен быть относительный путь без ведущего /, например admin или control-panel.

bash

./squopctl preflight

Флаги:

Флаг	Что делает
`-h`, `--help`	Показать справку по `preflight`.

`apply`

Генерирует runtime-файлы из deploy.env и secrets.env.

После выполнения появляются внутренние compose/env/config артефакты в state/generated/. Контейнеры эта команда не запускает.

bash

./squopctl apply

Флаги:

Флаг	Что делает
`-h`, `--help`	Показать справку по `apply`.

`install`

Основная команда установки.

Она запускает preflight, генерирует runtime-файлы, скачивает Docker images, поднимает контейнеры, выполняет миграции и проверяет результат через verify.

bash

./squopctl install

Флаги:

Флаг	Что делает
`--wipe-db`	Перед миграциями очистить уже доступную базу через `php artisan db:wipe --force`. Не исправляет потерянный или перегенерированный `DB_PASSWORD`.
`-h`, `--help`	Показать справку по `install`.

`status`

Показывает текущее состояние self-hosted runtime.

Команда сообщает, есть ли конфиги, где находится state, запущены ли контейнеры и какой следующий шаг обычно нужен.

bash

./squopctl status

`logs`

Показывает логи контейнеров текущего compose runtime.

Можно смотреть все сервисы сразу или указать один/несколько сервисов.

Основные сервисы:

Сервис	Что это
`proxy`	Nginx/proxy, отдаёт frontend, runtime config, API и websocket ingress.
`app`	Backend-приложение.
`queue-worker`	Обработчик фоновых задач.
`scheduler`	Планировщик задач приложения.
`reverb`	Realtime/WebSocket сервер.
`livekit`	Voice/video media server.
`postgres`	База данных.
`redis_app`	Redis для приложения.
`beanstalkd`	Очередь задач.

bash

./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`

Проверяет, что runtime действительно работает.

Команда проверяет compose-сервисы, HTTP/API доступность, runtime config и authenticated realtime path.

bash

./squopctl verify

Флаги:

Флаг	Что делает
`-h`, `--help`	Показать справку по `verify`.

`restart`

Перегенерирует runtime-файлы и пересоздаёт контейнеры.

Используйте после изменения deploy.env или secrets.env. Команда не скачивает новые images, не запускает миграции и не делает автоматический verify.

bash

./squopctl restart
./squopctl verify

Флаги:

Флаг	Что делает
`-h`, `--help`	Показать справку по `restart`.

`down`

Останавливает и удаляет текущий compose runtime.

Данные при этом сохраняются: named volumes, DATA_PATH, локальные конфиги и generated-файлы не удаляются.

bash

./squopctl down

Флаги:

Флаг	Что делает
`-h`, `--help`	Показать справку по `down`.

`reset`

Удаляет Docker runtime-data текущего instance.

Это destructive-команда: она удаляет named Docker volumes, включая Postgres data. Локальные deploy.env, secrets.env, generated-файлы и DATA_PATH остаются на диске.

bash

./squopctl reset --destroy-data

Флаги:

Флаг	Что делает
`--destroy-data`	Обязательное подтверждение удаления named Docker volumes.
`-h`, `--help`	Показать справку по `reset`.

`check-update`

Проверяет, доступна ли новая версия в текущем release channel.

Команда использует встроенные remote manifest URLs. Advanced override возможен через старые поля MANIFESTS_VERSIONS_URL и MANIFESTS_COMPATIBILITY_URL в deploy.env.

bash

./squopctl check-update

Флаги:

Флаг	Что делает
`--to VERSION`	Проверить возможность обновления до конкретной версии.
`-h`, `--help`	Показать справку по `check-update`.

`update`

Обновляет установленный runtime до новой версии.

Команда скачивает remote manifests, выбирает целевую версию, создаёт snapshot конфигов, применяет target version как managed runtime override, скачивает images, пересоздаёт контейнеры, запускает миграции и выполняет verify.

bash

./squopctl update

Флаги:

Флаг	Что делает
`--to VERSION`	Обновиться до конкретной версии, а не до самой новой доступной.
`-h`, `--help`	Показать справку по `update`.

Важно: автоматического отката БД и пользовательских данных сейчас нет. Перед обновлениями с миграциями нужен внешний backup базы и DATA_PATH.

`support-bundle`

Собирает архив для диагностики.

В архив попадают статус, логи, compose diagnostics и redacted snapshots конфигов без raw secrets.

bash

./squopctl support-bundle

Архив создаётся в:

text

state/logs/bundles/

Флаги:

Флаг	Что делает
`-h`, `--help`	Показать справку по `support-bundle`.

Частые сценарии

Первый запуск sandbox

bash

./squopctl init --profile sandbox
./squopctl install
./squopctl verify

Первый запуск за внешним HTTPS proxy

bash

./squopctl init --profile external-proxy

Затем заполните реальный PUBLIC_URL в state/deploy.env, после чего:

bash

./squopctl preflight
./squopctl install
./squopctl verify

Посмотреть состояние и логи

bash

./squopctl status
./squopctl logs
./squopctl logs proxy --tail 200

Обновить instance

bash

./squopctl check-update
./squopctl update
./squopctl verify

Остановить runtime без удаления данных

bash

./squopctl down

Чтобы снова развернуть runtime с сохранёнными данными:

bash

./squopctl install
./squopctl verify

Полностью удалить Docker data

bash

./squopctl reset --destroy-data

После этого следующий install создаст Postgres volume заново с текущим DB_PASSWORD из secrets.env.

Справка по squopctl

Поддерживаемые сценарии

Глобальные флаги

Команды

`init`

`preflight`

`apply`

`install`

`status`

`logs`

`verify`

`restart`

`down`

`reset`

`check-update`

`update`

`support-bundle`

Частые сценарии

Первый запуск sandbox

Первый запуск за внешним HTTPS proxy

Посмотреть состояние и логи

Обновить instance

Остановить runtime без удаления данных

Полностью удалить Docker data