Začínáme

Požadavky

• PHP 8.3 nebo novější s rozšířeními mysqli, json a mbstring.
• MySQL 8 nebo MariaDB 10.6 a novější.
• Apache s mod_rewrite nebo Nginx s PHP-FPM.
• Composer 2. Docker je volitelný.

Aplikace vyžaduje balíček Composeru wbengine/wbengine. Framework nemá další závislosti v Composeru; template engine i parser Markdownu jsou jeho součástí. Přesné požadavky na PHP ověřte v metadatech balíčku.

Rychlé spuštění v Dockeru

git clone https://github.com/rrsoftcz/wbengine-skeleton-app
cd wbengine-skeleton-app
docker compose up --build

Otevřete http://localhost:8080. Při startu webový kontejner spustí bin/wbe install: vytvoří a ověří Settings.json, připraví složku kompilovaných šablon a nainstaluje uzamčené závislosti. Demo účet je admin@example.com, heslo changeme. Před zpřístupněním webu heslo změňte.

Ruční instalace

Příkaz php bin/wbe install vytvoří a ověří nastavení, připraví src/View/Compiled a nainstaluje závislosti podle composer.lock. Oznámí chybný JSON, nečitelná nastavení, nezapisovatelnou cache šablon i chyby Composeru. Nepoužívejte chmod 777; právo zápisu přidělte uživateli PHP webserveru. Pro lokální diagnostiku nastavte debug na true nebo WBENGINE_DEBUG=1. Před nasazením debug vypněte.

php bin/wbe install

Vytvořte databázi, importujte schemas/wbengine_skeletone_app_mysql_template.sql a potom schemas/wbengine_skeletone_app_mysql_template_content.sql. Nastavte src/Config/Settings.json a jako kořen webu použijte public/.

Řešení chyb instalace a výjimek

Při vývoji nastavte v Settings.json debug na true. Šablona WBengine zobrazí typ výjimky, zprávu, soubor, řádek a trasu volání. Pokud nastavení chybí nebo obsahuje neplatný JSON, použijte WBENGINE_DEBUG=1 pouze v soukromém vývojovém prostředí. Ladicí výstup nikdy nezpřístupňujte veřejně. Produkční stránka zobrazí bezpečné vysvětlení a referenční kód; úplnou výjimku najdete v PHP nebo kontejnerovém error logu pod stejným kódem.

Před upgradem databázi zálohujte a dosud nepoužité skripty v schemas/migrations/ aplikujte v pořadí. Docker importuje schéma a seed pouze při vytvoření nového databázového volume. Rebuild webového image existující databázi nezmění.

Čisté nasazení na VPS pomocí Dockeru

Tento postup je určený pro nový, prázdný server s Ubuntu. Vytvoří novou databázi z aktuálního schématu a obsahu v tomto repozitáři. Nekopíruje databázi z vývojového ani již provozovaného webu. Instalační skript pro čistou instalaci nespouštějte nad existující databází. Při upgradu existujícího webu nejprve vytvořte zálohu a postupujte podle postupu pro upgrade.

PHP aplikace a MySQL poběží v Dockeru. Nginx a Certbot poběží přímo na serveru Ubuntu. Aplikační port bude dostupný pouze přes 127.0.0.1:8080 a MySQL nebude publikováno na port serveru. Volitelná administrace WBengine Admin je samostatná aplikace SvelteKit a tento postup ji neinstaluje. Může zůstat na vývojovém počítači a připojit se přes samostatně nastavenou integraci API v2.

1. Připravte DNS a firewall

Nasměrujte www.wbengine.org na IPv4 adresu VPS. Ve firewallu povolte příchozí SSH na portu 22 a webový provoz na portech 80 a 443. Doména wbengine.org může dál přesměrovávat na www ze svého současného DNS hostingu. Přiložená konfigurace Nginx obsluhuje www.wbengine.org.

2. Nainstalujte Docker

Nainstalujte Docker Engine a plugin Docker Compose podle oficiálního návodu pro Ubuntu. Na hostiteli není potřeba PHP ani Composer. PHP, Composer a MySQL poskytují aplikační kontejnery.

3. Vytvořte čistou aplikaci a databázi

Nainstalujte Git, OpenSSL, Nginx a Certbot, potom naklonujte repozitář a spusťte produkční instalátor:

apt-get update
apt-get install -y git openssl nginx certbot
git clone https://github.com/rrsoftcz/wbengine-skeleton-app.git /opt/wbengine-skeleton-app
cd /opt/wbengine-skeleton-app
./bin/setup-production.sh https://www.vase-domena.cz

