Ir para o conteúdo principal

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. Uma etapa builder, baseada em Alpine, que descompacta o JBoss, remove instâncias e bibliotecas desnecessárias e aplica arquivos de configuração.
  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:

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
  • Arimo-VariableFont_wght.ttf
  • Century Gothic.ttf
  • EnglishTowne.ttf
  • arquivos da pasta static/


3. Configurar 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
  • libs.jar/ldap.properties
  • postgres-ds.xml
  • EARs opcionais, como admin.ear


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

  • libs.jar/remotehosts.properties
  • libs.jar/ldap.properties
  • postgres-ds.xml
  • barramentoservicos.ear
  • dto.jar
  • servicos.ear
  • shared.ear
  • sigaa.ear
  • sipac.ear
  • sigrh.ear
  • admin.ear
  • sigpp.ear
  • probe.war


4. Ajustar env.conf

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

Parâmetros importantes:

  • -Xms: memória inicial da JVM.
  • -Xmx: memória máxima da JVM.
  • -XX:MetaspaceSize: tamanho inicial do Metaspace.
  • -XX:MaxMetaspaceSize: tamanho máximo do Metaspace.
  • -Dbr.ufrn.jboss.instanceName: nome da instância JBoss.
  • -Dfile.encoding=ISO-8859-1: encoding usado pela aplicação.

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


Permissões


O container executa com o usuário `sistemas`.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`8080 e aplica `chown`chown nos diretórios:


- `comum`

- `ear_sistemas`

- `fonts`

- `logs`

- `pobox`

- `sistemas`

- `usersOnline`


  • comum
  • ear_sistemas
  • fonts
  • logs
  • pobox
  • sistemas
  • usersOnline

No `dev/compose.yaml`,yaml, os argumentos de build atuais usam `TARGET_UID=1000`1000 e `TARGET_GID=1000`.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`,Dockerfile, `config/` ou `limpar-jboss.sh`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, Portashomolog, prod


8080

| Ambiente | Porta | Serviço |

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

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

| `dev` | `8787` | dev

8787

Debug remoto Java. |Java

| `homolog` | `15432` | homolog

15432

PostgreSQL exposto no host. |host

| opcional | `9404` |

9404

Métricas JMX Exporter. |Exporter

| opcional

4000

Glowroot

opcional |dev

8025

Interface `4000` | Glowroot. |MailPit

| opcional `dev`dev

1025

SMTP | `8025` | Interface MailPit. |MailPit

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

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

Dozzle


##

Ambiente de Desenvolvimento


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


Para configurar o debug no Eclipse:


1.

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

    2.

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

    3.

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

    4.

  4. Use a porta `8787`.

    5. 8787.

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


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


###

MailPit


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


-

  • host: `mailpit-sigufrn`

    - sigufrn

  • porta SMTP: `1025`

    - 1025

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


###

Dozzle


Para visualizar logs pelo navegador, descomente o serviço `dozzle`dozzle no `dev/compose.yaml`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.

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

    2.

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

    3.

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

    4.

  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.

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

    2.

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

    3.

  3. Prepare `fonts/`.

    4.

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

    5.

  5. Ajuste `env.conf`.

    6.

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

    7.

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

    8.

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

    9.

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

    10.

  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.


Voltar ao topo