> Source: https://docs.cyberelements.io/bastion/4.6/pt/Installation/Docker/HTML5Gateway/

# Instalar o HTML5 Gateway Docker

## Importação da imagem Docker

Antes de poder criar um contentor HTML5 Gateway Docker, deve importar a imagem Docker. Para isso, abra uma shell a partir da qual disponha dos comandos Docker, bem como do ficheiro `cleanroom-html5-4.6.1-33-v2.tgz`. A partir da shell, execute o comando seguinte, ajustando o caminho do ficheiro `TGZ` se este não se encontrar no diretório atual:

```
1
```

Em seguida, verifique se a importação foi bem-sucedida com o comando seguinte:

```
1
```

O resultado esperado é o seguinte. Se não for esse o caso, a importação falhou:

```
1
2
3
4
5
6
```

> **Resultado completo**
>
> ```
>  1
>  2
>  3
>  4
>  5
>  6
>  7
>  8
>  9
> 10
> 11
> 12
> 13
> 14
> 15
> 16
> 17
> 18
> 19
> 20
> 21
> 22
> 23
> 24
> 25
> 26
> 27
> 28
> 29
> 30
> 31
> 32
> 33
> 34
> 35
> 36
> 37
> 38
> 39
> 40
> 41
> 42
> 43
> 44
> 45
> 46
> 47
> 48
> 49
> 50
> 51
> 52
> 53
> 54
> 55
> 56
> 57
> 58
> 59
> 60
> 61
> 62
> 63
> 64
> 65
> 66
> 67
> 68
> 69
> 70
> 71
> 72
> 73
> ```

## Configuração do contentor

### Variáveis de ambiente

#### Variáveis para a implementação por pairing

| Nome | Obrigatório | Valor predefinido | Comentário |
|---|---|---|---|
| `ENV_MEDIATION` | SIM |  | Utilizado para a ligação por pairing. Indica o nome DNS ou o endereço IP para ligar à interface web de uma plataforma CyberElements Bastion. |
| `ENV_TOKEN` | SIM |  | Utilizada para a ligação por pairing. Indica o token de pairing a utilizar para a ligação ao Mediation Controller. |
| `ENV_NO_CHECK_CERT` | NÃO | `false` | Utilizado para as ligações por pairing. Desativa ou não a verificação do certificado web do Mediation Controller; é útil com CyberElements Bastion quando o acesso é feito por endereço IP ou quando o certificado web não é reconhecido pelas autoridades de certificação públicas predefinidas. Valores aceites: `true` ou `false`. |

#### Variáveis para a implementação manual

| Nome | Obrigatório | Valor predefinido | Comentário |
|---|---|---|---|
| `ENV_GW_CERT_NAME` | SIM |  | Utilizada para a ligação com configuração manual. Nome do ficheiro de certificado para a ligação ao SSL Router. |
| `ENV_GW_CERT_PASSWORD` | SIM |  | Utilizada para a ligação com configuração manual. Palavra-passe do ficheiro de certificado para a ligação ao SSL Router. |
| `ENV_SSL_ROUTER_IP` | SIM |  | Utilizado para a ligação com configuração manual. Endereço IP ou nome DNS do SSL Router ao qual o HTML5 Gateway se ligará. |
| `ENV_SSL_ROUTER_PORT` | NÃO | `443` | Utilizado para a ligação com configuração manual. Porta do SSL Router ao qual o HTML5 Gateway se ligará. |

#### Variáveis diversas

| Nome | Obrigatório | Valor predefinido | Comentário |
|---|---|---|---|
| `ENV_DISABLE_RSYSLOG` | NÃO | `false` | Desativação do serviço `rsyslog`. Valores aceites: `true` ou `false`. |

### Volumes

| Volume | Comentário |
|---|---|
| `/etc/ipdiva/` | Volume de configuração do HTML5 Gateway. Recomendamos que o monte num volume com nome ou no sistema de ficheiros da máquina anfitriã. |
| `/opt/certificates/` | Volume que contém o ou os certificados do HTML5 Gateway em caso de configuração sem pairing. |
| `/var/log/` | Volume que contém os logs do HTML5 Gateway. |

### Portas

| Porta | Comentário |
|---|---|
| `8080` | Porta de escuta do serviço HTML5. |

## Implementação do HTML5 Gateway Docker

### Implementação com pairing

