commit 1ab133942b12b3376fa5f9e4a702b9b832ceb92f Author: kovacsz Date: Thu Feb 5 20:42:20 2026 +0100 Add A docker-skeleton leírása diff --git a/A docker-skeleton le%C3%ADr%C3%A1sa.-.md b/A docker-skeleton le%C3%ADr%C3%A1sa.-.md new file mode 100644 index 0000000..503b70a --- /dev/null +++ b/A docker-skeleton le%C3%ADr%C3%A1sa.-.md @@ -0,0 +1,306 @@ +A **docker-skeleton** egy shell script framework, amely Docker konténerekből összeállított (komponált) webszolgáltatások menedzselésére szolgál standalone (nem orkesztrált) Ubuntu Linux Docker host környezetben. A framework működése Ubuntu Linux 24.04 LTS környezetben részletesen tesztelt, de egyéb, hasonló környezetben is működőképes lehet. + +**Work in progress** - még ne vedd komolyan! + +## Áttekintés + +## Házirend +A [[Docker host telepítése (24.04 LTS)|Docker host telepítése]] wikilapon részletezett elrendezés használata során az alábbi házirendet valósítjuk meg: + +* A hostgépen futó valamennyi dockerezett szolgáltatás egyetlen, nem perszonalizált, dedikált Linux felhasználó (a _dockeradmin_) tárterületén helyezkedik el (a _/srv/docker/services_ könyvtár alatt). Ezen belül az egyes szolgáltatások elkülönített könyvtárakba kerülnek. Arra törekszünk, hogy a szolgáltatáshoz tartozó minden specifikus állomány a szolgáltatás alapkönyvtárán belül kapjon helyet, így a szolgáltatás ezen könyvtár lemásolásával klónozható, költöztethető, illetve menthető legyen. +* Minden szolgáltatás különálló Docker kompozícióban fut (akkor is, ha azt csak egyetlen konténer biztosítja), és a Dockeren belül a szolgáltatás számára dedikált networkre csatlakozik. Ezek a networkök közvetlenül nem átjárhatóak (azaz az egyes szolgáltatások egymásra nem látnak rá). +* A szolgáltatások publikus portjait a TCP/8201-től kezdve egyesével emelkedő számsorrendben osztjuk ki. Ezek a portok a hostgépen kívülről közvetlenül nem, csak SSH tunnelen vagy reverse proxyn keresztül érhetőek el. A dockerezett webszolgáltatások számára a reverse proxyt a hostgépen futó webszerver biztosítja. +* A dockerezett szolgáltatások konténereinek naplóit (a _docker log_ kimeneteket), valamint a dockerezett webszolgáltatások webnaplóit perzisztensen megőrizzük és rotáljuk. +* A dockerezett szolgáltatásokról automatikus napi mentés készül, amelynek tartalma a szolgáltatás receptjében van meghatározva. A recept definiálásánál törekszünk arra, hogy a mentésből a szolgáltatás (szükség esetén annak újratelepítése után) teljesen visszaállítható legyen. Ez a mentés a naplókat általában nem tartalmazza. +* A dockerezett szolgáltatásokat adminisztráló _dockeradmin_ felhasználó közvetlenül nem _sudo_-képes, de a _docker_ Linux csoport tagjaként jogosult a _docker_ és _docker-compose_ parancsok teljes körű használatára.
A _dockeradmin_ felhasználót megbízhatónak tekintjük; tisztában vagyunk avval, hogy a fenti jogosultság birtokában a _dockeradmin_ képes lenne a hostgépen a teljes körű _root_ jogosultság megszerzésére is (**TODO!**). +* A _dockeradmin_ felhasználó jogosult shell futtatására; mindennapi tevékenysége során parancssori műveleteket használ. Bejelentkezése PPK authentikációval, (a _/srv/docker/.ssh/authorized_keys_ publikus kulcsai közé felvett egyéni magánkulccsal) történik. +* A _dockeradmin_ felhasználó jogosult a hostgépen futó reverse proxy webszerver konfigurációjának teszteltetésére és annak újraolvastatására. +* **TODO!** + +### Könyvtárszerkezet +A [[Docker host telepítése (24.04 LTS)|Docker host telepítése]] wikilapon részletezett Docker host telepítés esetén a framework az alábbi könyvtárszerkezetben működik: +
+  /srv                 a dockeradmin Linux felhasználó HOME könyvtára
+    /bin               a frameworkhöz tartozó binárisok könyvtára
+    /services          a dockerezett szolgáltatások alapkönyvtára
+    /tmp               tetszőlegesen felhasználható ideiglenes könyvtár
+      .nginx           a dockerezett webszolgáltatások nginx konfigurációira mutató symlinkek könyvtára
+      first_service    az első dockerezett szolgáltatás alapkönyvtára
+      second_service   a második dockerezett szolgáltatás alapkönyvtára
+      ...
+
+A fenti könyvtárszerkezetet a framework telepítése (a konkrét webszolgáltatások könyvtárainak kivételével) kialakítja és megfelelően fel is tölti. Telepítés után a könyvtárszerkezet a _dockeradmin:dockeradmin_ Linux felhasználó tulajdonában van, a könyvtárakra vonatkozón 2771, a fájlokra vonatkozóan 660 (scripteknél 770) jogosultságokkal. + +Az egyes szolgáltatások könyvtárszerkezete minden szolgáltatás esetében lényegében azonos: +
+  service_base         a szolgáltatás alapkönyvtára
+    .recipes           előre definiált szolgáltatás-receptek állományai
+    .templates         a szolgáltatás testre szabásánál használt sablonok
+    .utils             a docker-skeletonhoz kapcsolódó külső szolgáltatások
+    configs            konfigurációs állományok (pl. nginx.conf)
+      acme             az automatikus SSL tanúsítvány frissítés állományai
+      certs            nem automatikusan frissített SSL tanúsítványok
+    docker             helyben buildelendő szolgáltatás esetén annak állományai 
+    logs               a Dockertől származó naplók
+      web              a webszervertől származó naplók
+    storage            a szolgáltatáshoz kapcsolódó tárhely
+      backup           az automatikus mentések tárhelye
+        dumps          az adatbázis-mentések könyvtára
+        export         opcionálisan publikált automatikus mentések könyvtára
+        tarballs       a konfiguráció- és egyéb tárterület mentések könyvtára
+      volumes          a perzisztens Docker kötetek könyvtára
+    tools              a framework szolgáltatás-szintű futtatható állományai
+      backup.d         az automatikus mentéskor futtatandó scriptek
+      build.d          az esetleges buildeléskor futtatandó scriptek
+      shutdown.d       a szolgáltatás leállításakor futtatandó scriptek
+      startup.d        a szolgáltatás indításakor futtatandó scriptek
+
+A fenti könyvtárszerkezetet a szolgáltatás telepítésekor a _docker-skeleton_ kiadás általános tartalmának és a konkrét szolgáltatás receptjének összefűzésével alakítjuk ki. + +A szolgáltatások könyvtárszerkezete alapértelmezésben a _dockeradmin:dockeradmin_ Linux felhasználó tulajdonában marad, a könyvtárakra vonatkozón 2771, a fájlokra vonatkozóan 660 (scripteknél 770) jogosultságokkal. A _storage/volumes_ könyvtárban esetlegesen (a használt receptben meghatározott) ettől eltérő tulajdonosra és jogosultságokra lehet szükség (ennek beállításához a szolgáltatás telepítésénél _root_ jogosultság kellhet). A könnyebb adminisztrálhatóság érdekében törekedjünk arra, hogy ilyen esetben is a _dockeradmin_ felhasználónak legyen (pl. ACL-lel biztosított) olvasási- és írásjoga a szolgáltatás teljes tárterületére. + +### Webszolgáltatás +A dockerezett webalkalmazások számára a hostgépen telepített natív webszerver (jelenleg Apache vagy nginx) biztosít SSL végződtetést (tanúsítványkezelést) és http(s) => http reverse proxy szolgáltatást. A dockerezett alkalmazás saját szolgáltató portját (esetleg portjait) a hostgépen a _localhost:[8201-]_ tartományban exportálhatja, itt kapja a számára releváns lekéréseket a reverse proxy webszervertől. A fenti elrendezésben a webszolgáltatás akkor is válaszképes, ha az upstream dockerezett webalkalmazás éppen nem fut - ez esetben a webszerver a publikus lekérésre customizált hibaüzenettel válaszol. + +A _docker-skeleton_ frameworkben egy-egy komponált szolgáltatás minden webes alkatrésze - konfigurációja, SSL tanúsítványa, tárterülete, naplóállományai - a szolgáltatás alapkönyvtára alatt helyezkedik el, az alábbiak szerint: +
+ service_base         a szolgáltatás alapkönyvtára
+   configs            konfigurációs állományok
+     acme             az automatikus SSL tanúsítvány frissítés állományai
+     certs            nem automatikusan frissített SSL tanúsítványok
+     nginx.conf       virtualhost konfiguráció (nginx)
+     apache.conf      virtualhost konfiguráció (apache)
+   logs               naplóállományok
+     web              a webszervertől származó naplók
+   storage            a szolgáltatáshoz kapcsolódó tárhely
+     volumes          a perzisztens Docker kötetek könyvtára
+
+Minden dockerezett webszolgáltatás a hostgépre vonatkozóan önálló virtualhost konfigurációval rendelkezik, amelyben az alanti beállítások definiálva vannak. Az alapértelmezett konfiguráció sablon alapján történő létrehozását script támogatja, ezután azonban a konfiguráció _dockeradmin_-ként manuálisan tetszés szerint módosítható és a módosítás érvényesíthető (a _dockeradmin_ felhasználó jogosult a hostgépen a webszerver beállítások újraolvastatására). + +A hostgép webszervere számára a _~/services_ alatt lépezik egy katalógus könyvtár (_.apache_ vagy _.nginx_ néven) amelyben az egyes _[service]/configs/_ alatti webszerver konfigurációkra mutató (scripttel létrehozott) symlinkek találhatóak. A reverse proxy webszerver ezt a katalógus könyvtárat include-olja, így szerez tudomást az egyes webszolgáltatások egyéni konfigurációiról. + +A webalkalmazások virtualhostjainak SSL tanúsítványait (magánkulcsaikkal együtt) a _configs/acme_ illetve _configs/certs_ könyvtárak tartalmazhatják. Amennyiben a virtualhost alkalmas [https://certbot.eff.org/ CertBot]-jellegű automatikus tanúsítványfenntartásra, annak egyszeri (scriptelt) igénylését követően azt a _docker-skeleton_ automatikusan képes frissíteni, fenntartani. Ezek a tanúsítványok kerülnek a _configs/acme_ könyvtárba. A manuálisan telepített és fenntartott tanúsítványok javasolt helye a _config/certs_ könyvtár - az itt elhelyezett tanúsítványok érvényességét a _docker-skeleton_ naponta ellenőrzi és lejáratuk előtt figyelmeztetést küld. Amennyiben biztonsági, vagy egyéb okból a tanúsítványokat mégsem itt (hanem pl. a szervergép _/etc/ssl_ könyvtára alatt) szeretnénk elhelyezni, javasolt a releváns tanúsítványt a _config/certs_-be symlinkelni, hogy a lejárati ellenőrzés megmaradjon. + +Mind a konfigurációk, mind a tanúsítványok kezdeti beolvasását a host webszervere _root_-ként végzi, ezért ezen állományok a _dockeradmin_ tulajdonában maradhatnak. + +Az egyes webszolgáltatások virtualhostjaira vonatkozó webnaplókat a reverse proxy webszerver szolgáltatás a _logs/web_ könyvtárba írja. Ez a tárhely a _dockeradmin_ számára is írható-olvasható, így a karbantartási feladatok el tudják végezni a naplók rotálását (alapértelmezésben naponta rotálva és tömörítve, 60 nap megőrzésével). + +### Karbantartási funkciók +A _docker-skeleton_ framework rendelkezik a teljes Docker hostra kiterjedő, illetve az egyes szolgáltatásokon külön-külön használható karbantartási funkciókkal. Ezek a funkciók alapértelmezésben automatikusak (a _dockeradmin_ Linux felhasználó _crontab_-jából indítottak), de _dockeradmin_ felhasználóként belépve parancssorból manuálisan is elindíthatóak. + +Az automatikus karbantartási funkciókat a _dockeradmin_ Linux felhasználó _crontab_-ja indítja az alábbi híváslánc szerint: + crontab + + ~/bin/maintenance_midnight alapértelmezésben minden nap 00:01 + [service]/tools/maintenance_midnight + [service]/tools/rotate-logs Docker- és webnaplók rotálása + + ~/bin/maintenance_daily alapértelmezésben minden nap 04:00 + [service]/tools/maintenance_daily + [service]/tools/acme + ~/bin/acme.sh [service parameters] SSL webtanúsítvány automatikus frissítése + [service]/tools/backup + [service]/tools/configs_backup.sh konfigurációs állományok tar.gz mentése + [service]/tools/backup.d/*.sh a receptben meghatározott egyéb mentések + ~/bin/rotate_folder [service parameters] mentésállományok rotálása + + ~/bin/maintenance_reboot a szervergép (újra)indításakor + [service]/tools/maintenance_reboot + [service]/tools/startup.d/110-startlogs.sh a Docker naplók elindítása + +#### maintenance_midnight +A teljes Docker hostra kiterjedő, alapértelmezésben 00:01-kor elindított karbantartás. Lefuttatja az egyes szolgáltatások _tools/maintenance_midnight_ scriptjét a szolgáltatások könyvtára szerint betűrendben, egy-egy indítás között alapértelmezésben 60 másodperc türelmi idővel. A szolgáltatásonkénti azonos nevű karbantartó script a szolgáltatás _tools/rotate_logs_ scriptjének meghívásával gondoskodik az aktív (futó) szolgáltatáshoz tartozó Docker- és webnaplók rotálásáról. Nem aktív szolgáltatás naplói nem rotálódnak. + +#### maintenance_daily +A teljes Docker hostra kiterjedő, alapértelmezésben 04:00-kor elindított karbantartás. + +Első lépésként összeállít, és a karbantartást futtató Linux felhasználónak elküld egy emailt (napi jelentés), amelyben többek között a hostgép tárterület-foglaltságáról és a Linux disztribúció várakozó csomagfrissítéseiről szerepel tájékoztatás. Ezt az emailt a _~.forward_ állomány megfelelő beállításával irányíthatjuk létező email címekre. Amennyiben az email küldés az adott hostgépen nem telepített vagy nem biztosított, a _~/bin/mail_ (fake mailer) scriptre futtatási jogot adva elkerülhető a sikertelen levélküldési kísérlet okozta hibaüzenet. + +A levélküldési kísérlet után a karbantartás lefuttatja az egyes szolgáltatások _tools/maintenance_daily_ scriptjét a szolgáltatások könyvtára szerint betűrendben, egy-egy indítás között alapértelmezésben 120 másodperc türelmi idővel. A szolgáltatásonkénti azonos nevű karbantartó script a következő feladatokat látja el: + +* webszolgáltatás esetén az SSL tanúsítvány automatikus frissítése +Amennyiben a _tools/acme_ script létezik és futtatható, azt elindítja. Ez a script a _~/bin/acme.sh_ [https://certbot.eff.org/ Certbot] [https://github.com/acmesh-official/acme.sh variáns] hívásával ellenőrzi, és szükség esetén automatikusan frissíti a webszolgáltatáshoz tartozó, a szolgáltatás _configs/acme_ könyvtára alatt található SSL tanúsítványát. Ha ilyen tanúsítvány nem létezik, ez a lépés nem csinál semmit. + +* a napi mentés elkészítése +A napi mentés elkészítése a _tools/backup.d/*.sh_ scriptek betűrendben történő, egymás utáni lefuttatásával történik. Ebben a könyvtárban alapértelmezésben egyetlen script szerepel (_configs_backup.sh_), amely a _docker-compose.yml_, _configs_ és _docker_ könyvtárak tartalmát menti (az esetleges szimbolikus linkek feloldásával) a _storage/backups/tarball_ alatt létrejövő, egyedi nevű _.tgz_ tömörítvénybe. A használt recept általában tartalmaz további mentő scripteket (adatbázis dump, web tárterület, stb.) amelyek eredménye ugyancsak a _storage/backups_ alatti könyvtárszerkezetbe kerül. + +* a mentésállományok rotálása +A mentésállományok rotálása a _~/bin/rotate_folder_ script egyenkénti, paraméterezett hívásával valósul meg a _storage/backups_ alatti könyvtárakra. csak azok a könyvtártartalmak rotálódnak, amely könyvtárak tartalmaznak _.rotate_folder_ elnevezésű konfigurációs állományt. Ebben az állományban lehet meghatározni a megtartandó állományok körét. Az alapértelmezett rotálás megtartja az elmúlt 7 napban keletkezett valamennyi állományt, az előtte lévő 4 hétből heti egy-egy állományt (a legrégebbieket), illetve az előtte lévő 11 hónapból havi 1-1- állományt (ugyancsak a legrégebbieket). Ez a lépés nem fut le, ha a szolgáltatás nem fut (nem aktív). + +#### maintenance_reboot +A teljes Docker hostra kiterjedő, a szervergép (újra)indításakor lefutó karbantartás. + +A szervergép újraindításakor az _always_, illetve _unless-stopped_ policyvel definiált konténerek automatikusan elindulnak, azonban ez az indulás nem scriptelt (nem futnak le a _[service]/tools/startup.d/*_ scriptek), így az érintett konténerek logjai nem irányítódnak át a _[service]/logs_ alatti fájlokba. Ennek pótlására ez a karbantartás meghívja minden szolgáltatás _[service]/tools/startup.d/110-startlogs.sh_ scriptjét, amely ellenőrzi, hogy a szolgáltatás fut-e, és ha igen, elvégzi a logok átirányítását. +### Mentés és visszállítás + +## Műveletek +### Szolgáltatás telepítése recept alapján +Új szolgáltatás telepítését a Docker hostra _dockeradmin_ felhasználóként belépve végezzük. +#### Fájlműveletek +* [https://gitea.marcusconsulting.hu/marcusconsulting/docker-skeleton/ Töltsük le] a _docker-skeleton_ legfrissebb változatát a _~/tmp_ könyvtárba, és tömörítsük ki: +
+cd ~/tmp
+wget https://gitea.marcusconsulting.hu/marcusconsulting/docker-skeleton/archive/master.tar.gz -O docker-skeleton-$(date '+%Y%m%d').tar.gz
+tar xzf docker-skeleton-$(date '+%Y%m%d').tar.gz  # => ~/tmp/docker-skeleton
+* Futtassuk le a skeleton gyökerében található _setpermissions.sh_ scriptet, amely helyreállítja a jogosultságokat, a fájlok dátum-és idő adatait, valamint törli a felesleges (_.gitignore_, stb.) fájlokat. Futtatás után ez a script is törölhető: +
cd docker-skeleton
+/bin/bash setpermissions.sh
+rm .metadata README.md setpermissions.sh
+* Hozzunk létre egy új szolgáltatáskönyvtárat a _~/services_ alatt, és másoljuk a skeleton tartalmát a _.recipes_ és _.utils_ kivételével ebbe a könyvtárba (azért másolunk, és nem mozgatunk, hogy érvényesüljenek a _services_-re beállított, öröklődő ACL-ek). A könyvtár neve egyben a komponált Docker szolgáltatás neve is lesz, ezért ügyeljünk arra, hogy ne használjunk a könytárnévben ékezeteket, írásjeleket (beleértve a pontot), egzotikus karaktereket, illetve kötőjelet sem. Javasolt séma: _alkalmazás_webhelynév_, pl. _wordpress_mysite_: +
newservice='myapp_mysite'
+mkdir ~/services/$newservice
+rsync -a --exclude=".recipes" --exclude=".utils" . ~/services/$newservice
+* Válasszuk ki a kívánt receptet - lépjünk be a _.recipes/[recept]_ könyvtárba, és tartalmával egészítsük ki az imént létrehozott szolgáltatás könyvtárat: +
cd .recipes/wordpress_mariadb  # Csak példa, a megfelelő receptet használjuk :)
+rsync -a --exclude="README.md" . ~/services/$newservice
+Ezzel a szükséges fájlmásolásokat elvégeztük. A _~/tmp/docker-skeleton_ könyvtárat tetszés szerint törölhetjük, vagy megtarthatjuk. + +#### A reverse web proxy beállítása +Amennyiben webszolgáltatást telepítünk, érdemes már most beállítanunk a rá mutató reverse web proxy szolgáltatást a host szervergépen. Ehhez szükségünk van egy (vagy több), a szervergépre mutató DNS rekordra (ennek hiányában csak _hosts_ fájllal konfigurált klienseknek fogunk tudni szolgáltatni). +###### nginx beállítása +A konfiguráláshoz lépjünk be a _~/services/[service]_ könyvtárba, és szerkesszük meg a _tools/customize_nginx.sh_ állomány alábbi sorait: +
+PAR_SERVICENAME="myapp_mysite"
+PAR_PROXYHOST="localhost"
+PAR_PROXYPORT="8201"
+PAR_SERVERNAME="mysite.example.com"
+PAR_LOCATION=
+PAR_WEBMASTER="webmaster@example.com"  # Valid support email address
+
+ahol +* _PAR_SERVICENAME_ kötelezően egyezzen meg a _[service]_ könyvtár nevével; +* _PAR_PROXYHOST_ maradjon _localhost_; +* _PAR_PROXYPORT_ helyére a házirend szerint válasszuk a szervergépen a 8201-től kezdve első, még nem használt szabad portot - a dockerezett alkalmazás szolgáltató portját erre a külső portra kell exponálni; +* _PAR_SERVERNAME_ az nginx virtualhost neve, egyezzen meg a webszolgáltatásra mutató (valamelyik) DNS névvel; +* _PAR_LOCATION_ az webszolgáltatás URL-jének alkönyvtár része (_context_ - pl. /nextcloud) - ha a webszolgáltatás a gyökér contextben fut, hagyjuk üresen; +* _PAR_WEBMASTER_ a szerverhiba esetén megjelenő tájékoztató oldalon szereplő hibabejelentő e-mail cím. +Ha elkészültünk, futtassuk le a paraméterezett állományt: +
/bin/bash customize_nginx.sh
+amely létre fogja hozni a _configs/nginx.conf_ állományt, és az erre mutató _~/services/.nginx/[service].conf_ symlinket, publikálva ezzel a létrehozott konfigurációt a hostgép reverse proxy webszervere számára. Amennyiben szükséges, a létrehozott _configs/nginx.conf_ állományt manuálisan megszerkeszthetjük, pl. több rámutató DNS hostnév esetén azokat felvehetjük a _server_name_ direktívába: +
+    ...
+    server_name mysite.example.com
+           myothersite.example.com;
+    ...
+Ha elkészültünk, ellenőriztessük és érvényesítsük a konfigurációt: +
sudo nginx -t                # szintaktikai ellenőrzés
+sudo systemctl reload nginx  # módosítások érvényesítése
+A fenti parancsok a _dockeradmin_-tól nem fognak _sudo_ jelszót kérni. + +Ezzel a HTTP webszolgáltatást beállítottuk. Gyorstesztként a szervergépet http kapcsolaton elérni képes eszközön, böngészőprogrammal megtekintve a szolgáltatásra mutató bármelyik URL-t, a reverse proxy webszervertől a virtualhost konfigurációjában a _@proxy_error_ location-ben definiált üzenetet fogjuk kapni: +
Sorry something went wrong. Try again a bit later.
+You may report this at webmaster@example.com.
+A lekérések a _logs/web/access.log_ és _log/web/error.log_ naplókban is megjelennek. +###### Apache beállítása +**TODO!** + +###### SSL tanúsítás +HTTPs webszolgáltatás esetén a szükséges tanúsítvány(ok) kezelését intézhetjük a _docker-skeleton_ frameworkön kívül, vagy rábízhatjuk annak kezelését a frameworkre. +####### Tanúsítás a framework közreműködése nélkül +Ha a tanúsítványt a framework közreműködése nélkül szereztük meg, a PEM (Base64/ASCII) formátumú tanúsítványt és annak magánkulcsát elhelyezhetjük a szervergép _/etc/ssl/certs_ illetve _/etc/ssl/private_ könyvtáraiban (Debian/Ubuntu alapértelmezés, ehhez _root_ jogosultság kell), vagy tárolhatjuk a szolgáltatás _config/certs_ könyvtárában, pl. az alábbi (javasolt) elrendezésben: +
+service_base                      a szolgáltatás alapkönyvtára
+  configs                         konfigurációs állományok
+    certs                         nem automatikusan frissített SSL tanúsítványok könyvtára
+      mysite.example.com          a virtualhosthoz tartozó tanúsítványok könyvtára
+        fullchain.cer             Base64/ASCII formátumú tanúsítványlánc 
+        mysite.example.com.cer    Base64/ASCII formátumú tanúsítvány
+        mysite.example.com.key    Base64/ASCII formátumú magánkulcs
+
+ahol a _fullchain.cer_ állomány a tanúsítványhoz konkatenálva tartalmazza az esetleges köztes (_intermediate_) tanúsítványokat is. + +A fenti elrendezés használata esetén a HTTPs engedélyezéséhez és a tanúsítvány figyelembe vételéhez **nginx** használata esetén a _configs/nginx.conf_ állományban az alábbi sorok elől távolítsuk el a kommentezést: +
+server {
+    ...
+    listen 443 ssl;
+    ...
+    # For a (possibly symlinked) static certificate.
+    ssl_certificate     /srv/docker/services/myapp_mysite/configs/certs/mysite.example.com/fullchain.cer;
+    ssl_certificate_key /srv/docker/services/myapp_mysite/configs/certs/mysite.example.com/mysite.example.com.key;
+    ...
+
+A sablonból létrehozott konfigurációs állományban alapértelmezetten a fenti elrendezésnek megfelelő útvonalak szerepelnek, de tetszőleges egyéb útvonalakat is megadhatunk. + +**Apache** használata esetén **TODO!** + +###### Tanúsítás a framework közreműködésével +A tanúsítványok kezelését a frameworkre bízhatjuk, ha a tanúsítandó hostnév a nagyvilág felől http kapcsolaton keresztül folyamatosan elérhető, és üzleti céljainknak a [https://letsencrypt.org/ Let's Encrypt], [https://zerossl.com/ ZeroSSL], stb. jellegű tanúsítvány megfelelő. + +Tanúsításhoz a szolgáltatás alapkönyvtárában állva hívjuk meg a framework _acme_ parancsát az alábbi minta szerinti paraméterezéssel: +
./tools/acme --issue --keylength 4096 -d mysite.example.com -d myothersite.example.com --standalone --httpport 8100 --accountemail "webmaster@example.com"
+ahol tetszőleges számú _-d_ bejegyzéssel tetszőleges számú hostnevet foglaltathatunk bele ugyanabba a tanúsítványba (de * wildcardot nem használhatunk). Az _accountemail_-re a tanúsítványszolgáltató figyelmeztetést fog küldeni, ha a tanúsítvány automatikus meghosszabbítása valamiért sikertelen lenne, ezért ide valid email címet érdemes megadni. A paraméterek között meghatározott 8100-as TCP porti (technikai) forgalom a _localhost_-on belül marad, ezt a portot a külvilág felé kinyitni nem szükséges (nem szabad). + +Sikeres futtatás esetén a _configs_ alatt létrejön az alábbi könyvtárszerkezet: +
+service_base                      a szolgáltatás alapkönyvtára
+  configs                         konfigurációs állományok
+    acme                          automatikusan frissített SSL tanúsítványok könyvtára
+      ca                          regisztrációs adatok a tanúsítványszolgáltatókhoz
+      mysite.example.com          a virtualhosthoz tartozó tanúsítványok könyvtára
+        ca.cer                    Base64/ASCII formátumú tanúsítvány(lánc)
+        fullchain.cer             Base64/ASCII formátumú tanúsítványlánc 
+        mysite.example.com.cer    Base64/ASCII formátumú tanúsítvány
+        mysite.example.com.key    Base64/ASCII formátumú magánkulcs
+        ...                       egyéb technikai állományok
+
+Az így létrehozott tanúsítvány lejáratának figyeléséről és annak szükség szerinti periodikus megújításáról a framework _maintenance_daily_ karbantartási feladata gondoskodik. A tanúsítványkezeléssel kapcsolatos műveletek üzenetei a webnaplókkal azonos módon kezelt és rotált _logs/web/acme.log_ naplóba kerülnek. + +A HTTPs engedélyezéséhez és a tanúsítvány figyelembe vételéhez **nginx** használata esetén a _configs/nginx.conf_ állományban az alábbi sorok elől távolítsuk el a kommentezést: +
+server {
+    ...
+    listen 443 ssl;
+    ...
+    # For an ACME-handled certificate.
+    ssl_certificate     /srv/docker/services/myapp_mysite/configs/acme/mysite.example.com/fullchain.cer;
+    ssl_certificate_key /srv/docker/services/myapp_mysite/configs/acme/mysite.example.com/mysite.example.com.key;
+    ...
+
+A sablonból létrehozott konfigurációs állományban alapértelmezetten a fenti útvonalak szerepelnek, ezeket ne változtassuk meg. + +**Apache** használata esetén **TODO!** + +###### A HTTPs használatba vétele +Ha a fentiekkel elkészültünk, ellenőriztessük és érvényesítsük a konfigurációt, **nginx** használata esetén: +
+sudo nginx -t                # szintaktikai ellenőrzés
+sudo systemctl reload nginx  # módosítások érvényesítése
+
+**Apache** használata esetén: +
+sudo apachectl -t               # szintaktikai ellenőrzés
+sudo systemctl reload apache2   # módosítások érvényesítése
+
+A fenti parancsok a _dockeradmin_-tól nem fognak sudo jelszót kérni. + +**Gyorstesztként** a szervergépet https kapcsolaton elérni képes eszközön, böngészőprogrammal megtekintve a szolgáltatásra mutató bármelyik (tanúsított) URL-t, a korábban látott hibaoldalt tanúsítványhibára utaló figyelmeztetés nélkül kell megkapjuk. Sikeres teszt esetén érdemes az SSL biztonságát pl. a [https://www.ssllabs.com/ssltest/ Qualis] szolgáltatásával ellenőriztetni (A-t kell kapnunk). +###### A HTTPs kényszerítése +Amennyiben nincsen nyomós ellenérvünk, érdemes az érdemi webszolgáltatást csak https-en nyújtani (a http klienseket érdemi kiszolgálás helyett már a reverse proxy webszerverben a https URL-re átirányítani). + +Az átirányításhoz **nginx** használata esetén a _configs/nginx.conf_ állományban távolítsuk el a kommenteket az alábbi sorok elől: +
+    # Forced redirect to https.
+    if ($scheme = http) {
+        return 301 https://$host$request_uri;
+    }
+
+Ellenőriztessük és érvényesítsük a konfigurációt: +
+sudo nginx -t                # szintaktikai ellenőrzés
+sudo systemctl reload nginx  # módosítások érvényesítése
+
+A fenti parancsok a _dockeradmin_-tól nem fognak sudo jelszót kérni. + +**Apache** használata esetén **TODO!** +

+
+Ellenőriztessük és érvényesítsük a konfigurációt:
+
+sudo apachectl -t               # szintaktikai ellenőrzés
+sudo systemctl reload apache2   # módosítások érvényesítése
+

+A fenti parancsok a _dockeradmin_-tól nem fognak sudo jelszót kérni.
+
+**Gyorstesztként** a szervergépet http és https kapcsolaton elérni képes eszközön, böngészőprogrammal http-n elkérve a szolgáltatásra mutató bármelyik (tanúsított) URL-t, a korábban látott hibaoldalt (a háttérben lezajló böngésző redirect után) https-en kell megkapjuk.
+##### Speciális beállítások