A docker-skeleton leírása forrásának megtekintése

A [https://gitea.marcusconsulting.hu/marcusconsulting/docker-skeleton/ 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. Ilyen környezet kialakítását az Ubuntu szerver [[Ubuntu szerver alaptelepítés (24.04 LTS)|alaptelepítése]], annak [[Ubuntu szerver általános biztonsági beállításai (24.04 LTS)|általános biztonsági beállításai]] és a [[Docker host telepítése (24.04 LTS)|Docker host telepítése]] wikilapok ismertetik. A framework működése ebben a 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. <br/>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:
<pre>
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</pre>
* 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ő:
<pre>cd docker-skeleton
/bin/bash setpermissions.sh
rm .metadata README.md setpermissions.sh</pre>
* 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'':
<pre>newservice='myapp_mysite'
mkdir ~/services/$newservice
rsync -a --exclude=".recipes" --exclude=".utils" . ~/services/$newservice</pre>
* 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:
<pre>cd .recipes/wordpress_mariadb  # Csak példa, a megfelelő receptet használjuk :)
rsync -a --exclude="README.md" . ~/services/$newservice</pre>
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:
<pre>
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
</pre>
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:
<pre>/bin/bash customize_nginx.sh</pre>
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:
<pre>
    ...
    server_name mysite.example.com
           myothersite.example.com;
    ...</pre>
Ha elkészültünk, ellenőriztessük és érvényesítsük a konfigurációt:
<pre>sudo nginx -t                # szintaktikai ellenőrzés
sudo systemctl reload nginx  # módosítások érvényesítése</pre>
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:
<pre>Sorry something went wrong. Try again a bit later.
You may report this at webmaster@example.com.</pre>
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:
<pre>
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
</pre>
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:
<pre>
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;
    ...
</pre>
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:
<pre>./tools/acme --issue --keylength 4096 -d mysite.example.com -d myothersite.example.com --standalone --httpport 8100 --accountemail "webmaster@example.com"</pre>
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:
<pre>
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
</pre>
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:
<pre>
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;
    ...
</pre>
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:
<pre>
sudo nginx -t                # szintaktikai ellenőrzés
sudo systemctl reload nginx  # módosítások érvényesítése
</pre>
'''Apache''' használata esetén:
<pre>
sudo apachectl -t               # szintaktikai ellenőrzés
sudo systemctl reload apache2   # módosítások érvényesítése
</pre>
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:
<pre>
    # Forced redirect to https.
    if ($scheme = http) {
        return 301 https://$host$request_uri;
    }
</pre>
Ellenőriztessük és érvényesítsük a konfigurációt:
<pre>
sudo nginx -t                # szintaktikai ellenőrzés
sudo systemctl reload nginx  # módosítások érvényesítése
</pre>
A fenti parancsok a ''dockeradmin''-tól nem fognak sudo jelszót kérni.

'''Apache''' használata esetén '''TODO!'''
<pre></pre>

Ellenőriztessük és érvényesítsük a konfigurációt:
<pre>
sudo apachectl -t               # szintaktikai ellenőrzés
sudo systemctl reload apache2   # módosítások érvényesítése
</pre>
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 <u>http-n</u> 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) <u>https-en</u> kell megkapjuk.
=====Speciális beállítások=====