Phase 4 — docs.avaxis.cz production deploy¶

Audience: super_admin (Michal) co dělá první production rollout.

Předpoklady: - Přístup do DNS panelu pro avaxis.cz zone (registrar / Cloudflare) - SSH klíč na vm-gateway s sudo (root nebo passwordless sudo) - Public IP vm-gateway (TLS termination v apps-gateway.md arch)

Cíl: https://docs.avaxis.cz slouží MkDocs site z /srv/avax-docs/ na vm-gateway, HTTP→HTTPS redirect, Let's Encrypt SSL auto-renewal, CI push-triggered deploy přes .gitea/workflows/docs.yml.

Krok 1 — DNS A-record¶

V DNS panelu pro avaxis.cz:

Type:  A
Name:  docs
Value: <vm-gateway public IP>
TTL:   300

Ověř propagaci (může trvat ~5 min, někdy hodiny):

dig +short docs.avaxis.cz
# expected: <vm-gateway IP>

Krok 2 — Nginx vhost na vm-gateway¶

SSH na vm-gateway jako root:

sudo tee /etc/nginx/sites-available/docs-avaxis > /dev/null <<'EOF'
# Phase 1: HTTP-only (před certbot)
server {
    listen 80;
    server_name docs.avaxis.cz;

    root /srv/avax-docs;
    index index.html;

    # ACME challenge — certbot validation
    location /.well-known/acme-challenge/ {
        root /var/www/certbot;
    }

    # MkDocs static
    location / {
        try_files $uri $uri/ $uri.html =404;
    }

    # Optional: /advanced/ paths gate na user login (per spec sekce 8)
    # Zakomentováno do prvního deploye — odkomentuj až potřebuješ ACL.
    #
    # location ~ ^/advanced/ {
    #     auth_request /auth/check;
    #     error_page 401 = @login_redirect;
    #     try_files $uri $uri/ $uri.html =404;
    # }
    # location = /auth/check {
    #     internal;
    #     proxy_pass https://api.avaxis.cz/auth/me;
    #     proxy_pass_request_body off;
    #     proxy_set_header Content-Length "";
    #     proxy_set_header Authorization "Bearer $cookie_avax_token";
    # }
    # location @login_redirect {
    #     return 302 https://api.avaxis.cz/login?redirect=$request_uri;
    # }

    # Logy
    access_log /var/log/nginx/docs-avaxis-access.log;
    error_log  /var/log/nginx/docs-avaxis-error.log;
}
EOF

# Vytvořit data dir + restrictive owner
sudo mkdir -p /srv/avax-docs /var/www/certbot
sudo chown -R www-data:www-data /srv/avax-docs

# Enable site
sudo ln -sf /etc/nginx/sites-available/docs-avaxis /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Ověř HTTP přístup (před TLS):

curl -I http://docs.avaxis.cz/
# expected: 404 Not Found (nginx works, jen /srv/avax-docs je prázdný)

Krok 3 — Deploy user + SSH key¶

Vytvoř system user pro CI deploy (alternativně reuse existující deploy):

# Na vm-gateway
sudo useradd -m -s /bin/bash deploy
sudo usermod -aG www-data deploy
sudo chown -R deploy:www-data /srv/avax-docs

# SSH klíč (generování na avaxdev nebo lokálním PC)
# Na AVAXDEV nebo PC:
ssh-keygen -t ed25519 -f /tmp/avax-docs-deploy -N "" -C "avax-docs-ci"
cat /tmp/avax-docs-deploy.pub
# Zkopíruj public key

# Na VM-GATEWAY:
sudo -u deploy mkdir -p /home/deploy/.ssh
sudo -u deploy tee /home/deploy/.ssh/authorized_keys > /dev/null <<'EOF'
ssh-ed25519 AAAAC3Nz... avax-docs-ci
EOF
sudo -u deploy chmod 700 /home/deploy/.ssh
sudo -u deploy chmod 600 /home/deploy/.ssh/authorized_keys

Test rsync z avaxdev (jako sanity):

# Na avaxdev (rsync test)
echo "test" > /tmp/test-deploy.txt
rsync -e "ssh -i /tmp/avax-docs-deploy" /tmp/test-deploy.txt deploy@<vm-gateway>:/srv/avax-docs/
# Pokud OK, ověř na vm-gateway:
ls -la /srv/avax-docs/test-deploy.txt
rm /srv/avax-docs/test-deploy.txt  # cleanup

Krok 4 — Let's Encrypt SSL cert¶

# Na vm-gateway
sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx

