Xamma Derived je samostatně nasaditelná distribuce publikačního systému Xamma určená pro podcasty, články, galerie a správu obsahu ve Studiu. Tento návod popisuje celé nasazení od rozbalení balíku přes Apache, HTTPS a databázi až po vytvoření prvního administrátora a API přihlašovacího klíče. Vychází z reálného nasazení na Debianu s Apachem, PHP 8.4 a MariaDB.

V příkladech používám projekt /mnt/flash1/project/xamma-derived, HTTPS port 4438, databázi xamma_derived a lokální databázový účet rpi1_local. Tyto hodnoty si přizpůsobte svému serveru. Hesla, hodnotu APP_KEY ani API klíč nikdy nevkládejte do veřejného článku, repozitáře nebo běžného logu.

1. Co balík obsahuje a co vyžaduje

Veřejným kořenem projektu je výhradně adresář public. Zdrojové kódy, konfigurace, soubor .env, šablony a privátní úložiště musí zůstat mimo veřejný kořen. Balík vyžaduje PHP 8.2 nebo novější, rozšíření PDO, PDO MySQL, Fileinfo, JSON a OpenSSL, webový server Apache 2.4 s moduly rewrite, headers a ssl a databázi MySQL nebo MariaDB.

PROJECT=/mnt/flash1/project/xamma-derived
PUBLIC=$PROJECT/public
PORT=4438

Po rozbalení zkontrolujte základní soubory:

test -f "$PROJECT/composer.json"
test -f "$PROJECT/vendor/autoload.php"
test -f "$PROJECT/bootstrap/app.php"
test -f "$PUBLIC/index.php"
test -f "$PUBLIC/.htaccess"

2. Ověření PHP a projektu

Než začnete měnit Apache, ověřte verzi PHP, syntaxi vstupních souborů, Composer autoloader a dodaný smoke test:

php -v
php -m | grep -E 'PDO|pdo_mysql|fileinfo|json|openssl'
php -l "$PUBLIC/index.php"
php -l "$PROJECT/bootstrap/app.php"
cd "$PROJECT"
composer validate --no-interaction --no-check-publish
php tests/smoke.php

Smoke test může přeskočit databázovou část, pokud není nastaveno testovací PDO připojení. To při prvním spuštění není chyba. Aplikace je navržena tak, aby bez databáze zobrazila instalační stránku místo obecné chyby serveru.

3. Nastavení vlastníka a zapisovatelných adresářů

Apache obvykle běží jako uživatel www-data. Zdrojové soubory mu stačí číst, ale musí zapisovat do privátního úložiště a do adresářů pro nahrávaná média.

sudo chgrp -R www-data "$PROJECT"
sudo chmod -R g+rX "$PROJECT"
sudo find "$PROJECT" -type d -exec chmod g+s {} +

for DIR in \
    "$PROJECT/storage/cache" \
    "$PROJECT/storage/logs" \
    "$PROJECT/storage/sessions" \
    "$PROJECT/public/uploads/audio" \
    "$PROJECT/public/uploads/images"
do
    sudo install -d -o zbynek -g www-data -m 2770 "$DIR"
    sudo chmod -R u+rwX,g+rwX,o-rwx "$DIR"
done

Práva ověřte přímo jako uživatel Apache:

sudo -u www-data touch "$PROJECT/storage/cache/.test" && sudo rm "$PROJECT/storage/cache/.test"
sudo -u www-data touch "$PROJECT/storage/sessions/.test" && sudo rm "$PROJECT/storage/sessions/.test"

Chybná práva se typicky projeví chybou 500, nemožností vytvořit session, cache nebo log. Chyba 403 naopak většinou znamená chybný DocumentRoot, neprůchozí práva některého nadřazeného adresáře nebo zákaz v konfiguraci Apache.

4. Zapnutí potřebných modulů Apache

sudo a2enmod ssl
sudo a2enmod rewrite
sudo a2enmod headers
sudo apache2ctl configtest

Výsledek posledního příkazu musí být Syntax OK.

5. HTTPS virtual host na samostatném portu

V tomto příkladu aplikace běží na portu 4438. Do /etc/apache2/ports.conf přidejte pouze jeden řádek, pokud tam ještě není:

Listen 4438

Vytvořte soubor /etc/apache2/sites-available/xamma-derived-4438.conf:

<IfModule mod_ssl.c>
<VirtualHost *:4438>
    ServerName 46.13.178.180
    ServerAlias 192.168.1.131 rpi1

    DocumentRoot /mnt/flash1/project/xamma-derived/public
    DirectoryIndex index.php

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/xamma-derived-4438.crt
    SSLCertificateKeyFile /etc/ssl/private/xamma-derived-4438.key

    <Directory /mnt/flash1/project/xamma-derived/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/xamma-derived-4438-error.log
    CustomLog ${APACHE_LOG_DIR}/xamma-derived-4438-access.log combined
