skills/deploy-server/SKILL.md

name: deploy-server
description: Use this skill to provision or update a Welley server on a supported cloud (currently DigitalOcean) when the user asks to deploy a new instance or run a server update. Covers single-instance deployments and SSH-based updates, including interactive collection of missing credentials, SSH keys, domain, region, and sizing.

Nasadenie servera

Prehľad

Tento skill vytvorí na DigitalOcean jednoinštančný Welley stack a vie spustiť aktualizácie cez SSH. Agenta vedie k tomu, aby zistil chýbajúce vstupy, z určeného zdroja načítal dostupné parametre inštancií, vytvoril VM, nastavil hostiteľa, nasadil Welley príkazom wlycli deployment create a výsledok overil.

Názvy príkazov musia presne zodpovedať CLI:

  • wlycli deployment create
  • wlycli deployment update
  • wlycli deployment delete

Predvolené hodnoty (DigitalOcean)

  • Región: nyc3
  • Image: latest LTS available via API (zistite ho cez images?type=distribution)
  • Názov dropletu: náhodne vygenerovaný v tvare wlsly-<adjective>-<surname> (napr. wlsly-bright-hopper). Použite generátor názvov z úryvku v references/digitalocean.md. Ak vytvárate spravovanú databázu, dajte jej rovnaký názov.
  • Cieľový plán: Basic / Regular (Shared CPU)
  • Cieľová veľkosť: 2 vCPU / 4 GB RAM / 80 GB SSD / 4 TB prenosu (približne 24 $ mesačne)

Pravidlo pre zmenu predvolených hodnôt

Ak používateľ uvedie niektorú z predvolených hodnôt (región, image, názov dropletu, projekt, veľkosť), agent musí:

  1. Zopakovať zmenu doslova.
  2. Pred pokračovaním požiadať o potvrdenie.

Šablóna interaktívnych otázok

Pýtajte sa len na to, čo chýba. Použite presne tieto otázky, aby sa znížila nejednoznačnosť. Pýtajte sa po kolách. 1. kolo: najviac 2 otázky naraz. V 2. kole možno ponúknuť spoločnú možnosť „prijať všetky predvolené hodnoty“. Ak prostredie podporuje výber, ponúknite pri každej otázke 2 až 3 možnosti (A/B/C). Voľný text používajte, len keď je to nevyhnutné.

Otázky 1. kola (totožnosť a prístup):

  1. „Máte token API DigitalOcean, ktorý mám použiť, alebo mám počkať, kým ho zadáte?“
  2. „Akú doménu má tento server používať (napr. super-puper.example.com)? Máte kontrolu nad jej DNS?“
  3. „Máte už verejný kľúč SSH, ktorý mám použiť, alebo mám jeden vytvoriť a nahrať?“
  4. „Chcete tento droplet priradiť k existujúcemu projektu DigitalOcean? Ak áno, zadajte názov alebo ID projektu.“
  5. „Požiadavka na DNS: musíte vytvoriť záznamy A/AAAA pre <domain> a storage.<domain> (ak nepoužívate CDN). Stihnete to ešte pred spustením certbotu?“
  6. „Požiadavka na e-mailové DNS: doména z --smtp-from potrebuje záznamy SPF, DMARC a DKIM, inak sa pozvánky a potvrdzovacie e-maily novým príjemcom môžu potichu zahodiť. Máte ich nastavené, alebo vám mám vypísať záznamy, ktoré potrebuje váš poskytovateľ SMTP?“
  7. Ak sa používateľ pýta, kde získať token DO, pošlite mu tento odkaz:
https://cloud.digitalocean.com/account/api/tokens

Otázky 2. kola (veľkosť, umiestnenie a možnosti nasadenia):

  1. „Chcete predvolený región nyc3, alebo iný?“
  2. „Chcete predvolenú veľkosť (2 vCPU / 2 GB), alebo iný cieľ pre CPU/RAM?“
  3. „Mám použiť najnovší Ubuntu LTS dostupný v API, alebo konkrétnu verziu Ubuntu?“
  4. „Ktorého používateľa SSH máme po úvodnom nastavení používať (predvolene: wlsly)? Môžete nechať predvolenú hodnotu.“
  5. „Chcete spravovanú databázu Postgres, alebo mám použiť Postgres v pribalenom kontajneri?“
  6. Ak sa zvolí spravovaný Postgres: „Akú oblasť a veľkosť databázy mám použiť? Môžem predvoliť nyc3 a 1 vCPU / 2 GB.“
  7. Ak sa zvolí spravovaný Postgres: „Mám pokračovať vo vytvorení za mesačnú cenu uvedenú poskytovateľom?“
  8. „Zadajte, prosím, potrebné nastavenia SMTP (host, používateľ, heslo, odosielateľ). OTEL je voliteľný, zadajte ho, len ak ho potrebujete.“
  9. „E-mail správcu je pri vytvorení povinný. Zadajte ho teraz (prepínač: --email / -e). Ak ho nezadáte, dvakrát sa vás naň opýtam, aby sme ho potvrdili.“

