Squop Docs

Справка по squopctl

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

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

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

Настроить reverse proxy

В режиме external-proxy Squop слушает 127.0.0.1:8080; внешний web server принимает HTTPS-трафик и проксирует его в Squop.

Ваш домен

Укажите домен без https://, пути и порта, например chat.example.com.

Email администратора

Email подставляется в команды и примеры конфигурации ниже.

Пароль администратора

Необязательно: пустое поле создаст случайный пароль.

Установите Caddy и создайте конфиг, который читает стандартный systemd-сервис:

bash

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:

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.

Пример:

bash

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

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

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

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

bash

./squopctl init --profile sandbox --admin-email admin@example.com

Флаги:

Флаг	Что делает
`--profile sandbox`	Создать конфиг для простого HTTP/sandbox запуска.
`--profile external-proxy`	Создать конфиг для запуска за внешним HTTPS reverse proxy.
`--domain DOMAIN`	Домен для `external-proxy`, без `https://`; формирует `PUBLIC_URL`.
`--admin-email EMAIL`	Email первого администратора.
`--admin-password PASSWORD`	Необязательный пароль первого администратора, минимум 8 символов. Если не передан, генерируется автоматически.
`--force`	Перезаписать существующие `deploy.env` и `secrets.env`.
`-h`, `--help`	Показать справку по `init`.

Если команда запущена в терминале, она запросит недостающие обязательные значения. В non-interactive режиме для нового конфига необходимо передать --admin-email, а для external-proxy — также --domain. После успешного install пароль первого администратора показывается в терминале, но не попадает в transcript-логи.

Админ-панель будет доступна по адресу из PUBLIC_URL. По умолчанию путь — admin, то есть PUBLIC_URL/admin.

`preflight`

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

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

bash

./squopctl preflight

Флаги:

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

`apply`

Генерирует служебные файлы для запуска из deploy.env и secrets.env.

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

bash

./squopctl apply

Флаги:

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

`install`

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

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

bash

./squopctl install

Флаги:

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

`status`

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

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

bash

./squopctl status

`logs`

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

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

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

Сервис	Что это
`proxy`	Nginx/proxy, отдаёт сайт, настройки приложения, API и подключения в реальном времени.
`app`	Backend-приложение.
`queue-worker`	Обработчик фоновых задач.
`scheduler`	Планировщик задач приложения.
`reverb`	Сервер обмена сообщениями в реальном времени.
`livekit`	Сервер голосовых и видеозвонков.
`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`

Проверяет, что Squop работает после установки.

Команда проверяет работу контейнеров, доступность сайта и API, настройки и подключение авторизованного пользователя.

bash

./squopctl verify

Флаги:

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

`restart`

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

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

bash

./squopctl restart
./squopctl verify

Флаги:

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

`down`

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

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

bash

./squopctl down

Флаги:

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

`reset`

Удаляет данные текущего инстанса.

Команда удаляет тома Docker. Локальные deploy.env, secrets.env, файлы и DATA_PATH остаются на диске.

bash

./squopctl reset --destroy-data

Флаги:

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

`check-update`

Проверяет, доступна ли новая версия в выбранном канале обновлений.

Команда использует встроенные адреса манифестов. Опытные пользователи могут указать свои адреса через старые поля MANIFESTS_VERSIONS_URL и MANIFESTS_COMPATIBILITY_URL в deploy.env.

bash

./squopctl check-update

Флаги:

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

`update`

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

Команда скачивает информацию о версиях, выбирает версию, сохраняет копию настроек и применяет обновление, скачивает образы Docker, пересоздаёт контейнеры, запускает миграции и выполняет verify.

bash

./squopctl update

Флаги:

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

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

`support-bundle`

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

В архив попадают статус, логи, сведения о контейнерах и копии настроек без секретных данных.

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 --domain your_domain.ru --admin-email admin@example.com

Затем проверьте конфиг и запустите установку:

bash

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

Проверить результат

После успешного verify откройте:

text

https://your_domain.ru
https://your_domain.ru/admin

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

bash

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

Обновить instance

bash

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

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

bash

./squopctl down

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

bash

./squopctl install
./squopctl verify

Полностью удалить данные Squop из Docker

bash

./squopctl reset --destroy-data

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

Справка по squopctl

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

Настроить reverse proxy

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

Команды

`init`

`preflight`

`apply`

`install`

`status`

`logs`

`verify`

`restart`

`down`

`reset`

`check-update`

`update`

`support-bundle`

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

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

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

Проверить результат

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

Обновить instance

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

Полностью удалить данные Squop из Docker