Installazione dell'HTML5 Gateway Docker

Importazione dell'immagine Docker

Prima di poter creare un container HTML5 Gateway Docker, è necessario importare l'immagine Docker. A tale scopo, aprire una shell dalla quale siano disponibili i comandi Docker, così come il file cleanroom-html5-4.6.1-33-v2.tgz. Dalla shell, eseguire il comando seguente, adattando il percorso del file TGZ se non si trova nella directory corrente:

docker load --input cleanroom-html5-4.6.1-33-v2.tgz

Verificare quindi che l'importazione sia riuscita con il comando seguente:

docker inspect --type=image cleanroom-html5:4.6.1-33-v2

L'output previsto è il seguente. Se non è così, l'importazione è fallita:

[
    {
        "Id": "sha256:16ae07f1604409f6b092a8a2944e69b3db458a04dbbab6ffc3f945c253c82cee",
        "RepoTags": [
            "cleanroom-html5:4.6.1-33-v2"
        ],

Risultato completo

[
    {
        "Id": "sha256:16ae07f1604409f6b092a8a2944e69b3db458a04dbbab6ffc3f945c253c82cee",
        "RepoTags": [
            "cleanroom-html5:4.6.1-33-v2"
        ],
        "RepoDigests": [],
        "Parent": "",
        "Comment": "buildkit.dockerfile.v0",
        "Created": "2025-08-27T11:35:33.014244258+02:00",
        "DockerVersion": "",
        "Author": "",
        "Architecture": "amd64",
        "Os": "linux",
        "Size": 781097647,
        "GraphDriver": {
            "Data": {
                "LowerDir": "/var/lib/docker/overlay2/aa079416d669709486e3fd3dfefcff51acb3905ffcca7e6e428630d1a499e669/diff:/var/lib/docker/overlay2/da9f43ee88f5961a157af404be018fc7c3f5185a798b26911e38118d83830de7/diff:/var/lib/docker/overlay2/28efb3982392e95711e849cb90985fd534cd6273f4dec758463f98b41a432e93/diff:/var/lib/docker/overlay2/44a3abed0a932259b79c9e5e273749cc06bd8aca7d3adbfd1753a7b053dcae2f/diff:/var/lib/docker/overlay2/e3dfd4c7c4fe568ef731bd91314e69cc5c807ce717d5f4ea94f0d02cc11e70c5/diff:/var/lib/docker/overlay2/5acf2b56871d2537d95b9981c0498e16723a9eca20827f550366b48d8acf508f/diff:/var/lib/docker/overlay2/c732cd17c6501229b3a12c488d7f4c26f8634329211cac54ff1cf0d53055421f/diff:/var/lib/docker/overlay2/fd61cbda2a5e9a578c5a8eea67b63df3d31642588be3b6f2f7ebe6e10964f745/diff",
                "MergedDir": "/var/lib/docker/overlay2/b9c8170b6a9ed8e7c84a9ba208cd6e4b25e88d1dad42cd72b0e1178da62a46d4/merged",
                "UpperDir": "/var/lib/docker/overlay2/b9c8170b6a9ed8e7c84a9ba208cd6e4b25e88d1dad42cd72b0e1178da62a46d4/diff",
                "WorkDir": "/var/lib/docker/overlay2/b9c8170b6a9ed8e7c84a9ba208cd6e4b25e88d1dad42cd72b0e1178da62a46d4/work"
            },
            "Name": "overlay2"
        },
        "RootFS": {
            "Type": "layers",
            "Layers": [
                "sha256:4668f0f488e5ad4494fadff56ad585c514794b3a293e5e8d006410de9da08155",
                "sha256:782f6c5256575fbef0e518a1a1ce9188c457f1a0e9b88b733ed672f6e1be482d",
                "sha256:e09fd3e10e878ef6c812ccde0fa55b66cf4b9b593cf182c2760fec73649968c2",
                "sha256:e51c952c7bd89e0a3188c683d689eed81444d5513c14251f4b21cb9fd056d27d",
                "sha256:233ff67db52988898e3c1b4c2573b86c1c0c50d23f1f4b2365e3fc51abedbf9f",
                "sha256:f832eee42398852cab80a9a45138bf076d63ebbe153263fd8cf66857a0833d02",
                "sha256:f59f79d19c38ae4863b81774ad1d98030370c64e17013eb786da7b727bf2b41b",
                "sha256:0caeed550a29dbb274781e78bbe910fa5ccfdc90119cb4f9e3c815feff5a70b9",
                "sha256:21313651aa44ac0f5dd459a94be172b003b68f81b0db945c24a7ada5c21799e3"
            ]
        },
        "Metadata": {
            "LastTagTime": "0001-01-01T00:00:00Z"
        },
        "Config": {
            "Cmd": null,
            "Entrypoint": [
                "/entrypoint.sh"
            ],
            "Env": [
                "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                "DEBIAN_FRONTEND=noninteractive",
                "IMAGE_BUILD_DATE=20250827T112940",
                "IMAGE_BUILD_VERSION=4.6.1-33-v2",
                "IMAGE_IPDIPC=IPC-53702"
            ],
            "ExposedPorts": {
                "8080/tcp": {},
                "8090/tcp": {}
            },
            "Labels": {
                "maintainer": "contact@systancia.com",
                "org.label-schema.build-date": "20250827T112940",
                "org.label-schema.description": "Systancia Cleanroom Gateway",
                "org.label-schema.name": "Systancia Cleanroom 4.6.1-33-v2 HTML5 Server",
                "org.label-schema.url": "http://systancia.com/",
                "org.label-schema.vendor": "Systancia",
                "version": "4.6.1-33-v2"
            },
            "OnBuild": null,
            "User": "root",
            "Volumes": null,
            "WorkingDir": ""
        }
    }
]

Configurazione del container

Variabili d'ambiente

Variabili per la distribuzione tramite pairing

Nome	Obbligatorio	Valore predefinito	Commento
ENV_MEDIATION	SÌ		Utilizzata per la connessione tramite pairing. Indica il nome DNS o l'indirizzo IP per connettersi all'interfaccia web di una piattaforma CyberElements Bastion.
ENV_TOKEN	SÌ		Utilizzata per la connessione tramite pairing. Indica il pairing token da utilizzare per la connessione al Mediation Controller.
ENV_NO_CHECK_CERT	NO	false	Utilizzata per le connessioni tramite pairing. Disabilita o no la verifica del certificato web del Mediation Controller; utile con CyberElements Bastion quando l'accesso avviene tramite indirizzo IP oppure quando il certificato web non è riconosciuto dalle autorità di certificazione pubbliche predefinite. Valori accettati: true o false.

Variabili per la distribuzione manuale

Nome	Obbligatorio	Valore predefinito	Commento
ENV_GW_CERT_NAME	SÌ		Utilizzata per la connessione con configurazione manuale. Nome del file di certificato per la connessione all'SSL Router.
ENV_GW_CERT_PASSWORD	SÌ		Utilizzata per la connessione con configurazione manuale. Password del file di certificato per la connessione all'SSL Router.
ENV_SSL_ROUTER_IP	SÌ		Utilizzata per la connessione con configurazione manuale. Indirizzo IP o nome DNS dell'SSL Router al quale si connetterà l'HTML5 Gateway.
ENV_SSL_ROUTER_PORT	NO	443	Utilizzata per la connessione con configurazione manuale. Porta dell'SSL Router alla quale si connetterà l'HTML5 Gateway.

Variabili diverse

Nome	Obbligatorio	Valore predefinito	Commento
ENV_DISABLE_RSYSLOG	NO	false	Disattivazione del servizio rsyslog. Valori accettati: true o false.

Volumi

Volume	Commento
/etc/ipdiva/	Volume di configurazione dell'HTML5 Gateway. Si consiglia di montarlo su un volume denominato o sul file system della macchina host.
/opt/certificates/	Volume che contiene il o i certificati dell'HTML5 Gateway in caso di configurazione senza pairing.
/var/log/	Volume che contiene i log dell'HTML5 Gateway.

Porte

Porta	Commento
8080	Porta di ascolto del servizio HTML5.

Distribuzione dell'HTML5 Gateway Docker

Distribuzione con pairing

Prerequisiti

Prima di distribuire l'HTML5 Gateway Docker, è necessario ottenere un pairing token.

La distribuzione descritta di seguito utilizzerà tutti i volumi disponibili (tranne /opt/certificates/, che non è utile in questo contesto) ed esporrà tutte le porte.
I volumi saranno montati sul file system della macchina host nella posizione HTML5_GATEWAY_REP. All'interno di questa posizione si trovano le sottodirectory seguenti:

• config
• log

È possibile personalizzare le variabili dei comandi seguenti:

Valore personalizzato	Variabile	Commento
	DOCKER_NAME	Nome del container Docker.
	HTML5_GATEWAY_REP	Posizione nel file system in cui montare i volumi.
	ENV_MEDIATION_VALUE	Valore della variabile d'ambiente ENV_MEDIATION.
	ENV_TOKEN_VALUE	Valore della variabile d'ambiente ENV_TOKEN.
	ENV_NO_CHECK_CERT_VALUE	Valore della variabile d'ambiente ENV_NO_CHECK_CERT.

Creare l'albero di directory necessario per il montaggio dei volumi sul file system:

mkdir -p HTML5_GATEWAY_REP/config
mkdir HTML5_GATEWAY_REP/log

Infine, avviare un nuovo container:

docker run -d --restart unless-stopped --name "DOCKER_NAME" \
-e ENV_MEDIATION="ENV_MEDIATION_VALUE" \
-e ENV_TOKEN="ENV_TOKEN_VALUE" \
-e ENV_NO_CHECK_CERT="ENV_NO_CHECK_CERT_VALUE" \
-v "HTML5_GATEWAY_REP/config/:/etc/ipdiva/:rw" \
-v "HTML5_GATEWAY_REP/log/:/var/log/:rw" \
-p 8080:8080 \
cleanroom-html5:4.6.1-33-v2

I log del container possono essere consultati con il comando seguente:

docker logs -f DOCKER_NAME

Distribuzione manuale

Prerequisiti

Prima di distribuire l'HTML5 Gateway Docker, è necessario disporre del certificato richiesto per l'HTML5 Gateway.

La distribuzione descritta di seguito utilizzerà tutti i volumi disponibili ed esporrà tutte le porte.
I volumi verranno montati sul file system della macchina host nella posizione MANUAL_REP. All'interno di questa posizione si trovano le sottodirectory seguenti:

• config
• log
• certificates

È possibile personalizzare le variabili dei comandi seguenti:

Valore personalizzato	Variabile	Commento
	MANUAL_NAME	Nome del container Docker.
	MANUAL_REP	Posizione sul file system in cui montare i volumi.
	ENV_GW_CERT_NAME_VALUE	Valore della variabile d'ambiente ENV_GW_CERT_NAME.
	ENV_GW_CERT_PASSWORD_VALUE	Valore della variabile d'ambiente ENV_GW_CERT_PASSWORD.
	ENV_SSL_ROUTER_IP_VALUE	Valore della variabile d'ambiente ENV_SSL_ROUTER_IP.
	ENV_SSL_ROUTER_PORT_VALUE	Valore della variabile d'ambiente ENV_SSL_ROUTER_PORT.

Creare l'albero di directory necessario per il montaggio dei volumi sul file system:

mkdir -p MANUAL_REP/config
mkdir MANUAL_REP/log
mkdir MANUAL_REP/certificates

Collocare quindi i certificati dell'HTML5 Gateway e del servizio di registrazione in MANUAL_REP/certificates.

Infine, avviare un nuovo container:

docker run -d --restart unless-stopped --name "MANUAL_NAME" \
-e ENV_GW_CERT_NAME="ENV_GW_CERT_NAME_VALUE" \
-e ENV_GW_CERT_PASSWORD="ENV_GW_CERT_PASSWORD_VALUE" \
-e ENV_SSL_ROUTER_IP="ENV_SSL_ROUTER_IP_VALUE" \
-e ENV_SSL_ROUTER_PORT="ENV_SSL_ROUTER_PORT_VALUE" \
-v "MANUAL_REP/config/:/etc/ipdiva/:rw" \
-v "MANUAL_REP/log/:/var/log/:rw" \
-v "MANUAL_REP/certificates/:/opt/certificates/:ro" \
-p 8080:8080 \
cleanroom-html5:4.6.1-33-v2

I log del container possono essere consultati con il comando seguente:

docker logs -f MANUAL_NAME

Configurazione del Mediation Controller

Perché il nuovo HTML5 Gateway Docker sia operativo, resta da configurare il server Mediation Controller tramite un accesso SSH o console e con i permessi root.

Quest'ultima configurazione è necessaria per permettere al Mediation Controller di comunicare con il servizio HTML5.
Questa configurazione varia tuttavia in funzione della posizione dell'HTML5 Gateway Docker:

Collocato nella DMZCollocato nella LAN accessibile da un Edge Gateway

Lo schema generale è il seguente:

flowchart LR
    subgraph DMZ
        direction TB
        HTML5(HTML5 Gateway Docker)
        MED(Mediation Controller)
    end

    subgraph LAN
        GW(Edge Gateway)
    end


    MED -.-> |Connessione al servizio HTML5 ; TCP 8080| HTML5
    HTML5 --> |TLS Tunnel| MED
    MED ~~~ GW
    GW --> |TLS Tunnel| MED
    GW ~~~ MED

    linkStyle 0 stroke:#d22,color;

Hold "Ctrl" to enable pan & zoom

In questo contesto sarà necessario aggiungere al file /etc/ipdiva/httpd/commonParameters.extra.conf le informazioni indicate di seguito, oppure creare tale file.
È possibile personalizzare le impostazioni:

Valore personalizzato	Variabile	Commento
	HTML5_URL_DMZ	URL configurata al momento della dichiarazione dell'HTML5 Gateway nella console di amministrazione.
	HTML5_IP_DMZ	Nome DNS o indirizzo IP del server Docker sul quale l'HTML5 Gateway Docker è attivo.
	HTML5_PORT_DMZ	Porta pubblicata dal server Docker per l'HTML5 Gateway Docker.

<Location /HTML5_URL_DMZ/>
    Order allow,deny
    Allow from all
    ProxyPass http://HTML5_IP_DMZ:HTML5_PORT_DMZ/systanciaHTML5-6.0/ flushpackets=on
    ProxyPassReverse http://HTML5_IP_DMZ:HTML5_PORT_DMZ
</Location>

<Location /HTML5_URL_DMZ/websocket-tunnel>
    Order allow,deny
    Allow from all
    ProxyPass ws://HTML5_IP_DMZ:HTML5_PORT_DMZ/systanciaHTML5-6.0/websocket-tunnel
    ProxyPassReverse ws://HTML5_IP_DMZ:HTML5_PORT_DMZ/systanciaHTML5-6.0/websocket-tunnel
</Location>

Lo schema generale è il seguente:

flowchart LR
    subgraph DMZ
        direction TB
        MED(Mediation Controller)
    end

    subgraph LAN
        HTML5(HTML5 Gateway Docker)
        GW(Edge Gateway)
    end


    MED -.- | Connessione al servizio HTML5 ; tramite tunnel TLS| GW -.-> |Connessione al servizio HTML5 ; TCP 8080| HTML5
    HTML5 --> |TLS Tunnel| MED
    GW --> |TLS Tunnel| MED

    linkStyle 0,1 stroke:#d22,color;

Hold "Ctrl" to enable pan & zoom

In questo contesto sarà necessario aggiungere al file /etc/ipdiva/httpd/commonParameters.extra.conf le informazioni indicate di seguito, oppure creare tale file.
È possibile personalizzare le impostazioni:

Valore personalizzato	Variabile	Commento
	HTML5_URL_LAN	URL configurata al momento della dichiarazione dell'HTML5 Gateway nella console di amministrazione.
	GW_NAME_LAN	Nome dell'Edge Gateway utilizzato per connettersi al servizio HTML5. Il carattere barra verticale a fine riga deve essere conservato.
	ORGANIZATION_NAME_LAN	Nome dell'organizzazione alla quale si connette l'Edge Gateway.
	HTML5_IP_LAN	Nome DNS o indirizzo IP del server Docker sul quale l'HTML5 Gateway Docker è attivo.
	HTML5_PORT_LAN	Porta pubblicata dal server Docker per l'HTML5 Gateway Docker.

<Location /HTML5_URL_LAN/>
    Order allow,deny
    Allow from all
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-IPdiva-Gateway GW_NAME_LAN|
    RequestHeader set X-IPdiva-Orgname ORGANIZATION_NAME_LAN
    RequestHeader set X-IPdiva-Service HTML5_IP_LAN:HTML5_PORT_LAN

    ProxyPass http://127.0.0.1:9016/systanciaHTML5-6.0/ flushpackets=on
</Location>

<Location /HTML5_URL_LAN/websocket-tunnel>
    Order allow,deny
    Allow from all
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-IPdiva-Gateway GW_NAME_LAN|
    RequestHeader set X-IPdiva-Orgname ORGANIZATION_NAME_LAN
    RequestHeader set X-IPdiva-Service HTML5_IP_LAN:HTML5_PORT_LAN

    ProxyPass ws://127.0.0.1:9016/systanciaHTML5-6.0/websocket-tunnel
</Location>

Suggerimento

Questa configurazione può essere utilizzata anche nella situazione seguente, in cui un Edge Gateway Docker e un HTML5 Gateway Docker sono in esecuzione nella stessa rete Docker:

flowchart LR
    subgraph DMZ
        direction TB
        MED(Mediation Controller)
    end

    subgraph LAN
        subgraph docker[Docker Server]
            HTML5([HTML5 Gateway Docker])
            GW([Edge Gateway])
        end
    end


    MED -.- | Connessione al servizio HTML5 ; tramite tunnel TLS| GW -.-> |Connessione al servizio HTML5 ; TCP 8080 tramite la rete Docker| HTML5
    HTML5 --> |TLS Tunnel| MED
    GW --> |TLS Tunnel| MED

    linkStyle 0,1 stroke:#d22,color;

Hold "Ctrl" to enable pan & zoom

Esempio

In questo esempio distribuiremo un Edge Gateway e un HTML5 Gateway sullo stesso server Docker.

L'infrastruttura utilizzata per l'esempio è la seguente:

• Server Mediation Controller
  • Indirizzo IP web: 10.0.10.10
  • Nome dell'organizzazione: my-organization-name
  • Token per l'Edge Gateway: YJ5N-JN05-N5LS-N26H-7JHA-HZ9R-BGJF-MAVH
  • Token per l'HTML5 Gateway: ATCW-OMVR-0RY4-LW1M-D9G9-H5VF-WPX5-YCXF
  • URL di accesso al servizio HTML5: HTML5_DOCKER
• Server Docker
  • Nome della rete Docker: cyberelements-cleanroom-network
  • Edge Gateway
    • Name: my-edge-gateway-docker
    • Percorso radice nel file system: /opt/my-edge-gateway-docker
  • HTML5 Gateway
    • Name: my-html5-gateway-docker
    • Percorso radice nel file system: /opt/my-html5-gateway-docker

Innanzitutto, sul server Docker, è necessario creare l'albero di directory per il montaggio dei volumi Docker:

mkdir -p /opt/my-edge-gateway-docker/config
mkdir /opt/my-edge-gateway-docker/graphical_archives
mkdir /opt/my-edge-gateway-docker/ssh_archives
mkdir /opt/my-edge-gateway-docker/log
mkdir -p /opt/my-html5-gateway-docker/config
mkdir /opt/my-html5-gateway-docker/log

Creare quindi una rete Docker di tipo bridge affinché i due container possano comunicare tra loro:

docker network create -d bridge cyberelements-cleanroom-network

Avviare poi il container dell'Edge Gateway. Si noti che l'esempio stabilisce una connessione tramite pairing, con accesso al Mediation Controller tramite il suo indirizzo IP e senza verifica del certificato. Inoltre, viene aggiunto il parametro --network per indicare l'utilizzo della rete Docker creata in precedenza:

docker run -d --restart unless-stopped --name "my-edge-gateway-docker" \
-e ENV_MEDIATION="10.0.10.10" \
-e ENV_TOKEN="YJ5N-JN05-N5LS-N26H-7JHA-HZ9R-BGJF-MAVH" \
-e ENV_NO_CHECK_CERT="true" \
-v "/opt/my-edge-gateway-docker/config/:/etc/ipdiva/:rw" \
-v "/opt/my-edge-gateway-docker/graphical_archives/:/var/lib/ipdiva/carerecord/archives/:rw" \
-v "/opt/my-edge-gateway-docker/ssh_archives/:/var/ipdiva/care/sshrecord/:rw" \
-v "/opt/my-edge-gateway-docker/log/:/var/log/:rw" \
-p 2222:2222 \
-p 3389:3389 \
-p 8443:8443 \
--network="cyberelements-cleanroom-network" \
cleanroom-gateway:4.6.1-33-v2

Avviare poi il container dell'HTML5 Gateway. Si noti che l'esempio stabilisce una connessione tramite pairing, con accesso al Mediation Controller tramite il suo indirizzo IP e senza verifica del certificato. Inoltre, viene aggiunto il parametro --network per indicare l'utilizzo della rete Docker creata in precedenza e, poiché l'accesso al servizio HTML5 avverrà attraverso la rete Docker, non è necessario pubblicare la porta 8080:

docker run -d --restart unless-stopped --name "my-html5-gateway-docker" \
-e ENV_MEDIATION="10.0.10.10" \
-e ENV_TOKEN="ATCW-OMVR-0RY4-LW1M-D9G9-H5VF-WPX5-YCXF" \
-e ENV_NO_CHECK_CERT="true" \
-v "/opt/my-html5-gateway-docker/config/:/etc/ipdiva/:rw" \
-v "/opt/my-html5-gateway-docker/log/:/var/log/:rw" \
--network="cyberelements-cleanroom-network" \
cleanroom-html5:4.6.1-33-v2

Infine, è necessario configurare il file /etc/ipdiva/httpd/commonParameters.extra.conf del o dei server Mediation Controller. Deve essere aggiunta la sezione seguente:

<Location /HTML5_DOCKER/>
    Order allow,deny
    Allow from all
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-IPdiva-Gateway my-edge-gateway-docker|
    RequestHeader set X-IPdiva-Orgname my-organization-name
    RequestHeader set X-IPdiva-Service my-html5-gateway-docker:8080

    ProxyPass http://127.0.0.1:9016/systanciaHTML5-6.0/ flushpackets=on
</Location>

<Location /HTML5_DOCKER/websocket-tunnel>
    Order allow,deny
    Allow from all
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-IPdiva-Gateway my-edge-gateway-docker|
    RequestHeader set X-IPdiva-Orgname my-organization-name
    RequestHeader set X-IPdiva-Service my-html5-gateway-docker:8080

    ProxyPass ws://127.0.0.1:9016/systanciaHTML5-6.0/websocket-tunnel
</Location>

Prima di applicare la nuova configurazione, occorre verificare che non provochi alcun errore bloccante per il server web Apache2.
A tale scopo, eseguire il comando seguente:

apache2ctl configtest

Se la risposta è Syntax OK, le modifiche possono essere applicate con il comando sottostante. In caso contrario, verificare la configurazione del proprio file /etc/ipdiva/httpd/commonParameters.extra.conf.

systemctl reload apache2