Lokální vývoj na macOS a Windows

Návod pro toho, kdo chce Shipard rozjet na vlastním počítači a Linux server nikdy nespravoval. Na konci máš běžící Shipard a v prohlížeči jeho vývojářský dashboard.

Shipard běží na Ubuntu. Na Macu ho proto spustíš ve virtuálním stroji (Multipass), na Windows ve WSL — v obou případech je to Ubuntu uvnitř tvého počítače. Instalaci udělá jeden skript, scripts/dev-bootstrap.sh.

Máš linuxový server, nebo Ubuntu přímo v počítači? Tenhle návod nepotřebuješ — postup pro Linux je v linux-install.md. Bootstrap jen spouští jeho kroky za sebou.

1. Co budeš potřebovat

• Mac (Apple silicon i Intel), nebo Windows 10 (verze 21H2 a novější) či Windows 11
• asi 20 GB místa na disku a 4 GB paměti pro Ubuntu
• připojení k internetu — instalace stahuje balíčky a chvíli trvá
• účet na GitHubu jen tehdy, když chceš přispívat; na vyzkoušení potřeba není

Zdrojový kód žije uvnitř Ubuntu v adresáři ~/sw/shpd, ne na disku Macu nebo Windows. Soubory sdílené z hostitele jsou pomalé a rozbíjejí práva, na kterých instalace stojí.

2. macOS — Multipass

1. Nainstaluj Multipass podle oficiální stránky.

2. Stáhni konfiguraci — v aplikaci Terminál:

curl -fsSLO https://raw.githubusercontent.com/shipard/shipard/stable/scripts/multipass/shipard-dev.yaml

3. Vlož svůj veřejný SSH klíč (jen když chceš napojit Clauda v chatu — kapitola 5; jinak krok přeskoč). Klíč pro vývojový stroj vytvoř zvlášť a na dotaz na heslo (passphrase) jen stiskni Enter — remote-dev-bridge klíč s heslem neumí:

ssh-keygen -t ed25519 -f ~/.ssh/shipard_dev

Pokud klíč ~/.ssh/shipard_dev už máš, ssh-keygen se zeptá na přepsání — odpověz n, stávající klíč stačí.

Pak klíč vlož do shipard-dev.yaml — tenhle příkaz nahradí zástupný řádek obsahem veřejného klíče a druhý výsledek vypíše:

sed -i '' "s|ssh-ed25519 AAAA_NAHRAD_TENTO_RADEK_SVYM_VEREJNYM_KLICEM|$(cat ~/.ssh/shipard_dev.pub)|" shipard-dev.yaml
grep -A1 'ssh_authorized_keys:' shipard-dev.yaml

Pod ssh_authorized_keys: má být - ssh-ed25519 AAAA… s tvým klíčem, ne zástupný text AAAA_NAHRAD_….

Když chceš soubor upravit ručně: open -e shipard-dev.yaml (TextEdit). Na řádku - ssh-ed25519 AAAA_NAHRAD_TENTO_RADEK_SVYM_VEREJNYM_KLICEM nahraď všechno za pomlčkou obsahem souboru ~/.ssh/shipard_dev.pub; pomlčku a odsazení nech. Vkládá se vždy soubor .pub — soubor bez přípony je soukromý klíč a nikam se nekopíruje.

4. Spusť virtuální stroj:

multipass launch 26.04 --name shipard --cpus 2 --memory 4G --disk 20G \
    --timeout 1800 --cloud-init shipard-dev.yaml

Příkaz čeká, dokud instalace uvnitř nedoběhne. Volba --timeout je potřeba: instalace trvá déle než výchozích 5 minut, po kterých by Multipass ohlásil chybu, přestože stroj dál pracuje.

Síť nech výchozí. Nepřidávej --network ani --bridged. Vývojářský dashboard nemá přihlášení — ve výchozí síti Multipassu je dostupný jen z tvého počítače, v místní síti by ho viděl kdokoli.

5. Sleduj průběh — v druhém okně Terminálu:

multipass exec shipard -- tail -f shipard-bootstrap.log

Hotovo je, když výpis skončí souhrnem ==> Hotovo — vývojové prostředí Shipardu běží. s adresou dashboardu (Ctrl+C sledování ukončí). Totéž řekne multipass exec shipard -- cloud-init status --wait — vypíše status: done.

6. Otevři dashboard. Adresu stroje ukáže řádek IPv4:

multipass info shipard

V prohlížeči otevři http://<IPv4>/_dev/.

Příkazy, které se budou hodit:

3. Windows — WSL

1. Nainstaluj Ubuntu. Otevři PowerShell jako správce:

wsl --install Ubuntu-26.04

Když si instalace řekne o restart Windows, restartuj; kdyby se pak Ubuntu neotevřelo samo, spusť příkaz znovu. Dostupné distribuce vypíše wsl --list --online.

2. První spuštění. Ubuntu se zeptá na jméno a heslo nového uživatele. Heslo si zapamatuj — bude ho chtít sudo.

3. Spusť bootstrap — v okně Ubuntu:

curl -fsSL https://raw.githubusercontent.com/shipard/shipard/stable/scripts/dev-bootstrap.sh | bash

Skript se na začátku jednou zeptá na heslo a pak běží sám. Skončí souhrnem ==> Hotovo — vývojové prostředí Shipardu běží.

Kdyby Ubuntu hlásilo curl: command not found, doinstaluj ho (sudo apt update && sudo apt install -y curl) a příkaz zopakuj.

4. Otevři dashboard v prohlížeči ve Windows: http://localhost/_dev/.

