AM2 Print Cloud

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çãoDescrição
DICOM Print SCPRecebe impressões das modalidades na porta TCP 11112 (configurável).
Montagem de páginaConverte o filme DICOM em PDF A3/A4.
RoteamentoAplica as regras da nuvem: por tipo de exame, aparelho, dia, horário, impressão automática ou manual, contingência.
Impressão em papelEnvia para impressoras de rede por RAW/JetDirect (9100), IPP (631), LPD (515) ou fila CUPS.
Descoberta de impressorasVarre a rede local quando você clica em “Buscar impressoras” no sistema.
PACS (opcional)Consulta C-FIND para completar dados do paciente.
SincronizaçãoEnvia status e histórico de trabalhos para a nuvem a cada 30 segundos.

Situação das funções

FunçãoSituação
Receber DICOM Print e gerar PDFDisponível
Roteamento por regras e contingênciaDisponível
Impressão RAW / IPP / LPD / CUPSDisponí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.


2. Requisitos

Novidades da v0.15.1

Novidades da v0.15.0


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'

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

  1. No AM2 Print Cloud, abra Agentes locais → Novo agente e copie o token.
  2. 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
  1. 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

  1. Ative a virtualização na BIOS (Intel VT-x / AMD-V).
  2. PowerShell como Administrador: wsl --install -d Ubuntu
  3. Instale o Docker Desktop com backend WSL 2.
  4. Descompacte o pacote em C:\am2print-edge\, copie .env.example para .env e edite.
  5. Libere a porta:
New-NetFirewallRule -DisplayName "AM2 DICOM Print SCP" -Direction Inbound -Protocol TCP -LocalPort 11112 -Action Allow
  1. cd C:\am2print-edge e docker compose up -d --build

No Windows, a busca de impressoras funciona melhor configurando SCAN_SUBNET no .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_MAP ou, 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):

CampoValor
AE TitleAM2_PRINT
IPIP do servidor onde o agente roda
Porta11112
Filme14x17 ou A3, conforme o fluxo

Use o botão Verify / Echo do aparelho para testar a conexão.


7. Impressoras e regras (no sistema)

  1. Impressoras → Buscar agora: o agente varre a rede e lista o que encontrar. Clique em Adicionar.
  2. 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).
  3. Use Simular para conferir para onde um exame iria.
  4. 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.

  1. Veja as filas já instaladas no servidor:
lpstat -v
  1. 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
  1. Teste direto no Linux (deve sair uma folha):
echo "Teste AM2" > /tmp/teste.txt && lp -d NOME_DA_FILA /tmp/teste.txt
  1. 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

SintomaO que verificar
Agente “offline” no sistemaToken no .env, saída HTTPS liberada, docker compose logs.
Modalidade não conectaFirewall na porta 11112, AE Title igual dos dois lados.
Impressão não saiIP/porta da impressora; teste nc -vz IP 9100 no servidor.
Status "Impresso" mas nada saiA impressora precisa de driver: use Fila CUPS local (seção 7).
Porta ocupadaVeja em Configurações DICOM as portas livres sugeridas pelo agente.
Busca não acha impressorasConfigure 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).

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)

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:

  1. Lê os cantos das primeiras imagens (Acc Num, nome do paciente, ID).
  2. Consulta o PACS por Accession → ID → Nome, e só aceita se o nome do PACS bater com o lido na imagem.
  3. 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

Ú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

Novidades da v0.7.0