Na urýchlenie zbierania vstupov ponúknite v 2. kole možnosť „prijať všetky predvolené hodnoty“.

Ak nejaká odpoveď chýba, opýtajte sa cielene (jedna alebo dve otázky).

Postup (DigitalOcean, jedna inštancia)

  1. Zistite potrebné vstupy (ak chýbajú, opýtajte sa).
  • Token API DigitalOcean
  • Názov alebo ID projektu (voliteľné; ak chýba alebo sa nenájde, použite predvolený projekt)
  • Región
  • Cieľová veľkosť inštancie (napr. 4 vCPU / 16 GB RAM)
  • Názov domény
  • Verejný kľúč SSH (alebo potvrdenie, že sa má jeden vytvoriť a zaregistrovať)
  • E-mail správcu pre prvé prihlásenie a obnovu hesla (pri vytvorení povinný; --email / -e). Ak chýba, opýtajte sa dvakrát a overte, že sa zhoduje.
  • Voliteľné: vlastné certifikáty TLS alebo certbot
  • Potvrdenie prístupu k DNS (musí byť možné vytvoriť záznamy A/AAAA pre <domain> a storage.<domain>, ak sa používa)
  1. Načítajte typy inštancií a vyberte veľkosť.
  • Na zobrazenie zoznamu a filtrovanie podľa CPU/RAM použite úryvok pre veľkosti z references/digitalocean.md.
  • Ak sa zhoduje viac možností, potvrďte výber s používateľom.

2b. Zistite slug image Ubuntu.

  • Zavolajte GET /v2/images?type=distribution&per_page=200 a vyfiltrujte Ubuntu.
  • Ak používateľ požiadal o konkrétnu verziu, overte, že jej slug existuje, a potvrďte ju.
  • Inak vyberte zo zoznamu najnovší slug LTS a pred vytvorením ho potvrďte s používateľom.
  1. Vytvorte droplet.
  • Použite priamo API DigitalOcean (doctl je voliteľný).
  • Image: uprednostnite ten, ktorý určil používateľ; inak vyberte najnovší LTS zo zoznamu z API.
  • Pripojte odtlačok kľúča SSH alebo vytvorte a nahrajte nový kľúč.
  • Zapnite monitoring.
  • Ak ste dostali názov alebo ID projektu, ale nenašiel sa, vytvorte droplet bez projektu (predvolený projekt).
  • Poznámka: spravovanú databázu možno vytvárať paralelne s dropletom.

Paralelné spracovanie

Agent by mal prekrývať nezávislé úlohy, aby skrátil celkový reálny čas:

  • Počas zbierania vstupov od používateľa (2. kolo) začnite vytvárať droplet, ak sú token, región, veľkosť, image a kľúč SSH už potvrdené.
  • Kým sa droplet vytvára, začnite vytvárať spravovaný Postgres (ak oň používateľ požiadal).
  • Kým droplet nabieha, zbierajte zvyšné vstupy (SMTP, OTEL, e-mail správcu).
  • Ak pre niektorý krok chýba kľúčový vstup, tento krok pozastavte a pokračujte inými úlohami, ktoré sa dajú robiť súbežne.
  • Ak sa DNS spravuje v DigitalOcean, vytvorte alebo aktualizujte záznamy A/AAAA hneď, ako bude známa IP dropletu (nečakajte na celý krok nasadenia).
  1. DNS a doména.
  • Opýtajte sa, či sa má DNS vytvoriť alebo aktualizovať v DigitalOcean, alebo ostane externé.
  • Ak používate DNS od DigitalOcean, vytvorte záznamy A/AAAA smerujúce na IP dropletu.
  1. Nastavte hostiteľa cez SSH.
  • Vytvorte používateľa bez práv roota (napr. wlsly), pridajte mu sudo a skopírujte autorizované kľúče SSH.
  • Odhláste sa z roota a pred pokračovaním sa znova prihláste ako používateľ bez práv roota.
  • Nainštalujte Docker a docker compose.
  • Stiahnite binárny súbor Welley CLI z AppStore a nastavte ho ako spustiteľný:
    • Základná URL: https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?develop=stable&platform=<os>/<arch>
    • Správnu hodnotu platform vyberte podľa OS a architektúry:
      • Linux x86_64: linux/amd64
      • Linux arm64: linux/arm64
      • macOS x86_64: darwin/amd64
      • macOS arm64: darwin/arm64
      • Windows x86_64: windows/amd64
    • Príklad (Linux x86_64):
      curl -fL 'https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?develop=stable&platform=linux/amd64' -o wlycli
