Installa Arcanum

Arcanum viene distribuito come una singola immagine Docker più un database Postgres. Tutto — la firma WSAA, le chiavi private cifrate, il traffico SOAP verso ARCA — avviene dentro il tuo container. Niente si autentica attraverso una terza parte.

Requisiti

Docker

Il percorso supportato. Il docker compose incluso avvia l’app e Postgres insieme.

Two secrets

Una API key (protegge la superficie REST) e una master key (cifra le chiavi private a riposo). Generale con openssl.

An ARCA certificate

Per CUIT, in omologazione o produzione. Arcanum genera il CSR; tu lo carichi su ARCA e incolli di nuovo il .crt.

Esegui con Docker

Genera prima i due segreti:

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

Il file compose avvia Postgres e l’app insieme, mappa la porta 8094 e si riavvia a meno che non venga arrestato. Poi apri http://localhost:8094.

Prebuilt image

Usa l’immagine pubblicata su GHCR con il tuo 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

Guard the master key

ARCANUM_MASTER_KEY cifra ogni chiave privata a riposo (AES-256-GCM) e risiede solo nell’ambiente, mai nel database. Se la perdi, i certificati memorizzati non potranno essere decifrati. Conserva un backup sicuro.

Primo avvio

1. Apri http://localhost:8094 e accedi (ARCANUM_ADMIN_USER / ARCANUM_ADMIN_PASS, oppure la password stampata una volta nei log se l’hai lasciata vuota).
2. Scegli l’ambiente — omologazione o produzione — dal menu (ambiente ARCA). Puoi cambiarlo in seguito, a caldo, senza ridistribuire.
3. Aggiungi un cliente (CUIT). Arcanum genera il CSR; caricalo su ARCA e incolla di nuovo il .crt. La chiave privata viene memorizzata cifrata.
4. Segui la guida di attivazione per servizio per autorizzare ogni web service, poi effettua la tua prima chiamata dal pannello o tramite REST.

Variabili d’ambiente

Tutta la configurazione risiede in .env (copialo da .env.example).

Variable	Default	Descrizione
PORT	8094	Porta su cui ascolta l’app.
ARCANUM_ENV	homo	Ambiente ARCA predefinito: homo (testing) o prod. Cambiabile nell’interfaccia.
ARCANUM_API_KEY	(empty)	Chiave per l’API REST (X-API-Key). Vuota → generata e stampata una volta nel log.
ARCANUM_MASTER_KEY	(empty)	Chiave esadecimale di 32 byte che cifra le chiavi private a riposo.
DATABASE_URL	(compose)	Stringa di connessione PostgreSQL. Il file compose la collega all’arcanum-db incluso.
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB	arcanum	Credenziali per il Postgres incluso.
ARCANUM_ADMIN_USER	(empty)	Nome utente admin per il pannello web.
ARCANUM_ADMIN_PASS	(empty)	Password admin. Vuota → generata e stampata una volta nel log.
ARCANUM_OIDC_ISSUER	(empty)	URL issuer di Lockatus — impostalo per federare il login (SSO opzionale).
ARCANUM_OIDC_CLIENT_ID	(empty)	Slug dell’app in Lockatus (arcanum) quando federata.
ARCANUM_OIDC_CLIENT_SECRET	(empty)	Client secret OIDC, quando federata.

Single sign-on

Imposta le variabili ARCANUM_OIDC_* per federare Arcanum con Lockatus, l’hub di identità della suite — un solo login, autenticazione a due fattori e ruoli per app in tutta la famiglia. Lasciale vuote per mantenere il login admin standalone.