Instalátor přijme veřejnou HTTPS adresu webu jako argument, nastaví bránu Docker sítě jako důvěryhodnou proxy pro HTTPS hlavičky předávané z Nginx na hostiteli, na serveru vytvoří soukromá hesla databáze, sestaví produkční PHP image, naplní nový svazek MySQL schématem a obsahem, vytvoří tabulky API a analytiky a nahradí veřejně známé demo heslo náhodným nepoužitelným heslem. Soubory .env a src/Config/Settings.json chraňte jako tajné. Sběr vlastní analytiky zůstane vypnutý. Skript nepřenáší data z jiné databáze.

4. Nastavte HTTPS v Nginx

Vytvořte webroot ACME a zapněte dočasnou HTTP konfiguraci, aby Let's Encrypt ověřil doménu:

install -d -m 755 /var/www/letsencrypt
ln -sfn /opt/wbengine-skeleton-app/deploy/nginx/www.wbengine.org-http.conf /etc/nginx/sites-enabled/www.wbengine.org.conf
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl reload nginx
certbot certonly --webroot -w /var/www/letsencrypt -d www.wbengine.org

Po vydání certifikátu přepněte na TLS reverse proxy a ověřte obnovu:

ln -sfn /opt/wbengine-skeleton-app/deploy/nginx/www.wbengine.org.conf /etc/nginx/sites-enabled/www.wbengine.org.conf
nginx -t && systemctl reload nginx
certbot renew --dry-run --no-random-sleep-on-renew

5. Ověřte a aktualizujte web

Zkontrolujte veřejný web a stav obou kontejnerů:

curl -I https://www.wbengine.org/
docker compose -f docker-compose.production.yml ps
docker compose -f docker-compose.production.yml logs --tail=100 web db

Při pozdější aktualizaci aplikace stáhněte schválený commit a znovu sestavte webový image:

git pull --ff-only
docker compose -f docker-compose.production.yml up -d --build --wait

Databázový svazek zůstává zachovaný při sestavení nového image. Databázové aktualizace nové verze použijte jednou po záloze (viz stránka Nasazení). Nikdy veřejně nevystavujte port MySQL 3306. Kompletní postup je také v produkčním návodu repozitáře.

Uživatelé a první přihlášení

Každý web na WBengine ukládá účty do tabulky cms_users. Uživatel má jednu ze tří rolí: user (přihlásí se a používá profil), editor a admin. Role se čte z databáze při každém oprávněném požadavku, takže změna nebo smazání účtu platí okamžitě. Veřejná registrace neexistuje: účty se spravují nástrojem příkazové řádky bin/wbe.

Co obsahuje čistá instalace

• Lokální Docker (docker compose up): seed obsahuje demo účet admin@example.com se zveřejněným heslem changeme. Používejte jej jen na vlastním počítači.
• Produkce (bin/setup-production.sh): instalátor nahradí demo heslo náhodným, které nikdo nezná. Dokud nevytvoříte správce, nemůže se nikdo přihlásit.

Vytvoření prvního správce

Příkaz spusťte uvnitř webového kontejneru (u lokálního stacku docker compose exec web ..., v produkci docker compose -f docker-compose.production.yml exec web ..., bez Dockeru prostě php bin/wbe ...):

docker compose -f docker-compose.production.yml exec web php bin/wbe user:create --email=vy@vase-domena.cz --role=admin

Příkaz se na heslo zeptá dvakrát a nezobrazuje je. Heslo se nikdy nepřijímá jako argument ani proměnná prostředí, takže se nedostane do historie shellu ani do seznamu procesů. Pro automatizaci pošlete jediný řádek na standardní vstup (bez terminálu, proto exec -T):

printf '%s\n' "$HESLO" | docker compose -f docker-compose.production.yml exec -T web php bin/wbe user:create --email=vy@vase-domena.cz --role=admin

Poté se přihlaste na /login/ e-mailovou adresou a zvoleným heslem.

Odstranění demo účtu

bin/wbe user:delete --example --dry-run
bin/wbe user:delete --example

První příkaz jen vypíše účty. Druhý smaže každý účet, jehož e-mail patří do rezervované příkladové domény (example.com, example.org, example.net a jejich subdomény a domény nejvyšší úrovně .example, .test, .invalid a .localhost). Odmítne se provést, pokud by nezůstal žádný jiný správce, proto nejdřív vytvořte vlastního správce.

Výpis uživatelů, změna hesla, smazání uživatele

bin/wbe user:list
bin/wbe user:password --email=vy@vase-domena.cz
bin/wbe user:delete --email=nekdo@vase-domena.cz

Zapomenuté heslo se obnoví příkazem user:password, který zároveň ukončí webové relace uživatele. Posledního správce nelze smazat. Žádný z příkazů nevypisuje heslo ani jeho hash.

Další krok

Pro správu tohoto webu z centrální administrace WBengine Admin viz stránka Centrální administrace, část Připojení webu krok za krokem. Vyžaduje účet s rolí admin. Instalaci a provoz samotné administrace popisuje tatáž stránka, část Instalace a nastavení.