Instalar o Arcanum

O Arcanum é distribuído como uma única imagem Docker mais um banco de dados Postgres. Tudo — a assinatura WSAA, as chaves privadas criptografadas, o tráfego SOAP até a ARCA — acontece dentro do seu contêiner. Nada se autentica através de um terceiro.

Requisitos

Docker

O caminho suportado. O docker compose incluído sobe o app e o Postgres juntos.

Dois segredos

Uma chave de API (protege a superfície REST) e uma chave mestra (criptografa as chaves privadas em repouso). Gere-as com openssl.

Um certificado da ARCA

Por CUIT, em homologação ou produção. O Arcanum gera o CSR; você o envia à ARCA e cola de volta o .crt.

Executar com Docker

Gere primeiro os dois segredos:

openssl rand -hex 24   # ARCANUM_API_KEY     (protects the API)
openssl rand -hex 32   # ARCANUM_MASTER_KEY  (encrypts the private keys — keep it safe)

docker compose

git clone https://github.com/diegoparras/arcanum.git && cd arcanum
cp .env.example .env
# edit .env: set ARCANUM_API_KEY and ARCANUM_MASTER_KEY
docker compose up -d

O arquivo compose inicia o Postgres e o app juntos, mapeia a porta 8094 e reinicia a menos que seja parado. Depois abra http://localhost:8094.

Prebuilt image

Use a imagem publicada no GHCR com o seu próprio Postgres:

docker run -d -p 8094:8094 \
  -e ARCANUM_ENV=homo \
  -e ARCANUM_API_KEY="$(openssl rand -hex 24)" \
  -e ARCANUM_MASTER_KEY="$(openssl rand -hex 32)" \
  -e DATABASE_URL="postgres://arcanum:arcanum@your-db:5432/arcanum" \
  ghcr.io/diegoparras/arcanum:latest

Proteja a chave mestra

ARCANUM_MASTER_KEY criptografa cada chave privada em repouso (AES-256-GCM) e existe apenas no ambiente, nunca no banco de dados. Se você a perder, os certificados armazenados não poderão ser descriptografados. Mantenha um backup seguro.

Primeira execução

1. Abra http://localhost:8094 e faça login (ARCANUM_ADMIN_USER / ARCANUM_ADMIN_PASS, ou a senha exibida uma única vez nos logs se você a deixou vazia).
2. Escolha o ambiente — homologação ou produção — no menu (ambiente da ARCA). Você pode trocá-lo depois, a quente, sem reimplantar.
3. Adicione um cliente (CUIT). O Arcanum gera o CSR; envie-o à ARCA e cole de volta o .crt. A chave privada é armazenada criptografada.
4. Siga o guia de ativação por serviço para autorizar cada web service, e então faça a sua primeira chamada a partir do painel ou via REST.

Variáveis de ambiente

Toda a configuração vive no .env (copie-o de .env.example).

Variable	Default	Descrição
PORT	8094	Porta em que o app escuta.
ARCANUM_ENV	homo	Ambiente padrão da ARCA: homo (testes) ou prod. Alternável na UI.
ARCANUM_API_KEY	(empty)	Chave para a API REST (X-API-Key). Vazio → gerada e exibida uma única vez no log.
ARCANUM_MASTER_KEY	(empty)	Chave hex de 32 bytes que criptografa as chaves privadas em repouso.
DATABASE_URL	(compose)	String de conexão do PostgreSQL. O arquivo compose a liga ao arcanum-db incluído.
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB	arcanum	Credenciais do Postgres incluído.
ARCANUM_ADMIN_USER	(empty)	Nome de usuário admin do painel web.
ARCANUM_ADMIN_PASS	(empty)	Senha do admin. Vazio → gerada e exibida uma única vez no log.
ARCANUM_OIDC_ISSUER	(empty)	URL do issuer do Lockatus — defina para federar o login (SSO opcional).
ARCANUM_OIDC_CLIENT_ID	(empty)	Slug do app no Lockatus (arcanum) quando federado.
ARCANUM_OIDC_CLIENT_SECRET	(empty)	Segredo do cliente OIDC, quando federado.

Single sign-on

Defina as variáveis ARCANUM_OIDC_* para federar o Arcanum com o Lockatus, o hub de identidade da suíte — um único login, dois fatores e papéis por app em toda a família. Deixe-as vazias para manter o login de admin autônomo.