5. Volitelně: SSH pro Clauda v chatu (kapitola 5). Klíč vytvoř ve Windows — v PowerShellu, na dotaz na heslo (passphrase) jen stiskni Enter:

ssh-keygen -t ed25519

Pak v okně Ubuntu spusť bootstrap znovu s volbou --with-ssh (místo <uživatel> dosaď své jméno ve Windows):

bash ~/sw/shpd/scripts/dev-bootstrap.sh --with-ssh \
    --ssh-pubkey-file /mnt/c/Users/<uživatel>/.ssh/id_ed25519.pub

SSH pak naslouchá na portu 2222 a pustí jen držitele klíče, heslem se přihlásit nedá. Obojí jde i najednou při první instalaci: curl -fsSL … | bash -s -- --with-ssh --ssh-pubkey-file ….

Na co si dát pozor:

• Checkout nech v Ubuntu (~/sw/shpd), nikdy v /mnt/c/….
• Při práci nech okno Ubuntu otevřené. WSL může distribuci bez otevřeného terminálu po chvíli zastavit — dashboard i SSH pak přestanou odpovídat, dokud Ubuntu znovu neotevřeš.
• Bootstrap potřebuje WSL 2 se systemd. Nové instalace Ubuntu ho mají zapnutý; když skript hlásí, že systemd neběží, napíše i co nastavit.

4. První zdroj dat

Zdroj dat je jedna firma — vlastní databáze a soubory. Založíš ho v dashboardu tlačítkem + New DS; zaškrtni Seed test data, ať máš rovnou s čím pracovat. Kroky jednotlivě a co dělat dál: dev-daily.md (oddíl 2).

5. Napojení na Clauda

V projektu se pracuje s AI asistentem ve dvou rolích — popisuje je ai-workflow.md.

Claude Code běží přímo uvnitř Ubuntu, v adresáři ~/sw/shpd. Na běžnou práci (implementace, testy) stačí on. Bootstrap ho neinstaluje — instalace, přihlášení a první kroky jsou v claude-code-intro.md.

Claude v chatu (návrh, zadání, ověřování) se k Ubuntu připojuje přes SSH aplikací remote-dev-bridge na tvém počítači — instalace a napojení do desktopové aplikace Claude v ai-workflow.md §7. V nastavení mostu přidej server a projekt s ID shipard:

Na konci bootstrapu s --with-ssh jsou tyhle údaje vypsané v souhrnu. Po uložení se zeptej Clauda v chatu na hostname stroje — ověříš tím, že projekt míří na správný stroj.

Na macOS použij podepsané vydání ze stránky Releases. Vlastní nepodepsaný build končí chybou „No route to host“ — macOS mu nedá oprávnění Místní síť, bez kterého se k virtuálnímu stroji nedostane.

6. Každodenní práce

Terminál v Ubuntu: na Macu multipass shell shipard, ve Windows okno Ubuntu. Kód je v ~/sw/shpd.

Co dělat po git pull, kdy spustit ds-upgrade-all a kde je přehled příkazů, říká dev-daily.md — stejně pro Multipass, WSL i Linux server. Bootstrap zapnul git hooky, takže se závislosti a frontend po git pull aktualizují samy.

Bootstrap jde kdykoli spustit znovu — hotové kroky jen ověří. Stejně se doplní volitelné části:

bash ~/sw/shpd/scripts/dev-bootstrap.sh --with-render

Checkout je stažený přes HTTPS. Až budeš chtít posílat změny, přepni ho podle dev-daily.md (oddíl 5).

AI na lokální instalaci

K vytěžení dokladu z Dashboardu i k asistentovi stačí klíč AI backendu — žádný další runtime ani démon. Z adresáře zdroje dat:

cd /opt/shipard/data-sources/<id>
shpd-ds ai-backend-set-key --backend default   # klíč zadáš skrytě na výzvu

Pak nahraj doklad (PDF, obrázek účtenky) na Dashboardu. Analýza běží jako odpojený proces shpd-ds mail-analyze a zhruba do minuty je výsledek v detailu zprávy; víc dokladů naráz odbaví týž proces postupně (po dokončení zprávy bere další z fronty), cron k tomu není potřeba. Běhy s tokeny, cenou a trváním vidíš v tabu Analýzy. Bez klíče zpráva zůstane „Ve frontě“ — runner zapíše jedno varování do analysis.log a skončí; na stroji s cronem se varování sweepu opakuje každou minutu. Limit souběhu a vypnutí (ai.analysis.maxConcurrent) popisuje operations/production.md §10.

7. Něco nefunguje?

Bootstrap skončil chybou. Poslední řádky říkají, ve kterém kroku (==> Bootstrap selhal v kroku: …), nad nimi je příčina. Na Macu je výpis v souboru:

multipass exec shipard -- tail -n 50 shipard-bootstrap.log

Po odstranění příčiny spusť bootstrap znovu — v terminálu uvnitř Ubuntu bash ~/sw/shpd/scripts/dev-bootstrap.sh, a když checkout ještě neexistuje, příkazem curl … | bash z kapitoly 3 (krok 3).

multipass launch hlásí „timed out“. Stroj běží a instalace pokračuje — sleduj ji podle kroku 5 v kapitole 2.

Dashboard se neotevře. Na Macu ověř adresu a stav stroje (multipass info shipard), ve Windows měj otevřené okno Ubuntu.

Aplikace hlásí chybu, nebo to pořád nejde? Zdravotní kontrola shpd-server doctor, oprava práv, logy a kam se obrátit — dev-daily.md (oddíl 7). K hlášení o bootstrapu přilož poslední řádky jeho výpisu.