Manual de Instalação — AM2 Print Edge Agent (Docker)
O AM2 Print Edge Agent roda dentro da rede da clínica. Ele recebe as impressões DICOM das modalidades (TC, RM, US, RX…), decide para qual impressora mandar de acordo com as regras configuradas no AM2 Print Cloud e informa à nuvem tudo o que aconteceu.
O agente só faz conexões de saída (HTTPS) para a nuvem. Não é preciso abrir portas de entrada no firewall do hospital.
1. O que o agente faz
| Função | Descrição |
|---|---|
| DICOM Print SCP | Recebe impressões das modalidades na porta TCP 11112 (configurável). |
| Montagem de página | Converte o filme DICOM em PDF A3/A4. |
| Roteamento | Aplica as regras da nuvem: por tipo de exame, aparelho, dia, horário, impressão automática ou manual, contingência. |
| Impressão em papel | Envia para impressoras de rede por RAW/JetDirect (9100), IPP (631), LPD (515) ou fila CUPS. |
| Descoberta de impressoras | Varre a rede local quando você clica em “Buscar impressoras” no sistema. |
| PACS (opcional) | Consulta C-FIND para completar dados do paciente. |
| Sincronização | Envia status e histórico de trabalhos para a nuvem a cada 30 segundos. |
Situação das funções
| Função | Situação |
|---|---|
| Receber DICOM Print e gerar PDF | Disponível |
| Roteamento por regras e contingência | Disponível |
| Impressão RAW / IPP / LPD / CUPS | Disponível — homologar em cada modelo de impressora |
| Consulta PACS (C-FIND) | Disponível, desligada por padrão |
| Envio de nova série ao PACS (C-STORE) | Em teste (v0.6.0) — ligue em Configurações DICOM; valide no cliente antes de uso em produção |
Envio da impressão ao PACS (v0.6.0, em teste)
Fluxo automático: recebe a impressão DICOM → lê nome/acesso/ID na imagem → confirma o exame no PACS → monta cabeçalho e rodapé → envia as páginas ao PACS como a série AM2 PRINT - IMPRESSAO no mesmo exame. A impressão física segue a regra da clínica e pode ficar aguardando liberação manual.
- Ligue em Configurações DICOM → Enviar a impressão montada ao PACS.
- No PACS, cadastre o AE do agente (ex.:
AM2PRINT2_SCU) com permissão de envio (C-STORE). - Se o exame não for confirmado no PACS, a série não é enviada (evita gravar no paciente errado); a impressão sai normalmente.
- Para reimprimir depois: Montar impressão → buscar o exame → série “AM2 PRINT - IMPRESSAO” → escolher a impressora.
2. Requisitos
Novidades da v0.15.1
- Trabalhos mostra o resultado confirmado pelo PACS e a data/hora de envio, separado da impressão física. O histórico permanece após expirar as miniaturas.
- Usuários da clínica: operadores vinculados a um agente acessam apenas Trabalhos e Balcão / Entrega; não alteram configurações nem excluem exames.
Novidades da v0.15.0
-
Trabalhos: Hoje, Ontem, Últimos 7 dias, Todos e intervalo personalizado, com paginação.
-
Configurações DICOM: perfil Padrão atual ou Melhoria experimental por clínica. Padrão atual continua selecionado inicialmente.
-
Trabalhos → Comparar qualidade: folhas lado a lado e impressão de teste de cada perfil. Exige agente atualizado; trabalhos antigos/expirados podem não ter comparação. Até quatro folhas na comparação.
-
A melhoria usa janelamento quando disponível nos DICOM recuperados do PACS e nitidez leve. Impressões já renderizadas pelo aparelho não recebem um segundo janelamento. Não recupera detalhes ausentes, não usa IA e requer avaliação clínica em papel.
-
Comparar não imprime nem envia ao PACS. Impressões de teste de montagens também não geram série no PACS.
-
Montagens impressas enviam a folha ao PACS quando a opção da clínica estiver ligada e o estudo for confirmado novamente. O retorno aparece na prévia do trabalho. Salvar montagem continua sem imprimir ou arquivar automaticamente.
-
Atualize em Agentes locais → Atualizar agente; depois ative o envio em Configurações DICOM na clínica desejada e valide a nova série no PACS. Continua em teste.
-
Servidor ou PC na mesma rede das modalidades e das impressoras.
-
Linux Ubuntu Server 22.04/24.04 (recomendado) ou Windows 10/11 Pro / Server com WSL 2 + Docker Desktop.
-
2 vCPU, 4 GB RAM, 20 GB de disco.
-
Saída HTTPS (porta 443) liberada para a nuvem.
3. Instalação no Linux
3.1 Docker
sudo apt update && sudo apt install -y ca-certificates curl unzip
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER # saia e entre de novo na sessão
3.2 Antes de instalar: ver quais portas estão livres
Se o servidor já tem PACS ou outro sistema DICOM, confira as portas em uso:
ss -tulpn | grep -E ':(104|4210|11112|11114|11115|11116)\b'
- Porta que aparece na lista = ocupada. Não use.
- Escolha uma que não aparece (ex.: 11115) para
PRINT_SCP_PORT. - Use também um AE Title diferente do outro sistema (ex.:
AM2PRINT2).
Depois de instalado, o próprio agente verifica as portas e mostra em Configurações DICOM se a porta está livre e quais você pode usar.
3.3 Agente
- No AM2 Print Cloud, abra Agentes locais → Novo agente e copie o token.
- Baixe o pacote em Download do agente e descompacte:
sudo mkdir -p /opt/am2print-edge
sudo unzip am2-edge-agent.zip -d /opt/am2print-edge
sudo chown -R $USER /opt/am2print-edge
cd /opt/am2print-edge
cp .env.example .env
nano .env # cole o AGENT_TOKEN e confira CLOUD_URL
- Libere a porta DICOM e suba:
sudo ufw allow 11112/tcp comment "AM2 DICOM Print SCP"
docker compose up -d --build
docker compose logs -f
Em até 30 segundos o agente aparece online no sistema.
4. Instalação no Windows
- Ative a virtualização na BIOS (Intel VT-x / AMD-V).
- PowerShell como Administrador:
wsl --install -d Ubuntu - Instale o Docker Desktop com backend WSL 2.
- Descompacte o pacote em
C:\am2print-edge\, copie.env.examplepara.enve edite. - Libere a porta:
New-NetFirewallRule -DisplayName "AM2 DICOM Print SCP" -Direction Inbound -Protocol TCP -LocalPort 11112 -Action Allow
cd C:\am2print-edgeedocker compose up -d --build
No Windows, a busca de impressoras funciona melhor configurando
SCAN_SUBNETno.env(ex.:192.168.1.0/24), pois o Docker Desktop não enxerga a rede física diretamente.
5. Arquivo .env
CLOUD_URL=https://cloudside-bridge.lovable.app
AGENT_TOKEN=am2_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PRINT_SCP_AET=AM2_PRINT
PRINT_SCP_PORT=11112
# PACS (opcional)
PACS_ENABLED=false
PACS_AET=PACS_CENTRAL
PACS_HOST=192.168.1.100
PACS_PORT=104
LOCAL_SCU_AET=AM2_PRINT_SCU
AUTO_CSTORE_ENABLED=false
RETENTION_HOURS=48
SCAN_SUBNET=
# Tipo de exame por aparelho (usado nas regras por tipo de exame)
AET_MODALITY_MAP=CT_SALA1=CT,MR_3T=MR
O DICOM Print não informa o tipo de exame. O agente descobre pelo
AET_MODALITY_MAPou, se o AE Title do aparelho contiver CT, MR, US etc., automaticamente.
6. Configurar as modalidades
Dica: porta, AE Title e dados do PACS também podem ser alterados no AM2 Print Cloud em Configurações DICOM. O agente aplica em até 30 segundos e substitui os valores do
.env. Usar a porta 11112 igual ao PACS não tem problema se o agente estiver em outro computador.
No console de cada aparelho, cadastre uma impressora DICOM (DICOM Printer / Film Printer):
| Campo | Valor |
|---|---|
| AE Title | AM2_PRINT |
| IP | IP do servidor onde o agente roda |
| Porta | 11112 |
| Filme | 14x17 ou A3, conforme o fluxo |
Use o botão Verify / Echo do aparelho para testar a conexão.
7. Impressoras e regras (no sistema)
- Impressoras → Buscar agora: o agente varre a rede e lista o que encontrar. Clique em Adicionar.
- Regras de impressão → Nova regra. Exemplos:
- Tomografia → OKI C911, contingência Xerox 570, automática, todos os dias.
- Ressonância → Xerox 570, contingência OKI, automática.
- Plantão noturno: 19:00–07:00, impressão manual (fica aguardando liberação).
- Use Simular para conferir para onde um exame iria.
- Em Trabalhos, libere manualmente os que estiverem “Aguardando”.
A regra com menor número de prioridade que corresponder ao exame é a que vale. Se a impressora principal estiver fora do ar, o agente usa a contingência; se as duas estiverem fora, o trabalho fica aguardando.
Impressoras que precisam de driver (Fila CUPS local)
Algumas impressoras não aceitam o arquivo direto pela rede (ex.: Xerox Phaser 3020, Xerox com Fiery). Nesses casos, a impressora deve estar instalada no Linux (CUPS) e o agente manda o trabalho para essa fila.
- Veja as filas já instaladas no servidor:
lpstat -v
- Se a impressora não estiver na lista, instale (funciona na maioria das impressoras de rede modernas):
lpadmin -p NOME_DA_FILA -E -v ipp://IP_DA_IMPRESSORA/ipp/print -m everywhere
- Teste direto no Linux (deve sair uma folha):
echo "Teste AM2" > /tmp/teste.txt && lp -d NOME_DA_FILA /tmp/teste.txt
- No sistema, em Impressoras, cadastre com Protocolo: Fila CUPS local e no campo Nome da fila CUPS coloque o nome exato (ex.:
AM2_OKI_C911).
O docker-compose.yml já traz a linha /var/run/cups:/var/run/cups:ro, que permite ao agente usar as filas do Linux.
Dica: se o status em Trabalhos fica "Impresso" mas nada sai no papel, a impressora provavelmente precisa de driver. Use a Fila CUPS.
Para corrigir nome, IP, protocolo ou papel de uma impressora, clique no lápis em Impressoras. Não precisa excluir.
8. Manutenção
docker compose ps # status
docker compose logs -f # logs ao vivo
docker compose pull && docker compose up -d --build # atualizar
docker compose restart # reiniciar
Os arquivos recebidos ficam em ./data/spool e são apagados após o Tempo de guarda (padrão 48 horas), ajustável em Configurações DICOM. As imagens “como chegou / como ficou” do botão Visualizar em Trabalhos seguem o mesmo prazo (agente v0.10.0+).
9. Problemas comuns
| Sintoma | O que verificar |
|---|---|
| Agente “offline” no sistema | Token no .env, saída HTTPS liberada, docker compose logs. |
| Modalidade não conecta | Firewall na porta 11112, AE Title igual dos dois lados. |
| Impressão não sai | IP/porta da impressora; teste nc -vz IP 9100 no servidor. |
| Status "Impresso" mas nada sai | A impressora precisa de driver: use Fila CUPS local (seção 7). |
| Porta ocupada | Veja em Configurações DICOM as portas livres sugeridas pelo agente. |
| Busca não acha impressoras | Configure SCAN_SUBNET; algumas impressoras bloqueiam varredura. |
Cabeçalho e rodapé das impressões
Na nuvem, em Modelos de impressão, monte o cabeçalho e o rodapé (logo, nome do paciente, exame, data, QR code para o laudo, avisos). Depois, em Regras de impressão, escolha o modelo de cada regra. O agente aplica o modelo em cada folha antes de imprimir.
Observação: a impressão DICOM vinda do aparelho normalmente não traz os dados do paciente; nesses casos os campos de paciente saem em branco até a consulta ao PACS estar ativa.
Dados do paciente pelo PACS (C-FIND)
A impressão DICOM normalmente não traz o nome do paciente. Com o PACS ligado em Configurações DICOM e a opção Consulta ao PACS ativa, o agente pergunta ao PACS, a cada impressão recebida, qual exame é esse e preenche o cabeçalho (nome, ID, nascimento, idade, sexo, exame, accession, solicitante).
- Se o aparelho mandar o identificador do estudo, a busca é exata.
- Se não mandar, o agente pega o exame de hoje, da mesma modalidade, iniciado mais recentemente.
- Cadastre no PACS o AE Title do agente (campo "AE Title do agente") como cliente autorizado a consultar.
- Se o PACS não responder, a folha é impressa mesmo assim, sem os dados.
Montar impressão (busca no PACS)
No menu Montar impressão você busca o exame no PACS (nome, ID, accession, data), abre a série, escolhe as imagens (uma a uma ou "pular de N em N") e imprime em grades 1x1 até 5x6, em A3 ou A4, retrato ou paisagem. Acima de 20 imagens numa 4x5, o sistema divide em várias folhas.
Na folha, clique nas imagens para selecionar quais receberão ajustes ou use Selecionar todas (inclui todas as folhas). Os pré-filtros Mais escuro, Mais claro, Contraste forte e Original ajustam brilho/contraste; os controles permitem brilho e contraste de 20% a 200%, zoom de 100% a 300%, giro de 90° e espelhamento. Restaurar ajustes desfaz todas as alterações da seleção. O zoom amplia com corte central, podendo ocultar bordas da imagem. Os ajustes são aplicados pelo agente nas imagens de resolução original antes de gerar o PDF; o DICOM de origem permanece intacto. A prévia usa miniaturas, não é um visualizador diagnóstico; valide o resultado na impressora usada pela clínica.
Requisitos no PACS: liberar o AE Title do agente (ex.: AM2_PRINT_SCU) para C-FIND e C-GET. As imagens baixadas ficam em cache no agente (data/cache). O primeiro pedido pode levar até 30 s; depois o agente responde a cada 2 s enquanto a montagem estiver em uso. Após esta atualização, baixe o pacote novamente e atualize o agente para aplicar os ajustes.
Porta DICOM ocupada (Address already in use)
Se a porta escolhida já for usada por outro programa no mesmo servidor (PACS ou outro sistema DICOM), o agente não cai mais: ele continua ligado na porta do .env e mostra um aviso vermelho na tela Configurações DICOM. Basta escolher outra porta livre (ex.: 11115, 11116, 11120) e salvar. Não precisa reinstalar.
Renovar token
Em Agentes locais, clique em Renovar token, copie o novo token, troque a linha AGENT_TOKEN= no .env e rode docker compose down && docker compose up -d.
Busca no PACS por período
Em Montar impressão use Data inicial / Data final ou os atalhos Hoje, Ontem, Últimos 7 dias, Este mês e Qualquer data (esta exige nome, ID ou accession).
Proteção da busca no PACS (v0.3.0)
- Sem nome, ID ou accession: é obrigatório informar data inicial e final, com no máximo 60 dias.
- Cada busca traz no máximo 100 exames; se houver mais, a tela avisa para refinar os filtros.
- O agente e a tela descartam exames fora do período/modalidade, mesmo que o PACS ignore o filtro.
- A versão do agente aparece em Agentes; se estiver em vermelho, baixe o pacote novo em Downloads e rode
docker compose down && docker compose up -d --build.
Leitura automática dos dados do paciente (OCR) — v0.5.0
Muitos aparelhos (ex.: GE Signa) enviam a impressão DICOM só com a imagem: nome, Accession e ID aparecem escritos no canto, mas não vêm como dados. A partir da v0.5.0 o agente:
- Lê os cantos das primeiras imagens (Acc Num, nome do paciente, ID).
- Consulta o PACS por Accession → ID → Nome, e só aceita se o nome do PACS bater com o lido na imagem.
- Preenche o cabeçalho/rodapé com os dados completos do PACS. Sem resposta do PACS, usa o que foi lido.
Já vem ligado. Para desligar: OCR_ENABLED=false no .env. No log aparece OCR leu: {...}.
Para atualizar: baixe o novo pacote em Downloads e rode docker compose down && docker compose up -d --build.
Novidades da v0.9.0
- Nome das impressoras na busca: o agente pergunta o modelo por SNMP (comunidade
public) e pela página HTTPS, igual ao CUPS. - Bolinha verde/vermelha automática: a cada minuto o agente testa todas as impressoras e o PACS e mostra Online/Offline no painel.
- Atualizar pelo painel: em Agentes locais, botão Atualizar agente. Não precisa mais de terminal.
Última atualização pelo terminal (só uma vez, vindo da v0.8.0 ou anterior):
cd /opt/am2print-edge
cp .env /tmp/env.bak
curl -L -o /tmp/agent.zip https://cloudside-bridge.lovable.app/downloads/am2-edge-agent.zip
unzip -o /tmp/agent.zip -d .
cp /tmp/env.bak .env
docker compose down && docker compose up -d --build
Depois disso, as próximas versões são instaladas pelo botão no painel.
Novidades da v0.8.0
- Testar comunicação: em Configurações DICOM há o botão Testar C-ECHO para o PACS, e em Impressoras cada impressora tem o botão Testar. Bolinha verde = online (com tempo de resposta); vermelha = falha, com o motivo.
- Filas CUPS são testadas com
lpstat; impressoras de rede (RAW/IPP/LPD) testam a porta; impressoras DICOM usam C-ECHO. - Montar impressão agora tem filtro de Modalidade (Todas, CT, MR, CR, MG, US…).
Novidades da v0.7.0
- Compatibilidade com aparelhos GE (e outros) que enviam a ordem de impressão sem identificador da sessão. Antes, o aparelho mostrava "impressora não encontrada" e o trabalho não chegava.
- Para atualizar: baixe o novo pacote em Downloads, substitua os arquivos (mantenha o
.env) e rodedocker compose down && docker compose up -d --build.