</VirtualHost>
</IfModule>

Nejdůležitější je, aby DocumentRoot ukazoval do public, nikoli do kořene projektu.

6. Certifikát pro testovací nasazení

Pro lokální nebo dočasné testování lze vytvořit self-signed certifikát. Pro veřejný produkční web použijte důvěryhodný certifikát, například od Let's Encrypt. Self-signed certifikát vyvolá v prohlížeči bezpečnostní varování.

sudo openssl req \
    -x509 \
    -nodes \
    -newkey rsa:2048 \
    -sha256 \
    -days 825 \
    -keyout /etc/ssl/private/xamma-derived-4438.key \
    -out /etc/ssl/certs/xamma-derived-4438.crt \
    -subj "/C=CZ/O=Xamma Derived/CN=46.13.178.180" \
    -addext "subjectAltName=IP:46.13.178.180,IP:192.168.1.131,DNS:rpi1" \
    -addext "basicConstraints=critical,CA:FALSE" \
    -addext "keyUsage=critical,digitalSignature,keyEncipherment" \
    -addext "extendedKeyUsage=serverAuth"

sudo chmod 600 /etc/ssl/private/xamma-derived-4438.key
sudo chmod 644 /etc/ssl/certs/xamma-derived-4438.crt

Hodnota CA:FALSE je důležitá: certifikát je serverový certifikát, nikoli certifikační autorita.

7. Zapnutí webu, firewall a první test

sudo a2ensite xamma-derived-4438.conf
sudo apache2ctl configtest
sudo systemctl reload apache2
sudo ufw allow 4438/tcp

Potom ověřte odpověď serveru:

curl -k -I https://46.13.178.180:4438/

Před nastavením databáze má aplikace vrátit HTTP 200 a zobrazit stránku Installation guide s informací, že databáze zatím není připravena. To je očekávaný bezpečný první start.

8. Vytvoření souboru .env

Soubor .env musí ležet v kořeni projektu, tedy vedle composer.json, a nesmí být veřejně dostupný:

cd /mnt/flash1/project/xamma-derived
cp .env.example .env
chmod 640 .env

Základní konfigurace může vypadat takto:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://46.13.178.180:4438
APP_NAME="Xamma Podcast"
APP_TIMEZONE=Europe/Prague

APP_KEY=SEM_VLOZTE_NAHODNY_RETEZEC_ALESPON_32_ZNAKU

DB_DSN="mysql:host=127.0.0.1;port=3306;dbname=xamma_derived;charset=utf8mb4"
DB_USER=rpi1_local
DB_PASSWORD=SEM_VLOZTE_HESLO

SESSION_NAME=xamma_session
SESSION_LIFETIME=7200

APP_KEY musí mít nejméně 32 znaků a musí být pro každé nasazení jedinečný. Bezpečnou hodnotu lze vygenerovat příkazem:

openssl rand -hex 32

Změna APP_KEY později zneplatní dříve zašifrované API přihlašovací údaje. Hodnotu proto nejprve definitivně nastavte a teprve potom generujte API credential.

9. Databáze a účty

V našem nasazení jsme použili databázi xamma_derived, lokální účet rpi1_local a vzdálený účet rpi1_remote. Účty už existovaly, takže jsme jim pouze přidělili práva:

CREATE DATABASE IF NOT EXISTS xamma_derived
    CHARACTER SET utf8mb4
    COLLATE utf8mb4_unicode_ci;

GRANT ALL PRIVILEGES ON xamma_derived.* TO 'rpi1_local'@'localhost';
GRANT ALL PRIVILEGES ON xamma_derived.* TO 'rpi1_local'@'127.0.0.1';
GRANT ALL PRIVILEGES ON xamma_derived.* TO 'rpi1_remote'@'%';
FLUSH PRIVILEGES;

Vzdálený účet s hostitelem % zpřístupňuje databázi z libovolné adresy, pokud tomu nebrání firewall. V produkci je bezpečnější omezit hostitele i firewall na konkrétní IP adresu.

10. Import databázových tabulek

Balík obsahuje tři SQL soubory. Pokud používáte vlastní název databáze xamma_derived, databázi vytvořte ručně podle předchozího kroku a importujte modulová schémata přímo do ní:

cd /mnt/flash1/project/xamma-derived

mysql -u root -p xamma_derived < database/10-main-module.sql
mysql -u root -p xamma_derived < database/20-media-module.sql

Soubor 00-create-database.sql v původním balíku může vytvářet databázi s výchozím názvem xamma. Pokud chcete používat jiný název, nespouštějte jej beze změny. Vždy zkontrolujte jeho obsah nebo databázi vytvořte vlastním příkazem.

Po importu zkontrolujte tabulky:

mysql -u root -p -e \
"SELECT TABLE_NAME
 FROM information_schema.TABLES
 WHERE TABLE_SCHEMA='xamma_derived'
 ORDER BY TABLE_NAME;"

