Passa al contenuto principale

Variabili Ambiente

Guida completa alle variabili d'ambiente utilizzate in Emblema. Tutte le variabili sono definite nel file .env (copiare da .env.example).

🚀 Setup Iniziale​

# Copia il template
cp .env.example .env

# Genera segreti sicuri per produzione
openssl rand -hex 32  # Per JWT secrets, API keys, etc.

📋 Variabili per Categoria​

Core Application​

VariabileDescrizioneDefaultEsempio
COMPOSE_PROJECT_NAMENome progetto Docker Composeemblemaemblema
EMBLEMA_VERSIONVersione applicazione0.1.01.0.0
BASE_DOMAINDominio base per tutti i servizi-emblema.aeronautica.difesa.it
USE_SSLAbilita HTTPS (0/1)11
EDITOREditor preferito per CLIcursorvscode

Networking & DNS​

VariabileDescrizioneDefaultEsempio
DNS_SERVERServer DNS interno-192.168.1.69
TRAEFIK_HOSTNAMEHostname Traefik dashboard-traefik.emblema.ai

SSL/TLS Certificates​

VariabileDescrizioneDefaultEsempio
CERT_RESOLVERModalità certificati: vuoto (custom) o letsencrypt letsencrypt

Per certificati custom, posizionare i file in config/traefik/certs/.

Database - PostgreSQL​

VariabileDescrizioneDefaultEsempio
POSTGRES_USERUsername PostgreSQLemblemaemblema
POSTGRES_PASSWORDPassword PostgreSQL-Generare con openssl rand -hex 32

Database - Redis​

VariabileDescrizioneDefaultEsempio
REDIS_MASTER_HOSTNAMEHostname Redis master-redis.emblema.ai
REDIS_PORTPorta Redis63796379
REDIS_MASTER_PASSWORDPassword Redis-Generare con openssl rand -hex 32
REDIS_CACHE_URLURL cache Redis-redis://redis-master:6379/2

Database - MongoDB (per Novu)​

VariabileDescrizioneDefaultEsempio
MONGO_ROOT_USERNAMEUsername MongoDBemblemaemblema
MONGO_ROOT_PASSWORDPassword MongoDB-Generare con openssl rand -hex 32
MONGO_URLConnection string MongoDB-Auto-costruito dalle credenziali

Vector Database - Milvus​

VariabileDescrizioneDefaultEsempio
MILVUS_HOSTNAMEHostname Milvus-milvus.emblema.ai
MILVUS_PORTPorta Milvus1953019530
MILVUS_DB_NAMENome databaseemblemaemblema
MILVUS_USERUsername Milvusrootroot
MILVUS_PASSWORDPassword MilvusMilvusCambiare in produzione
MILVUS_ATTU_HOSTNAMEHostname UI Attu-attu.emblema.ai

Object Storage - MinIO​

VariabileDescrizioneDefaultEsempio
MINIO_HOSTNAMEHostname MinIO API-minio.emblema.ai
MINIO_ADMIN_HOSTNAMEHostname MinIO Console-minio-admin.emblema.ai
MINIO_ROOT_USERUsername adminemblemaemblema
MINIO_ROOT_PASSWORDPassword admin-Generare con openssl rand -hex 32
MINIO_BUCKETNome bucket principaleemblemaemblema
MINIO_REGIONRegione S3-compatibleeu-rome-1eu-rome-1
MINIO_ACCESS_KEY_IDAccess key applicazione-emblema_bucket_user
MINIO_SECRET_ACCESS_KEYSecret key applicazione-Generare con openssl rand -hex 32

Authentication - Keycloak​

VariabileDescrizioneDefaultEsempio
KEYCLOAK_HOSTNAMEHostname Keycloak-keycloak.emblema.ai
KEYCLOAK_ADMINUsername adminemblemaadmin
KEYCLOAK_ADMIN_PASSWORDPassword admin-Generare con openssl rand -hex 32
KEYCLOAK_REALM_URLURL realm Emblema-https://keycloak.emblema.ai/realms/emblema

API Gateway - Hasura​

VariabileDescrizioneDefaultEsempio
HASURA_HOSTNAMEHostname Hasura-hasura.emblema.ai
HASURA_ADMIN_SECRETAdmin secret-Generare con openssl rand -hex 32

Monitoring - Grafana & Loki​

VariabileDescrizioneDefaultEsempio
GRAFANA_HOSTNAMEHostname Grafana-grafana.emblema.ai
LOKI_HOSTNAMEHostname Loki-loki.emblema.ai
GRAFANA_ADMINUsername adminemblemaadmin
GRAFANA_ADMIN_PASSWORDPassword admin-Generare con openssl rand -hex 32

AI/LLM Gateway - LiteLLM​

VariabileDescrizioneDefaultEsempio
LITELLM_HOSTNAMEHostname LiteLLM-litellm.emblema.ai
LITELLM_MASTER_KEYMaster API key-Generare con openssl rand -hex 32
LITELLM_SALT_KEYSalt per encryption-Generare con openssl rand -hex 32
DEFAULT_CHAT_MODELModello chat defaultllama3.3-70b-instructgpt-4
DEFAULT_EMBEDDING_MODELModello embedding defaultbge-m3text-embedding-3-small

Background Tasks - Celery​

