Ambiente de desenvolvimento SIGAA, SIGRH, SIPAC e SIGAdmin usando Docker

Manual do Repositório Ambiente Docker

Repositório GIT: https://git.ufla.br/sig-ufrn/ambiente-docker

Este repositório contém os arquivos necessários para construir e executar ambientes Docker do SIGUFRN com JBoss 5.1.0.GA. A estrutura separa ambientes de desenvolvimento, homologação e produção, além de manter recursos compartilhados e scripts auxiliares para testes.

Pré-requisitos

-

• Docker instalado.

  -

• Docker Compose instalado.

  -

• Git LFS instalado, pois o repositório versiona arquivos binários grandes, como JBoss, JDK e agentes de monitoramento.

sudo apt-get install git-lfs
git lfs install

Estrutura Geral

.
├── dev/                  # Ambiente de desenvolvimento
├── homolog/              # Ambiente de homologação
├── prod/                 # Ambiente de produção
├── resources/            # Recursos compartilhados para build e monitoramento
├── testes/               # Scripts de apoio para carga, rate limit e PostgreSQL
├── README.md             # Visão inicial do repositório
└── MANUAL.md             # Este manual

Ambientes Disponíveis

Ambiente	Diretório	Container principal	Uso esperado
Desenvolvimento	dev/	jboss_dev	Execução local com debug remoto e volumes de workspace.
Homologação	homolog/	jboss-homolog	Ambiente com JBoss e PostgreSQL no Compose.
Produção	prod/	jboss	Execução do JBoss em produção.

Cada ambiente possui seus próprios arquivos Dockerfile, compose.yaml, env.conf, README.md, add_user_host.sh e limpar-jboss.sh.

Componentes Principais

-

• Dockerfile: constrói a imagem do JBoss customizado.

  -

• compose.yaml: define containers, portas, volumes, rede, usuário e limites de memória.

  -

• env.conf: sobrescreve ou define `JAVA_OPTS` usados pelo JBoss.

  -

• add_user_host.sh: cria o usuário/grupo `sistemas` no host e ajusta permissões dos diretórios montados.

  -

• limpar-jboss.sh: remove componentes desnecessários do JBoss durante o build da imagem.

  -

• config/: contém arquivos copiados para dentro da imagem no momento do build.

  -

• ear_sistemas/: contém EARs, WARs, JARs e arquivos de configuração das aplicações.

  -

• logs/: recebe logs do JBoss montados a partir do container.

  -

• resources/: contém recursos base, como `jboss-5.1.0.GA-jdk6.zip`, JDK e agentes de monitoramento.

Arquitetura Docker

O build usa duas etapas:

1. 1. Uma etapa builder, baseada em Alpine, que descompacta o JBoss, remove instâncias e bibliotecas desnecessárias e aplica arquivos de configuração.

2. 2. Uma etapa final, baseada em amazoncorretto:8-alpine, que recebe o JBoss preparado, instala dependências de fonte/timezone, cria o usuário sistemas e executa o servidor.

O JBoss é iniciado com:

/opt/jboss-5.1.0.GA/bin/run.sh -b 0.0.0.0 -p 8080 -c inst1

Diretórios Montados

Os ambientes montam diretórios do host dentro do container. Os principais são:

Host	Container	Finalidade
./ear_sistemas	/opt/sistemas/ear	Artefatos das aplicações e configurações
./pobox	/opt/pobox	Arquivos do SIAFI
./usersOnline	/var/jboss_config/usersOnline	Dados de usuários online.
./sistemas/comum	/var/sistemas/comum	Arquivos comuns dos sistemas.
./comum	/var/comum	Arquivos comuns adicionais
./logs	/opt/jboss-5.1.0.GA/server/inst1/log	Logs do JBoss.
./fonts	/usr/share/fonts	Fontes usadas pelas aplicações.

No ambiente dev, também há volumes para workspace local:

- /caminho/para/LIBS:/sig-ufrn/eclipse-workspace/LIBS/
- /caminho/para/SharedResources:/sig-ufrn/eclipse-workspace/SharedResources/
- /caminho/para/Sistema:/sig-ufrn/eclipse-workspace/Sistema/

Esses caminhos devem ser ajustados no dev/compose.yaml conforme a máquina do desenvolvedor.

Configuração Inicial

1. Copiar Recursos

Cada ambiente espera uma pasta `resources/` local para o build. Copie a pasta da raiz para o ambiente desejado:

```bash

cp -r ../resources ./

```

Execute o comando dentro de `dev/`, `homolog/` ou `prod/`.

###

2. Configurar Fontes

A pasta `fonts/` deve conter as fontes esperadas pelo Compose, incluindo arquivos como:

- `

• Arimo-Italic-VariableFont_wght.ttf`

  - `ttf

• Arimo-VariableFont_wght.ttf`

  - `ttf

• Century Gothic.ttf`

  - `ttf

• EnglishTowne.ttf`

  - ttf

• arquivos da pasta `static/`

###

3. Configurar `ear_sistemas`

