Tuotantoympäristö

Kotiseuranta julkaistaan cPanel-palvelimelle paikallisen FTP/GVFS-liitoksen kautta. Julkinen esittelysivu on kotiseuranta.fi-osoitteessa ja sovellus app.kotiseuranta.fi-osoitteessa. Sovelluksen API pysyy saman originin /api-polussa, jotta selainistunnot ja tiedostolataukset toimivat nykyisellä tavalla. api.kotiseuranta.fi-alidomainia ei tarvita.

./deploy app julkaisee sovelluksen ja ./deploy marketing esittelysivun. Molemmilla on oma dokumenttijuurihakemisto, manifesti, palautuskopio ja rollback-komento. Vanhan päädomainin production-kohteen tilaa ei käytetä uudessa hakemistossa. Sovelluksen julkaisu rakentaa frontendin ja käyttöohjeen, testaa backendin ja kokoaa PHP-riippuvuudet. Esittelysivun julkaisu kopioi marketing-hakemiston staattiset tiedostot ja brändikuvat.

Ensimmäinen käyttöönotto

1. Varmista, että tuotannon FTP-hakemisto on liitetty paikalliselle koneelle.
2. Luo cPanelissa app.kotiseuranta.fi siten, että sen dokumenttijuuri on FTP-liitoksessa /app.kotiseuranta.fi. Apex-domainin dokumenttijuuri on /public_html. Hakemistojen on oltava erilliset, ei sisäkkäiset. Varmista HTTPS molemmille osoitteille.
3. Kopioi deploy.conf.example tiedostoksi deploy.conf ja tarkista molemmat polut ja URL:t. Nykyinen paikallinen asetus käyttää edellä mainittuja hakemistoja.
4. Luo .env.product, jossa ovat tuotantotietokannan DB_HOST, DB_PORT, DB_NAME, DB_USER ja DB_PASSWORD.
5. Kun siirrät nykyisen asennuksen pois /public_html-hakemistosta, ota koko nykyisestä julkaisusta varmuuskopio ja kopioi toimiva julkaisu, .env sekä backend/public/uploads uuteen hakemistoon. Tarkista API, kirjautuminen ja ladatut tiedostot uudessa osoitteessa ennen vanhan asennuksen poistamista. Jos työpuussa on muuta keskeneräistä työtä, älä käytä ./deploy app --force-komentoa siirtoon: se veisi myös keskeneräiset tiedostot tuotantoon.
6. Esikatsele ./deploy marketing --replace-legacy-app --dry-run ja julkaise esittelysivu komennolla ./deploy marketing --replace-legacy-app. Tämä kertaluonteinen valitsin ottaa ensin koko vanhasta päädomainin sisällöstä paikallisen palautuskopion, poistaa vanhan sovelluksen backendin, lataukset, salaisen .env-tiedoston ja vanhat staattiset hakemistot päädomainilta sekä julkaisee uuden etusivun. Käytä sitä vasta, kun uusi sovellus ja sen lataukset on tarkistettu.
7. Jatkossa ./deploy marketing päivittää vain esittelysivun ja ./deploy app sovelluksen. Käytä --with-migrations vain, jos sovelluksen julkaisu tarvitsee uusia migraatioita.
8. Jos kyseessä on uusi asennus, vie .env.product-arvot hetkellisesti prosessin ympäristöön ja luo ensimmäinen käyttäjä komennolla php backend/bin/create-user.php asukas. Älä anna tietokannan salasanaa komentoriviparametrina.
9. Tarkista selaimella esittelysivu, kirjautuminen, tietojen avaaminen ja tiedoston lataaminen.

Valitse cPanelin PHP-asetuksista domainille PHP 8.2 tai uudempi. Kehityskoneen PHP-versio ei määrää tuotantopalvelimen versiota. Julkaisu säilyttää kohteen .htaccess-tiedoston cPanelin luomat PHP-versio- ja ini-asetuslohkot.

deploy.conf, .env.product, julkaisuun muodostettava .env ja paikalliset palautuskopiot eivät kuulu versionhallintaan. Deploy ei tulosta ympäristötiedoston sisältöä lokiin.

Tavallinen julkaisu

./deploy app
./deploy marketing

Käytä --with-migrations vain, kun julkaisuun kuuluu uusia tietokantamigraatioita. --skip-tests käyttää olemassa olevia buildeja ja ohittaa backend-testit sekä frontendin ja ohjeen rakentamisen. --force sallii julkaisun likaisesta Git-työpuusta; sitä tulee käyttää vain tietoisesti. --full kopioi kaikki julkaisutiedostot uudelleen esimerkiksi palvelimella käsin tehtyjen muutosten jälkeen.