VariabileDescrizioneDefaultEsempio
CELERY_BROKER_URLURL broker Redis-redis://redis-master:6379/6
CELERY_RESULT_URLURL risultati-redis://redis-master:6379/6
CELERY_MAX_CONCURRENCYWorker concurrency14
CELERY_FLOWER_HOSTNAMEHostname Flower UI-celery-flower.emblema.ai
BACKGROUND_TASK_HOSTNAMEHostname API task-task.emblema.ai

Application Services​

VariabileDescrizioneDefaultEsempio
EMBLEMA_WEB_HOSTNAMEHostname app principale-www.emblema.ai
EMBLEMA_UI_HOSTNAMEHostname libreria UI-ui.emblema.ai
DOCS_HOSTNAMEHostname documentazione-doc.emblema.ai
DOCUMENT_RENDER_HOSTNAMEHostname render service-document-render.emblema.ai
DOCUMENT_RENDER_URLURL interno render service-http://document-render:8094

Authentication - Web App​

VariabileDescrizioneDefaultEsempio
EMBLEMA_WEB_AUTH_SECRETNextAuth secret-Generare con openssl rand -base64 32
EMBLEMA_WEB_AUTH_KEYCLOAK_IDClient ID Keycloakweb_clientweb_client
EMBLEMA_WEB_AUTH_KEYCLOAK_SECRETClient secret Keycloak-Da Keycloak console
EMBLEMA_WEB_AUTH_URLURL callback auth-https://www.emblema.ai/api/auth

Notifications - Novu​

VariabileDescrizioneDefaultEsempio
NOVU_API_HOSTNAMEHostname API Novu-novu-api.emblema.ai
NOVU_DASHBOARD_HOSTNAMEHostname dashboard-novu-dashboard.emblema.ai
NOVU_JWT_SECRETJWT secret-Generare con openssl rand -hex 32
NOVU_STORE_ENCRYPTION_KEYEncryption key (32 char!)-Generare esattamente 32 caratteri
NOVU_API_SECRET_KEYAPI key (da dashboard)-Ottenere da Novu dopo setup
NOVU_APPLICATION_IDENTIFIERApp ID (da dashboard)-Ottenere da Novu dopo setup

External Services​

VariabileDescrizioneDefaultEsempio
HUGGINGFACE_TOKENToken HuggingFace-hf_...
HF_HUB_OFFLINEModalità offline HF (0/1)01 per ambienti air-gap
OPENAI_API_KEYAPI key OpenAI-sk-...
OPENAI_BASE_URLBase URL (se custom)-https://litellm.emblema.ai

Monitoring & Telemetry​

VariabileDescrizioneDefaultEsempio
WEB_SENTRY_DSNDSN Sentry frontend-Da progetto Sentry
WEB_SENTRY_AUTH_TOKENAuth token Sentry-Da progetto Sentry
TURBO_TELEMETRY_DISABLEDDisabilita telemetria Turbo11

Cron Jobs​

VariabileDescrizioneDefaultEsempio
CRON_SECRETSecret per cron API-Generare con openssl rand -hex 32

File Upload​

VariabileDescrizioneDefaultEsempio
MAX_FILE_SIZEMax upload size (bytes)10737418242147483648 (2GB)

Configurazioni comuni:

  • 10MB: 10485760
  • 100MB: 104857600
  • 500MB: 524288000
  • 1GB: 1073741824 (default)
  • 2GB: 2147483648
  • 5GB: 5368709120

🔒 Best Practices Sicurezza​

1. Generazione Segreti​

# Per la maggior parte dei segreti
openssl rand -hex 32

# Per NextAuth secret
openssl rand -base64 32

# Per password complesse
openssl rand -base64 40 | tr -d "=+/" | cut -c1-32

2. Gestione .env​

# Non committare mai .env
echo ".env" >> .gitignore

# Usa .env.example come template
cp .env.example .env

# Cambia TUTTI i valori di default prima della produzione

3. Rotazione Segreti​

  • Ruotare periodicamente tutti i segreti
  • Usare un password manager per team
  • Considerare l'uso di HashiCorp Vault per produzione

🐳 Docker Compose Override​

Per override locali senza modificare .env:

# docker-compose.override.yml
version: '3.8'
services:
  www-emblema:
    environment:
      - DEBUG_MODE=1
      - LOG_LEVEL=debug

🌍 Configurazioni per Ambiente​

Sviluppo​

USE_SSL=0
CERT_RESOLVER=
HF_HUB_OFFLINE=0

Staging​

USE_SSL=1
CERT_RESOLVER=letsencrypt
HF_HUB_OFFLINE=0

Produzione​

USE_SSL=1
CERT_RESOLVER=letsencrypt
HF_HUB_OFFLINE=1  # Per ambienti air-gap

🚨 Troubleshooting​

Errori Comuni​

"Invalid JWT secret"

  • Verificare che EMBLEMA_WEB_AUTH_SECRET sia generato correttamente
  • Deve essere base64 encoded

"MinIO access denied"

  • Verificare che MINIO_ACCESS_KEY_ID e MINIO_SECRET_ACCESS_KEY corrispondano
  • Controllare che il bucket esista

"Novu encryption key invalid"

  • NOVU_STORE_ENCRYPTION_KEY DEVE essere esattamente 32 caratteri
  • Non usare caratteri speciali

Verifica Configurazione​

# Controlla sintassi .env
docker compose config

# Verifica variabili caricate
docker compose exec www-emblema env | grep EMBLEMA

# Test connessioni
docker compose exec www-emblema ping postgres
docker compose exec www-emblema ping redis-master

📚 Riferimenti​

Questa pagina ti è stata utile?