ear_sistemas

A pasta `ear_sistemas/` deve conter os artefatos e configurações necessários para o ambiente.

Para desenvolvimento, normalmente são necessários:

- `

• libs.jar/remotehosts.properties`

  - `properties

• libs.jar/ldap.properties`

  - `properties

• postgres-ds.xml`

  - xml

• EARs opcionais, como `admin.ear`
  ear

Para homologação e produção, normalmente são necessários:

- `

• libs.jar/remotehosts.properties`

  - `properties

• libs.jar/ldap.properties`

  - `properties

• postgres-ds.xml`

  - `xml

• barramentoservicos.ear`

  - `ear

• dto.jar`

  - `jar

• servicos.ear`

  - `ear

• shared.ear`

  - `ear

• sigaa.ear`

  - `ear

• sipac.ear`

  - `ear

• sigrh.ear`

  - `ear

• admin.ear`

  - `ear

• sigpp.ear`

  - `ear

• probe.war`
  war

###

4. Ajustar `env.conf`

conf

Revise `JAVA_OPTS`JAVA_OPTS conforme os recursos disponíveis na máquina.

Parâmetros importantes:

• - `-Xms`:Xms: memória inicial da JVM.

• - `-Xmx`:Xmx: memória máxima da JVM.

  - `

• -XX:MetaspaceSize`:MetaspaceSize: tamanho inicial do Metaspace.

  - `

• -XX:MaxMetaspaceSize`:MaxMetaspaceSize: tamanho máximo do Metaspace.

  - `

• -Dbr.ufrn.jboss.instanceName`:instanceName: nome da instância JBoss.

  - `

• -Dfile.encoding=ISO-8859-1`:1: encoding usado pela aplicação.

  
  

No `dev`,dev, o debug remoto já fica habilitado na porta `8787`.8787.

##

Permissões

O container executa com o usuário `sistemas`. Para evitar problemas de escrita nos volumes, crie o mesmo usuário/grupo no host e ajuste a propriedade dos diretórios montados.

Dentro do diretório do ambiente, execute:

```bash

sudo ./add_user_host.sh

```

O script cria UID/GID `8080` e aplica `chown` nos diretórios:

- `comum`

- `ear_sistemas`

- `fonts`

- `logs`

- `pobox`

- `sistemas`

- `usersOnline`

No `dev/compose.yaml`, os argumentos de build atuais usam `TARGET_UID=1000` e `TARGET_GID=1000`. Ajuste esses valores ou o script conforme o UID/GID necessário no host.

## Build da Imagem

Entre no diretório do ambiente desejado e execute:

```bash

docker compose build --no-cache

```

Alternativamente, sem Compose:

```bash

docker build -t sigufrn --progress=plain --no-cache .

```

Alterações em `Dockerfile`, `config/` ou `limpar-jboss.sh` exigem novo build da imagem.

## Execução

Entre no diretório do ambiente e suba os containers:

```bash

docker compose up -d

```

Para acompanhar os logs:

```bash

docker logs -f jboss_dev

```

Em homologação:

```bash

docker logs -f jboss-homolog

```

Em produção:

```bash

docker logs -f jboss

```

Para acessar o shell:

```bash

docker exec -it jboss_dev /bin/sh

```

Ou ajuste o nome do container conforme o ambiente.

## Portas

| Ambiente | Porta | Serviço |

| --- | --- | --- |

| `dev`, `homolog`, `prod` | `8080` | Aplicação JBoss. |

| `dev` | `8787` | Debug remoto Java. |

| `homolog` | `15432` | PostgreSQL exposto no host. |

| opcional | `9404` | Métricas JMX Exporter. |

| opcional | `4000` | Glowroot. |

| opcional `dev` | `8025` | Interface MailPit. |

| opcional `dev` | `1025` | SMTP MailPit. |

| opcional `dev` | `8079` | Dozzle. |

## Ambiente de Desenvolvimento

O ambiente `dev/` usa a imagem `ufla/jboss-5.1.0.ga-dev:2.1.0` e expõe a porta `8787` para debug remoto.

Para configurar o debug no Eclipse:

1. Acesse `Run > Debug Configurations...`.

2. Crie uma configuração em `Remote Java Application`.

3. Use `localhost` ou `127.0.0.1` como host.

4. Use a porta `8787`.

5. Clique em `Apply` e depois em `Debug`.

O `dev/compose.yaml` também contém blocos comentados para MailPit e Dozzle.

### MailPit

Para interceptar e-mails, descomente o serviço `mailpit` no `dev/compose.yaml` e configure a aplicação para usar:

- host: `mailpit-sigufrn`

- porta SMTP: `1025`

- interface web: `http://127.0.0.1:8025/`

### Dozzle

Para visualizar logs pelo navegador, descomente o serviço `dozzle` no `dev/compose.yaml` e acesse:

```text

http://127.0.0.1:8079/

```

## Ambiente de Homologação

O ambiente `homolog/` sobe dois serviços:

- `jboss`, com container `jboss-homolog`.

- `postgres`, com container `postgres`.

O PostgreSQL usa a imagem `postgres:18-alpine`, volume Docker `pg_data` e arquivo `postgres-env.conf`.

Revise principalmente:

```conf

POSTGRES_USER=postgres

POSTGRES_PASSWORD=password

POSTGRES_DB=postgres

POSTGRES_HOST_AUTH_METHOD=md5

```

Não mantenha senha padrão em ambiente compartilhado.

## Ambiente de Produção

O ambiente `prod/` sobe somente o serviço JBoss definido no `compose.yaml`.

Cuidados recomendados:

- Validar `env.conf` antes de subir o ambiente.

- Validar permissões dos volumes antes do deploy.

- Garantir que `ear_sistemas/` contenha os artefatos corretos da versão a ser publicada.

- Não versionar logs, EARs, dados de runtime ou segredos.

- Recriar o container em janelas controladas de manutenção.

Para recriar o container:

```bash

docker compose stop jboss

docker compose pull

docker compose up -d jboss --force-recreate

```

## Observabilidade

O repositório contém agentes em `resources/monitoring/`:

- Glowroot para traces.

- JMX Exporter para métricas Prometheus.

Para habilitar:

1. Copie `resources/monitoring/` para o ambiente desejado.

2. Descomente o volume `./monitoring/:/opt/monitoring/` no `compose.yaml`.

3. Exponha as portas `4000` e `9404` no `Dockerfile` e no `compose.yaml`.

4. Descomente os agentes no `env.conf`.

As métricas do JMX Exporter ficam em `9404`. O arquivo padrão `resources/monitoring/jmx_exporter/config.yaml` usa autenticação básica com usuário `admin` e senha `admin`; altere antes de usar fora de ambiente local.

O Glowroot fica disponível em `4000`. No primeiro acesso, cadastre usuário e senha em `Administration > Users > Add new`.

## Testes e Scripts de Apoio

### Teste de Carga

Diretório: `testes/teste_carga/`

Simula vários usuários registrando ponto no SIGRH.

Configuração básica:

```bash

python3 -m venv venv

source venv/bin/activate

python3 -m pip install -r ./requirements.txt

cp .env.sample .env

```

Depois, ajuste o `.env` e configure usuários de teste no banco conforme o README do diretório.

### Rate Limit

Diretório: `testes/ratelimit/`

Scripts disponíveis:

```bash

python3 teste-rate-limit.py

python3 teste-rate-limit-navegacao.py

```

### Consultas PostgreSQL

Diretório: `testes/consultas_postgres/`

Contém SQL para salvar periodicamente consultas em execução no PostgreSQL.

Exemplo de execução:

```bash

export PGPASSWORD='password'

watch -n 1 psql -h 127.0.0.1 -d <bd> -U <user> -f salvar_consultas.sql

```

## Arquivos Ignorados

O `.gitignore` exclui diretórios e arquivos de runtime, como:

- `dev/ear_sistemas/`, `homolog/ear_sistemas/`, `prod/ear_sistemas/`

- `logs/`

- `resources/` copiado para cada ambiente

- `fonts/` por ambiente

- `pobox/`, `usersOnline/`, `comum/`, `sistemas/comum/`

- `.env` dos testes

- ambientes virtuais Python

Isso evita versionar artefatos grandes, dados sensíveis, logs e arquivos específicos de máquina.

## Fluxo Recomendado de Uso

Para configurar um ambiente do zero:

1. Entre no diretório do ambiente: `dev/`, `homolog/` ou `prod/`.

2. Copie `../resources` para o diretório atual.

3. Prepare `fonts/`.

4. Prepare `ear_sistemas/` com EARs, WARs, JARs e arquivos de configuração.

5. Ajuste `env.conf`.

6. Ajuste volumes e portas no `compose.yaml`.

7. Configure permissões com `sudo ./add_user_host.sh`.

8. Gere a imagem com `docker compose build --no-cache`.

9. Suba o ambiente com `docker compose up -d`.

10. Valide logs com `docker logs -f <container>`.

## Solução de Problemas

### Erro de permissão em volumes

Execute novamente `sudo ./add_user_host.sh` no diretório do ambiente e confira se o UID/GID do container corresponde ao usuário do host.

### Alteração em arquivos de `config/` não aparece no container

Arquivos de `config/` são copiados durante o build. Gere a imagem novamente com `docker compose build --no-cache`.

### JBoss não encontra EARs ou arquivos de configuração

Confira se `ear_sistemas/` existe, se os arquivos foram copiados corretamente e se os volumes estão apontando para o caminho correto no `compose.yaml`.

### Debug remoto não conecta no desenvolvimento

Confira se o container `jboss_dev` está em execução, se a porta `8787` está exposta e se o Eclipse usa `localhost:8787`.

### Métricas ou traces não aparecem

Confira se os agentes foram copiados, se o volume `monitoring` está montado, se as portas foram expostas e se as linhas do `env.conf` foram descomentadas.