# Vystavit cert (interactive — zadej email)
sudo certbot --nginx -d docs.avaxis.cz --redirect --email admin@avaxis.cz \
  --agree-tos --no-eff-email

# Certbot automaticky:
# - vystaví cert
# - upraví /etc/nginx/sites-available/docs-avaxis (add ssl + 301 redirect)
# - reload nginx
# - nastaví systemd timer pro auto-renewal (certbot.timer)

# Ověř HTTPS
curl -I https://docs.avaxis.cz/
# expected: 404 Not Found (TLS works)

# Plus auto-renewal smoke
sudo certbot renew --dry-run

Krok 5 — Gitea repo secrets¶

Otevři https://git.avaxis.cz/claudAI/avax-platform/settings/actions → Secrets → Add Secret (super_admin token paincelebrator):

Secret name	Hodnota
`DOCS_DEPLOY_HOST`	`<vm-gateway public IP nebo hostname>`
`DOCS_DEPLOY_USER`	`deploy`
`DOCS_DEPLOY_SSH_KEY`	Plný obsah `/tmp/avax-docs-deploy` (private key, vč. `-----BEGIN OPENSSH...`
`DOCS_DEPLOY_PORT`	`22` (volitelné, default v workflow)

⚠️ DOCS_DEPLOY_SSH_KEY musí být PLNÝ private key — všechny řádky včetně begin/end markerů. Nezapomenout final newline.

Krok 6 — Trigger first deploy¶

Po nastavení secrets vyvolat workflow ručně push (libovolný drobný docs change):

# Na PC / lokálně
cd ~/avax-platform
echo "" >> docs/index.md   # whitespace change, triggers paths filter
git add docs/index.md
git commit -m "trigger(docs): first production deploy after Phase 4 infra setup"
git push origin master

# Sleduj workflow
# https://git.avaxis.cz/claudAI/avax-platform/actions

Expected workflow log:

✅ Install Python + MkDocs
✅ MkDocs build — X HTML stránek
✅ Deploy (rsync → produkcni host)
   sending incremental file list
   index.html
   ...
   sent N KB
   total size is N KB
✅ Trigger RAG resync
✅ Cleanup

Po úspěšném deploy:

curl https://docs.avaxis.cz/
# expected: 200 OK + plný MkDocs HTML

Krok 7 — Smoke test¶

# Hlavní stránka
curl -sS -o /dev/null -w "HTTP %{http_code}\n" https://docs.avaxis.cz/

# User guide
curl -sS -o /dev/null -w "HTTP %{http_code}\n" https://docs.avaxis.cz/user-guide/

# Spec page
curl -sS -o /dev/null -w "HTTP %{http_code}\n" https://docs.avaxis.cz/spec/ai-helper/

# Search (MkDocs Material má /search.html)
curl -sS -o /dev/null -w "HTTP %{http_code}\n" https://docs.avaxis.cz/search.html

Všechno mělo by být 200. Pokud něco 404, check že rsync proběhl správně (ls /srv/avax-docs/ | wc -l by mělo být desítky souborů).

Krok 8 — Acl gate pro `/advanced/*` (volitelné, později)¶

Jakmile máš stable docs.avaxis.cz, můžeš zapnout auth gate pro některé páthy (např. /advanced/ pro vendor-internal docs, nebo /admin/). Odkomentuj location ~ ^/advanced/ v nginx vhostu + reload.

Auth flow: 1. User browseuje docs.avaxis.cz/advanced/secret-page.html 2. Nginx auth_request /auth/check → proxy api.avaxis.cz/auth/me 3. Pokud cookie avax_token validní → 200, dovolit 4. Pokud ne → 401 → redirect https://api.avaxis.cz/login?redirect=...

Cookie avax_token musí být set domain .avaxis.cz (sdílený mezi api a docs) — backend /auth/login při response set cookie s správným Set-Cookie: avax_token=...; Domain=.avaxis.cz; HttpOnly; Secure.

Rollback¶

Pokud Phase 4 deploy zlomí dev workflow (např. workflow zaplakat secret inject):

# Disable secrets (gitea UI)
# nebo:
# Push workflow change s `if: false` na deploy step

Dev docs.avaxdev.local zůstává funkční nezávisle na Phase 4 (jiný nginx vhost, jiný server).

Související¶

Spec: docs/spec/platform-docs.md sekce 5 fáze 2
Workflow: .gitea/workflows/docs.yml (Gitea)
Dev hosting: docs.avaxdev.local (live)
Apps-gateway: docs/spec/apps-gateway.md (vm-gateway TLS termination context)