intra_max_bot/DEPLOY_VARIANT_A.md

Deploy Guide (Variant A: No Docker Runtime)

This guide is for deployment from source code on the server:

• git pull after each push
• restart systemd service
• no Docker runtime

0) What is already prepared in this repo

• CI pipeline for Variant A: .woodpecker.yml
• Env template with host/port/public IP/domain vars: .env.example
• App runner that uses APP_HOST/APP_PORT: app/run.py
• systemd template: deploy/systemd/max-support.service.template
• sudoers template: deploy/sudoers/max-support-restart.template
• One-shot setup script: deploy/scripts/setup_variant_a.sh

1) Create repository and connect CI

1. Create repository in GitHub/GitLab.
2. Push current project to main.
3. Connect repository to Woodpecker.

2) Prepare server

Example for Ubuntu/Debian:

sudo apt update
sudo apt install -y git curl python3 python3-venv python3-pip
sudo mkdir -p /opt/max-support
sudo chown -R $USER:$USER /opt/max-support
git clone <SSH_REPO_URL> /opt/max-support
cd /opt/max-support

3) Create server .env

Create /opt/max-support/.env:

APP_ENV=prod
APP_HOST=0.0.0.0
APP_PORT=8000

# Public endpoint metadata (for ops/documentation)
APP_PUBLIC_IP=203.0.113.10
APP_PUBLIC_DOMAIN=bot.example.com
APP_BASE_URL=https://bot.example.com

DB_PATH=/opt/max-support/data/app.db
SESSION_SECRET=CHANGE_ME_LONG_RANDOM_STRING
WEB_ADMIN_LOGIN=admin
WEB_ADMIN_PASSWORD=CHANGE_ME_STRONG_PASSWORD

MAX_BOT_TOKEN=YOUR_MAX_BOT_TOKEN
MAX_BOT_API_URL=https://botapi.max.ru

# Recommended first start: polling mode
MAX_USE_WEBHOOK=false
MAX_WEBHOOK_URL=
MAX_WEBHOOK_SECRET=

CONTEXT_BACKEND=memory
REDIS_URL=redis://127.0.0.1:6379/0

CHANNEL_LOCAL_ENABLED=true
CHANNEL_EXTERNAL_ENABLED=true
EXTERNAL_API_CREATE_URL_WITH_KEY=https://external.example/api/create?key=YOUR_KEY

OPERATOR_CHAT_IDS=123456,987654
REQUEST_CATEGORIES=Общая консультация,Техническая проблема,Оплата,Другое

4) Run one-shot setup on server

cd /opt/max-support
chmod +x deploy/scripts/setup_variant_a.sh
APP_DIR=/opt/max-support APP_USER=$USER SERVICE_NAME=max-support ./deploy/scripts/setup_variant_a.sh

What this does:

1. Creates/updates .venv
2. Installs dependencies
3. Installs systemd unit
4. Installs sudoers rule for restart
5. Enables and starts max-support
6. Runs healthcheck on 127.0.0.1:${APP_PORT}

5) Woodpecker secrets (required)

Create these repository secrets:

1. deploy_host - server host (IP or domain), e.g. 203.0.113.10
2. deploy_user - SSH user on server, e.g. deploy
3. deploy_port - SSH port, usually 22
4. deploy_ssh_key - private SSH key (PEM, multiline)

No registry secrets are needed in Variant A.

6) SSH and sudo requirements

deploy_user must be able to:

1. cd /opt/max-support && git pull --ff-only
2. sudo systemctl restart max-support

The setup script already installs sudoers rule in /etc/sudoers.d/max-support-restart:

<deploy_user> ALL=(ALL) NOPASSWD:/bin/systemctl restart max-support,/bin/systemctl status max-support

7) CI/CD flow now

On each push to main/master:

1. Tests run
2. CI connects via SSH
3. Executes git pull --ff-only
4. Updates dependencies in .venv
5. Restarts max-support service
6. Checks /health using APP_PORT from /opt/max-support/.env

8) Useful commands on server

sudo systemctl status max-support
sudo journalctl -u max-support -n 200 --no-pager
sudo systemctl restart max-support
curl -fsS http://127.0.0.1:8000/health