chmod +x wlycli
    • Očakávané hlavičky odpovede obsahujú:
      • x-artifact-display-name: Welley CLI
      • x-artifact-full-name: social.wellesley.wlycli
      • x-artifact-kind: cli
      • x-artifact-platform: <os>/<arch>, napríklad linux/amd64
      • x-artifact-sha256: <sha256>
      • x-artifact-version: <version>
      • x-channel: develop
    • Pred inštaláciou radšej skontrolujte hlavičky požiadavkou HEAD a overte, že názov artefaktu, druh, platforma a kanál zodpovedajú požadovanému binárnemu súboru.
  • Overte binárny súbor CLI: spustite wlycli -v a wlycli deployment --help, aby ste potvrdili očakávané informácie o zostavení.
  1. Nasaďte Welley.
  • Spustite wlycli deployment create s potrebnými voľbami.
  • Použite predvolené nastavenia pre jednu inštanciu (bez externého Postgresu, kým o to používateľ nepožiada).
  • Ak používateľ chce spravovaný Postgres, vytvorte ho najprv (databáza DigitalOcean) a potom vrátený host, port, databázu, používateľa a heslo použite v prepínačoch --postgres-*.
  • Ak API alebo UI heslo používateľa databázy nevráti, pred spustením wlycli resetujte overenie používateľa databázy a získajte nové prihlasovacie údaje.
  • Neinteraktívne spustenia musia mať --email / -e, inak príkaz zlyhá.
  • --base-dir ukazuje na nadradený adresár; CLI podadresár projektu vytvorí samo.
  • CLI odmietne bežať, ak adresár projektu alebo kontajnery už existujú; pred ďalším pokusom je potrebné ich upratať.
  1. Certifikáty (povinné).
  • Predvolene: použite Certbot v režime standalone (neinteraktívne).
  • Používateľ musí pred spustením certbotu nasmerovať záznamy DNS A/AAAA pre doménu (a pre storage.<domain>, ak sa používa) na IP dropletu.
  • CLI podporuje --public-ip (prepíše zistenú IP) a --skip-dns-preflight, ak musíte kontrolu obísť.
  • Nikdy nepredpokladajte, že DNS je nastavené. Opýtajte sa a počkajte na výslovné potvrdenie.
  • Nikdy nepoužívajte --skip-dns-preflight, kým o to používateľ výslovne nepožiada.
  • Ak CDN nie je nastavené, certbot musí do žiadosti o certifikát zahrnúť aj storage.<domain>.
  • Samopodpísané certifikáty použite, len ak o ne používateľ výslovne požiada, a zadajte --self-signed-certs (samopodpísané certifikáty sa generujú v Go).
  • Dajte používateľovi pokyny na nastavenie DNS a počkajte na potvrdenie:
  • „Vytvorte záznamy A/AAAA tak, aby sa <domain> prekladala na IP dropletu.“
  • „Ak sa používa storage.<domain>, vytvorte záznam A/AAAA aj pre ňu.“
  • „Keď sa DNS rozšíri, dajte mi vedieť a budem pokračovať. Šírenie nevidím, kým ma nepožiadate o overenie prekladu.“
  • Agent môže šírenie DNS overiť aj sám pomocou ping -c 1 <domain> a porovnať IP s dropletom. Ak sa zhodujú, pokračujte.

7b. E-mailové DNS (SPF / DMARC / DKIM).

  • Poštu z domény bez SPF a DMARC Gmail a Outlook často zahodia, ak ide o príjemcov, ktorým z nej píšete prvýkrát, aj keď poskytovateľ SMTP hlási, že ju doručil.
  • deployment create vypíše Warning:, keď doména z --smtp-from nemá záznam SPF, alebo nemá záznam DMARC na _dmarc.<domain> ani v nadradenej doméne. Nasadenie neblokuje. Upozornenie nikdy neignorujte: ukážte ho používateľovi a dajte mu záznamy, ktoré má pridať:
    • <mail-domain> TXT v=spf1 include:<provider> ~all (presný include určuje poskytovateľ SMTP; zlúčte ho do existujúceho záznamu SPF, nikdy nepridávajte druhý)
    • _dmarc.<mail-domain> TXT v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain>
    • DKIM: záznamy <selector>._domainkey.<mail-domain>, ktoré poskytovateľ SMTP vygeneruje pri overení domény
  • Skontrolujte pomocou dig +short TXT <mail-domain> a dig +short TXT _dmarc.<mail-domain>.
  • CLI nevie skontrolovať DKIM (selektor je špecifický pre poskytovateľa). Vždy sa používateľa opýtajte, či je DKIM u poskytovateľa SMTP overený, aj keď create nevypísal žiadne upozornenie. Pri Amazon SES a podobných poskytovateľoch sa SPF kontroluje pre vlastnú doménu obálky poskytovateľa, takže DMARC môže prejsť len vďaka DKIM. V SES musí byť v časti Verified identities pri <mail-domain> stav DKIM Successful.
  1. Overte a podajte správu.
  • Skontrolujte docker ps a endpointy so stavom služieb.
  • Uveďte konečné údaje o pripojení a ďalšie kroky.