11. Vytvoření prvního administrátora

Administrátor se vytváří až po dokončení databázového schématu:

cd /mnt/flash1/project/xamma-derived
php bin/create-admin publisher@example.com "Jméno vydavatele"

Skript si vyžádá heslo interaktivně, takže heslo nemusí být součástí příkazu ani historie shellu. Použijte alespoň 12 znaků. Pokud příkaz hlásí chybějící tabulku nebo selhání připojení, vraťte se ke konfiguraci DB_DSN, uživateli, heslu a importu obou SQL schémat.

12. Vytvoření API přihlašovacího klíče

API přihlášení používá dvě různé tajné hodnoty:

• APP_KEY v souboru .env, nejméně 32 znaků;
• samotný API přihlašovací klíč, nejméně 24 znaků.

Nejdříve vygenerujte dlouhý náhodný klíč:

openssl rand -hex 24

Potom spusťte generátor se dvěma argumenty: API klíčem a e-mailem existujícího administrátora:

php bin/create-api-key \
    'SEM_VLOZTE_API_KLIC_NEJMENE_24_ZNAKU' \
    publisher@example.com

Skript vypíše řádek ve tvaru:

credential_0123456789abcdef="ZASIFROVANA_HODNOTA"

Tento řádek vložte do sekce [credentials] v souboru config/apikey.ini. Původní zkušební credential odstraňte. V souboru se neukládá otevřený API klíč ani otevřený e-mail; obě hodnoty jsou zašifrované pomocí AES-256-GCM a klíče APP_KEY.

Přihlašovací adresa má tvar:

https://vas-server.example:4438/admin/signin/VAS_API_KLIC

Protože je klíč součástí URL, může se objevit v historii prohlížeče a přístupovém logu webového serveru. Zacházejte s celou adresou jako s heslem.

13. Dokončení instalace

Po nastavení .env, importu databáze a vytvoření administrátora obnovte stránku. Není nutné restartovat Apache, pokud jste měnili pouze .env a databázi. Instalační stránka zmizí, jakmile se aplikace úspěšně připojí a najde všechny požadované tabulky.

curl -k -I https://46.13.178.180:4438/

Očekávaný výsledek je HTTP 200. Zkontrolujte také přihlášení do Studia, vytvoření článku nebo podcastového kanálu, upload obrázku a zápis session.

14. Nejčastější problémy

403 Forbidden

Zkontrolujte, zda virtual host míří do PROJECT_ROOT/public, zda Apache může projít všemi nadřazenými adresáři a zda sekce <Directory> obsahuje Require all granted.

500 Server error

Podívejte se do samostatného Apache logu a do storage/logs. Častými příčinami jsou špatná práva adresářů, nečitelný .env, chybný DSN, chybějící tabulky nebo neplatný PHP soubor.

tail -n 200 /var/log/apache2/xamma-derived-4438-error.log
find /mnt/flash1/project/xamma-derived/storage/logs -maxdepth 1 -type f -print

Požadavek na 24 nebo 32 znaků

Nejde o stejnou hodnotu. APP_KEY musí mít alespoň 32 znaků. API klíč předávaný skriptu create-api-key musí mít alespoň 24 znaků. Skript navíc vyžaduje jako druhý argument platný e-mail administrátora.

Instalační stránka nezmizela

Aplikace buď nemá platné databázové údaje, nedokáže se připojit, nebo v databázi chybí část schématu. Ověřte DB_DSN, DB_USER, DB_PASSWORD a import souborů 10-main-module.sql a 20-media-module.sql.

15. Produkční kontrolní seznam

• Veřejným kořenem je pouze adresář public.
• Soubor .env není dostupný z webu a má omezená práva.
• APP_DEBUG=false.
• APP_KEY je náhodný a má nejméně 32 znaků.
• Výchozí API credential byl odstraněn.
• API klíč má nejméně 24 znaků a je bezpečně uložen.
• Databázový účet má práva pouze k databázi aplikace.
• Vzdálený přístup k MariaDB je omezen firewallem.
• Self-signed certifikát byl na veřejném webu nahrazen důvěryhodným certifikátem.
• Adresáře storage a public/uploads jsou zapisovatelné pro Apache, ostatní části projektu pouze čitelné.
• Apache configtest, smoke test a HTTP test končí úspěšně.

Závěr

Xamma Derived se dá spustit bezpečně ještě před vytvořením databáze. Klíčem k bezproblémovému nasazení je správný veřejný kořen public, oddělení privátní konfigurace, přesně nastavená práva provozních adresářů, vlastní databáze a dva správně rozlišené klíče: APP_KEY pro šifrování a dlouhý API klíč pro přihlášení. Pokud jednotlivé kroky provádíte v uvedeném pořadí a po každém kroku kontrolujete logy, lze většinu chyb odhalit ještě před zpřístupněním webu uživatelům.