> **Pré-requisitos**
>
> Antes de implementar o HTML5 Gateway Docker, deve [obter um token de pairing](https://docs.cyberelements.io/bastion/4.6/pt/Usage/Configuration/AdminConsole/CreatePairingTokenForEdgeGateway/#__tabbed_1_2).

A implementação descrita a seguir utiliza todos os volumes disponíveis (exceto `/opt/certificates/`, que não é útil neste contexto) e expõe todas as portas.
Os volumes serão montados no sistema de ficheiros da máquina anfitriã na localização `HTML5_GATEWAY_REP`. No interior desta localização encontram-se os subdiretórios seguintes:

- config
- log

Pode personalizar as variáveis dos comandos seguintes:

| Valor personalizado | Variável | Comentário |
|---|---|---|
|  | `DOCKER_NAME` | Nome do contentor Docker. |
|  | `HTML5_GATEWAY_REP` | Localização no sistema de ficheiros onde montar os volumes. |
|  | `ENV_MEDIATION_VALUE` | Valor da [variável de ambiente](#environment-variables) `ENV_MEDIATION`. |
|  | `ENV_TOKEN_VALUE` | Valor da [variável de ambiente](#environment-variables) `ENV_TOKEN`. |
|  | `ENV_NO_CHECK_CERT_VALUE` | Valor da [variável de ambiente](#environment-variables) `ENV_NO_CHECK_CERT`. |

Crie a árvore de diretórios necessária para montar os volumes no sistema de ficheiros:

**Bash**

> ```
> 1
> 2
> ```

**PowerShell**

> ```
> 1
> ```

E, por último, inicie um novo contentor:

**Bash**

> ```
> 1
> 2
> 3
> 4
> 5
> 6
> 7
> 8
> ```

**PowerShell**

> ```
> 1
> 2
> 3
> 4
> 5
> 6
> 7
> 8
> ```

Os logs do contentor podem ser consultados com o comando seguinte:

```
1
```

### Implementação manual

> **Pré-requisitos**
>
> Antes de implementar o HTML5 Gateway Docker, deve dispor do certificado necessário para o HTML5 Gateway.

> **Palavras-passe visíveis com `docker inspect`**
>
> As variáveis de ambiente de um contentor, incluindo as palavras-passe dos certificados, continuam legíveis por qualquer pessoa autorizada a executar `docker inspect` no servidor Docker. Por isso, deve dar-se preferência à [implementação com pairing](#deployment-with-pairing), que não utiliza nenhuma palavra-passe de certificado.

A implementação descrita a seguir utiliza todos os volumes disponíveis e expõe todas as portas.
Os volumes são montados no sistema de ficheiros da máquina anfitriã na localização `MANUAL_REP`. Dentro desta localização encontram-se os seguintes subdiretórios:

- config
- log
- certificates

Pode personalizar as variáveis dos comandos seguintes:

| Valor personalizado | Variável | Comentário |
|---|---|---|
|  | `MANUAL_NAME` | Nome do contentor Docker. |
|  | `MANUAL_REP` | Localização no sistema de ficheiros onde montar os volumes. |
|  | `ENV_GW_CERT_NAME_VALUE` | Valor da [variável de ambiente](#environment-variables) `ENV_GW_CERT_NAME`. |
|  | `ENV_SSL_ROUTER_IP_VALUE` | Valor da [variável de ambiente](#environment-variables) `ENV_SSL_ROUTER_IP`. |
|  | `ENV_SSL_ROUTER_PORT_VALUE` | Valor da [variável de ambiente](#environment-variables) `ENV_SSL_ROUTER_PORT`. |

Crie a árvore de diretórios necessária para montar os volumes no sistema de ficheiros:

**Bash**

> ```
> 1
> 2
> 3
> ```

**PowerShell**

> ```
> 1
> ```

Em seguida, coloque os certificados do HTML5 Gateway e do serviço de gravação em `MANUAL_REP/certificates`.

Para que as palavras-passe dos certificados não fiquem guardadas no histórico da shell, introduza-as em variáveis de ambiente da sessão atual (o que é escrito não é apresentado):

**Bash**

> ```
> 1
> 2
> ```

**PowerShell**

> ```
> 1
> ```

Por último, inicie um novo contentor:

**Bash**

> ```
>  1
>  2
>  3
>  4
>  5
>  6
>  7
>  8
>  9
> 10
> ```

**PowerShell**

> ```
>  1
>  2
>  3
>  4
>  5
>  6
>  7
>  8
>  9
> 10
> ```

Depois de o contentor ter sido iniciado, remova estas variáveis da sessão:

**Bash**

> ```
> 1
> ```

**PowerShell**

> ```
> 1
> ```

Os logs do contentor podem ser consultados com o comando seguinte:

```
1
```

## Configuração do Mediation Controller

Para que o novo HTML5 Gateway Docker seja operacional, falta configurar o servidor Mediation Controller através de um acesso SSH ou de consola e com permissões `root`.

Esta última definição é necessária para permitir que o Mediation Controller comunique com o serviço HTML5.
No entanto, esta configuração varia em função da localização do HTML5 Gateway Docker:

**Colocado na DMZ**

> O esquema geral é o seguinte:
>
> ```mermaid
> flowchart LR
>     subgraph DMZ
>         direction TB
>         HTML5(HTML5 Gateway Docker)
>         MED(Mediation Controller)
>     end
>
>     subgraph LAN
>         GW(Edge Gateway)
>     end
>
>
>     MED -.-> |Ligação ao serviço HTML5 ; TCP 8080| HTML5
>     HTML5 --> |TLS Tunnel| MED
>     MED ~~~ GW
>     GW --> |TLS Tunnel| MED
>     GW ~~~ MED
>
>     linkStyle 0 stroke:#d22,color;
> ```
>
> Neste contexto, será necessário acrescentar ao ficheiro `/etc/ipdiva/httpd/commonParameters.extra.conf` as informações indicadas abaixo, ou então criá-lo.
> É possível personalizar as definições:
>
> | Valor personalizado | Variável | Comentário |
> |---|---|---|
> |  | `HTML5_URL_DMZ` | URL configurado ao declarar o HTML5 Gateway na consola de administração. |
> |  | `HTML5_IP_DMZ` | Nome DNS ou endereço IP do servidor Docker no qual o HTML5 Gateway Docker está ativo. |
> |  | `HTML5_PORT_DMZ` | Porta publicada pelo servidor Docker para o HTML5 Gateway Docker. |
>
> ```
>  1
>  2
>  3
>  4
>  5
>  6
>  7
>  8
>  9
> 10
> 11
> 12
> 13
> ```

**Colocado na LAN acessível por um Edge Gateway**

> O esquema geral é o seguinte:
>
> ```mermaid
> flowchart LR
>     subgraph DMZ
>         direction TB
>         MED(Mediation Controller)
>     end
>
>     subgraph LAN
>         HTML5(HTML5 Gateway Docker)
>         GW(Edge Gateway)
>     end
>
>
>     MED -.- | Ligação ao serviço HTML5 ; através do túnel TLS| GW -.-> |Ligação ao serviço HTML5 ; TCP 8080| HTML5
>     HTML5 --> |TLS Tunnel| MED
>     GW --> |TLS Tunnel| MED
>
>     linkStyle 0,1 stroke:#d22,color;
> ```
>
> Neste contexto, será necessário acrescentar ao ficheiro `/etc/ipdiva/httpd/commonParameters.extra.conf` as informações indicadas abaixo, ou então criá-lo.
> É possível personalizar as definições:
>
> | Valor personalizado | Variável | Comentário |
> |---|---|---|
> |  | `HTML5_URL_LAN` | URL configurado ao declarar o HTML5 Gateway na consola de administração. |
> |  | `GW_NAME_LAN` | Nome do Edge Gateway utilizado para ligar ao serviço HTML5. O caráter de barra vertical no fim da linha **deve ser conservado**. |
> |  | `ORGANIZATION_NAME_LAN` | Nome da organização à qual o Edge Gateway se liga. |
> |  | `HTML5_IP_LAN` | Nome DNS ou endereço IP do servidor Docker no qual o HTML5 Gateway Docker está ativo. |
> |  | `HTML5_PORT_LAN` | Porta publicada pelo servidor Docker para o HTML5 Gateway Docker. |
>
> ```
>  1
>  2
>  3
>  4
>  5
>  6
>  7
>  8
>  9
> 10
> 11
> 12
> 13
> 14
> 15
> 16
> 17
> 18
> 19
> 20
> 21
> ```
>
> > **Sugestão**
> >
> > Esta configuração também pode ser utilizada na situação seguinte, em que um Edge Gateway Docker e um HTML5 Gateway Docker são executados na mesma rede Docker:
> >
> > ```mermaid
> > 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 -.- | Ligação ao serviço HTML5 ; através do túnel TLS| GW -.-> |Ligação ao serviço HTML5 ; TCP 8080 através da rede Docker| HTML5
> >     HTML5 --> |TLS Tunnel| MED
> >     GW --> |TLS Tunnel| MED
> >
> >     linkStyle 0,1 stroke:#d22,color;
> > ```
> >
> > > **Exemplo**
> > >
> > > Neste exemplo, vamos implementar um Edge Gateway e um HTML5 Gateway no mesmo servidor Docker.
> > >
> > > A infraestrutura utilizada para o exemplo é a seguinte:
> > >
> > > - Servidor Mediation Controller
> > >     - Endereço IP web: `10.0.10.10`
> > >     - Nome da organização: `my-organization-name`
> > >     - Token para o Edge Gateway: `YJ5N-JN05-N5LS-N26H-7JHA-HZ9R-BGJF-MAVH`
> > >     - Token para o HTML5 Gateway: `ATCW-OMVR-0RY4-LW1M-D9G9-H5VF-WPX5-YCXF`
> > >     - URL de acesso ao serviço HTML5: `HTML5_DOCKER`
> > > - Servidor Docker
> > >     - Nome da rede Docker: `cyberelements-cleanroom-network`
> > >     - Edge Gateway
> > >         - Nome: `my-edge-gateway-docker`
> > >         - Localização raiz no sistema de ficheiros: `/opt/my-edge-gateway-docker`
> > >     - HTML5 Gateway
> > >         - Nome: `my-html5-gateway-docker`
> > >         - Localização raiz no sistema de ficheiros: `/opt/my-html5-gateway-docker`
> > >
> > > Em primeiro lugar, no servidor Docker, tem de criar a árvore de diretórios para montar os volumes Docker:
> > >
> > > ```
> > > 1
> > > 2
> > > 3
> > > 4
> > > 5
> > > 6
> > > ```
> > >
> > > Em seguida, crie uma rede Docker do tipo `bridge` para que os dois contentores possam comunicar entre si:
> > >
> > > ```
> > > 1
> > > ```
> > >
> > > Depois, inicie o contentor do Edge Gateway. Note que o exemplo estabelece uma ligação por pairing, com acesso ao Mediation Controller através do seu endereço IP e sem verificação de certificado adicional. Além disso, o parâmetro `--network` é acrescentado para indicar a utilização da rede Docker criada anteriormente:
> > >
> > > ```
> > >  1
> > >  2
> > >  3
> > >  4
> > >  5
> > >  6
> > >  7
> > >  8
> > >  9
> > > 10
> > > 11
> > > 12
> > > 13
> > > ```
> > >
> > > Depois, inicie o contentor do HTML5 Gateway. Note que o exemplo estabelece uma ligação por pairing, com acesso ao Mediation Controller através do seu endereço IP e sem verificação de certificado adicional. Além disso, o parâmetro `--network` é acrescentado para indicar a utilização da rede Docker criada anteriormente e, dado que o acesso ao serviço HTML5 será feito através da rede Docker, não é necessário publicar a porta 8080:
> > >
> > > ```
> > > 1
> > > 2
> > > 3
> > > 4
> > > 5
> > > 6
> > > 7
> > > 8
> > > ```
> > >
> > > Por último, é necessário configurar o ficheiro `/etc/ipdiva/httpd/commonParameters.extra.conf` no ou nos servidores Mediation Controller. Deve ser acrescentada a secção seguinte:
> > >
> > > ```
> > >  1
> > >  2
> > >  3
> > >  4
> > >  5
> > >  6
> > >  7
> > >  8
> > >  9
> > > 10
> > > 11
> > > 12
> > > 13
> > > 14
> > > 15
> > > 16
> > > 17
> > > 18
> > > 19
> > > 20
> > > 21
> > > ```

Antes de aplicar as novas definições, é necessário verificar que a nova configuração não provoca nenhum erro bloqueante no servidor web Apache2.
Para isso, execute o seguinte comando:

```
1
```

Se a resposta for `Syntax OK`, as alterações podem ser aplicadas com o comando abaixo. Caso contrário, verifique a configuração do seu ficheiro `/etc/ipdiva/httpd/commonParameters.extra.conf`.

```
1
```