Deploy tallentaa onnistuneen julkaisun tarkistussummat paikalliseen .deploy/manifests-hakemistoon. Ensimmäinen julkaisu ilman manifestia kopioi kaikki tiedostot; seuraavat julkaisut siirtävät vain muuttuneet tai kohteesta puuttuvat tiedostot. Manifesti päivitetään vasta onnistuneiden HTTP-tarkistusten jälkeen ja poistetaan rollbackin yhteydessä. Käyttäjän lataamat tiedostot eivät kuulu manifestiin. Ennen muutoksia otettava palautuskopio lukee yhä koko tuotantohakemiston.

Kopioinnissa sovellushakemistojen oikeuksiksi asetetaan 755, tiedostoille 644 ja salaisuuksia sisältävälle .env-tiedostolle 600. FTP-kohteeseen ei kopioida paikallisia omistaja- ja aikaleimatietoja. Palvelimen public_html-hakemiston omia oikeuksia ei muuteta. FTP/GVFS-liitos ei aina tue chmod-operaatiota: deploy tarkistaa kohteen oikeudet ensin ja ohittaa muutoksen, jos ne ovat jo oikein. Jos oikeudet ovat väärät eikä niitä voi muuttaa, julkaisu pysähtyy ja oikeudet on korjattava palvelimen hallinnassa. Tiedostot kopioidaan yksitellen GIO:lla, koska GVFS-liitos voi hylätä cp -R-kopioinnin. Julkaisupaketin tavalliset tiedostot normalisoidaan paikallisesti oikeuksiin 644 ennen GIO-siirtoa; lähdekoodin oikeuksia ei muuteta. Tämä estää esimerkiksi paikallisen 664-oikeuden siirtymisen FTP-kohteeseen, jossa chmod ei toimi.

Julkaisu tarkistaa kopioinnin jälkeen etusivun, ohjeen, faviconin, JavaScript- ja CSS-tiedostojen sekä API:n terveystarkistuksen toiminnan HTTP-pyynnöillä myös --skip-tests-valitsinta käytettäessä. Epäonnistunut tarkistus keskeyttää komennon virheeseen; tiedostot ovat tällöin jo palvelimella ja palautuskopio on käytettävissä. --dry-run ei muuta tuotantotiedostoja eikä tee HTTP-tarkistuksia.

Palautuskopio luetaan FTP/GVFS-liitoksesta tiedosto kerrallaan GIO:lla. Jos yhdenkin tiedoston kopiointi epäonnistuu, julkaisu pysähtyy ennen tietokantamigraatioita ja uusien tiedostojen vientiä. Tällöin aiempi palautuskopio säilyy viimeisimpänä toimivana kopiona.

Excel/CSV-tuonnin ensimmäisessä julkaisussa on uusi tietokantamigraatio. Julkaise se komennolla ./deploy app --with-migrations.

Käyttäjätilin poisto tarvitsee migraation 019_pending_file_deletions.sql. Julkaise tämä versio --with-migrations-valitsimella ennen poistopainikkeen käyttöä. Määritä cPanelin Cron Jobs -toiminnossa esimerkiksi tunnin välein ajettava komento php -q /home/TUNNUS/app.kotiseuranta.fi/backend/bin/purge_deleted_uploads.php, jossa korvaat polun todellisella sovelluspolulla. Komento poistaa poistotilanteessa jonoon jääneet tiedostot uudelleenyrityksellä. Se siivoaa myös yli tunnin vanhat tiedostot, joilla ei enää ole dokumenttiriviä tietokannassa. Normaali poisto yrittää poistaa tiedostot heti; cron on virhetilanteen varmistus. Tarkista cronin tuloste ja pending_file_deletions-taulu, jos poistoja jää odottamaan.

/uploads-osoitteet ohjataan nyt PHP:lle, joka tarkistaa kirjautumisen ja talon käyttöoikeuden. Varmista julkaisun jälkeen, että käyttäjä voi avata oman dokumenttinsa ja että ulos kirjautunut ei voi avata samaa URL:ia.

Paikalliset deploy-palautuskopiot voivat sisältää ennen poistoa ladattuja tiedostoja. Niille on määritettävä säilytysaika, ja vanhaa kopiota palautettaessa poistopyynnöt on huomioitava ennen palvelun avaamista käyttäjille.

Jos sivu jää tyhjäksi ja selain näyttää tiedostoille 403 Forbidden, tarkista erityisesti assets-, brand- ja ohje-hakemistojen oikeudet. Jos API palauttaa virheen Composer dependencies require a PHP version ">= 8.2.0", vaihda domainin PHP-versio cPanelissa. Julkaisun paikalliset regressiotestit voi ajaa komennolla bash deployment/test-deploy.sh.

Palautus

./deploy rollback app
./deploy rollback marketing

Palautus koskee tiedostoja, ei tietokantaa. Migraatioiden kanssa julkaistaessa varmista etukäteen, että edellinen sovellusversio toimii myös uuden skeeman kanssa. Käyttäjän lataamat tiedostot säilyvät normaalissa päivityksessä.