Aktualizácia cez SSH

Keď používateľ požiada o „aktualizáciu servera“:

  1. Opýtajte sa na cieľového hostiteľa alebo IP a na používateľa a kľúč SSH.
  2. Spustite wlycli deployment update --domain <domain> [--force-restart].
  3. Overte stav kontajnerov a Nginxu.

Zdroje

  • Úryvky a príklady pre API DigitalOcean: references/digitalocean.md.

Tajné údaje a ich prepínače

Pre tajné údaje použite tieto názvy prepínačov:

  • Host SMTP: --smtp-host
  • Používateľ SMTP: --smtp-user
  • Heslo SMTP: --smtp-password
  • Odosielateľ SMTP: --smtp-from
  • Endpoint OTEL: --otel-endpoint
  • Hlavičky OTEL: --otel-headers

Minimálny príkaz na vytvorenie

Povinné prepínače:

  • --domain
  • --email
  • --smtp-host
  • --smtp-user
  • --smtp-password
  • --smtp-from

Minimálny príklad:

wlycli deployment create \
  --domain example.com \
  --email admin@example.com \
  --smtp-host smtp.example.com \
  --smtp-user user \
  --smtp-password pass \
  --smtp-from noreply@example.com

Predvolené hodnoty spravovaného Postgresu (DigitalOcean a CLI)

Pri spravovanom Postgrese od DigitalOcean sa nespoliehajte na predvolené hodnoty CLI. Všetky prepínače --postgres-* nastavte výslovne:

  • Typické predvolené hodnoty DO:
    • Port: 25060
    • Databáza: defaultdb
    • Používateľ: doadmin
  • Predvolené hodnoty CLI (ak prepínače vynecháte):
    • Port: 5432
    • Databáza: wlsly
    • Používateľ: wlsly

Poznámky k používaniu CLI

  • Kontrola verzie: wlycli -v alebo wlycli --version (prepínač). Podpríkaz version neexistuje.
  • --base-dir použite, len ak chcete iné než predvolené umiestnenie (predvolené je ~/.welley). CLI adresár vytvorí, ak na to má oprávnenie.
  • Neinteraktívne spustenia cez SSH majú obsahovať --email a všetky potrebné prepínače, aby sa predišlo otázkam.
  • Ak používateľ dodá binárny súbor CLI na serveri (napr. ~/wcli), použite ho priamo. Nepresúvajte ho, kým o to nepožiada.
  • Úryvky z references/digitalocean.md kopírujte doslova pri všetkých volaniach API DO. Neprepisujte, neupravujte ani neimprovizujte spracovanie v Pythone: aj malé zmeny (napr. escapovanie, úvodzovky) môžu v rôznych shelloch zlyhať.
  • Vzdialené skripty cez SSH: Vždy používajte ssh host 'bash -s' << 'EOF' (heredoc v úvodzovkách). Nikdy nepoužívajte ssh host "..." s dvojitými úvodzovkami: zsh rozbalí $(...) a [...] lokálne ešte pred odoslaním na vzdialeného hostiteľa.

Obnova po zlyhaní

Ak deployment create zlyhá a potrebujete to skúsiť znova:

  • Na upratanie použite wlycli deployment delete --domain <domain> --yes-please-delete-all-the-data.
  • Príkaz delete sa pokúsi upratať súbory vlastnené rootom cez kontajner. Ak to stále zlyhá, odstráňte adresár projektu v --base-dir s vyššími oprávneniami a spustite príkaz znova.

Predbežný test portu 80 (voliteľné)

Ak certbot zlyhá, pred ďalším spustením otestujte dostupnosť portu 80:

docker run --rm -d -p 80:80 --name test-http nginx:alpine
curl -s http://<domain>:80
docker rm -f test-http

Ďalšie dokumenty