Atrea User API

Tmavý režim

Konfigurace serveru ​

Atrea User API používá balíček config s YAML soubory v adresáři config/. Konfigurace se přepíná pomocí proměnné NODE_ENV.

Soubory konfigurace ​

SouborNODE_ENVPopis
config/default.yaml(výchozí, dev)Lokální vývoj s Dockerem
config/production.yamlproductionProdukční přepisy
config/test.yamltestTestovací prostředí

Produkční soubor přepisuje pouze změněné hodnoty z default.yaml.

Kompletní schéma konfigurace ​

Síť & Server ​

yaml
hostname: "0.0.0.0"          # IP pro naslouchání (0.0.0.0 = všechna rozhraní)
port: 3001                     # Port HTTP serveru

Databáze (PostgreSQL) ​

yaml
database:
  host: "db"                   # Hostname PostgreSQL
  database: "atrea-user-db"    # Název databáze
  user: "app"                  # Uživatelské jméno
  password: "app"              # Heslo (změňte v produkci!)
  port: 5432                   # Port PostgreSQL
  logging: true                # SQL query logování (vypnout v produkci)
  synchronize: false           # TypeORM auto-migrate (NIKDY true v produkci!)

DANGER

synchronize: true v produkci může způsobit ztrátu dat. Vždy používejte false a migrujte ručně přes SQL soubory.

JWT Provideři ​

yaml
token:
  keyRefreshIntervalMinutes: 60  # Interval refreshe JWKS klíčů

  jwt:
    - provider: "zitadel"
      baseUrl: "http://zitadel:8080"    # URL JWKS endpointu (interní)
      jwk: "/oauth/v2/keys"             # Cesta k JWKS
      issuer: "http://localhost:8080"   # Očekávaný issuer v JWT
      hostOverride: "localhost"         # Přepíše Host header při fetchování klíčů

    - provider: "amotion"
      baseUrl: "https://auth-dev.am-space.cz"
      jwk: "/.well-known/jwks.json"
      issuer: "https://auth-dev.am-space.cz"

    - provider: "microsoft"
      baseUrl: "https://login.microsoftonline.com"
      jwk: "/common/discovery/v2.0/keys"
      issuer: "https://login.microsoftonline.com/{tenantId}/v2.0"

    - provider: "google"
      baseUrl: "https://accounts.google.com"
      jwk: "/oauth/v2/certs"
      issuer: "https://accounts.google.com"

Zitadel integrace ​

yaml
zitadel:
  apiUrl: "http://zitadel:8080"         # Interní API URL (Docker service name)
  publicUrl: "http://localhost:8080"    # Veřejná URL (pro OIDC redirecty)
  serviceAccountToken: ""               # Service account token pro Zitadel API
  webhookSecret: "change-me-in-production"  # Secret pro webhook validaci

  orgToApp:                             # Mapování orgId → appCode
    "org_abc123": "crm"
    "org_def456": "vallox-panel"

Email (SMTP) ​

yaml
email:
  from: "Atrea <noreply@atrea.eu>"      # Odesílatel (přepíše brand.emailFrom pro systémové emaily)
  assetsBaseUrl: "http://localhost:3001" # Base URL pro obrázky v emailech

  # DKIM podepisování (volitelné)
  dkim:
    domainName: "atrea.eu"
    keySelector: "mail"
    privateKeyPath: "/app/config/dkim/atrea.eu.pem"

Web Push (VAPID) ​

yaml
# Volitelné — bez konfigurace push notifikace nefungují
push:
  vapidPublicKey: "BM8U3B..."
  vapidPrivateKey: "x7Vc3A2..."
  vapidSubject: "mailto:admin@atrea.eu"

Interní API klíč ​

yaml
internalApiKey: "change-me-in-production"  # x-internal-api-key header

Produkční konfigurace (příklad) ​

yaml
# config/production.yaml — přepisuje pouze rozdíly od default.yaml

zitadel:
  apiUrl: "https://admin.kagb.cloud"
  publicUrl: "https://admin.kagb.cloud"
  serviceAccountToken: "<token>"
  webhookSecret: "<silny-secret>"

database:
  host: "postgres"
  password: "<silne-heslo>"
  logging: false

email:
  from: "Atrea <noreply@atrea.eu>"
  assetsBaseUrl: "https://api.atrea.eu"
  dkim:
    domainName: "atrea.eu"
    keySelector: "mail"
    privateKeyPath: "/app/config/dkim/atrea.eu.pem"

internalApiKey: "<silny-api-klic>"

push:
  vapidPublicKey: "<vapid-public-key>"
  vapidPrivateKey: "<vapid-private-key>"
  vapidSubject: "mailto:tech@atrea.eu"

token:
  jwt:
    - provider: "zitadel"
      baseUrl: "https://admin.kagb.cloud"
      jwk: "/oauth/v2/keys"
      issuer: "https://admin.kagb.cloud"

Přístup ke konfiguraci v kódu ​

Konfigurace je typována v src/utils/serverConfig.ts:

typescript
import config from 'config';

// Přímý přístup
const port = config.get<number>('port');
const dbHost = config.get<string>('database.host');
const jwtProviders = config.get<JwtProviderConfig[]>('token.jwt');

// Bezpečný přístup (vrátí undefined pokud neexistuje)
const dkim = config.has('email.dkim') ? config.get('email.dkim') : undefined;

Proměnné prostředí ​

Balíček config podporuje přepsání libovolné hodnoty z proměnné prostředí pomocí NODE_CONFIG:

bash
NODE_CONFIG='{"database":{"password":"tajne"}}' node dist/index.js

Nebo pomocí NODE_APP_INSTANCE pro instance-specifickou konfiguraci:

bash
NODE_APP_INSTANCE=2 node dist/index.js  # Načte config/default-2.yaml pokud existuje

DKIM klíče ​

DKIM klíče jsou uloženy v config/dkim/. Soubory jsou vynechány z git (.gitignore) z bezpečnostních důvodů.

bash
config/dkim/
├── atrea.eu.pem       # RSA private key pro DKIM podepisování
└── atrea.eu.pub       # Veřejný klíč (pro DNS TXT záznam)

Viz Nasazení → DKIM pro instrukce.

Logování ​

typescript
// src/utils/logger.ts
// Winston logger s JSON výstupem
logger.info('Zpráva');
logger.error('Chyba', { detail: 'popis' });
logger.warn('Varování');

Log level závisí na NODE_ENV:

  • development: debug
  • production: info
  • test: silent

Atrea User API — interní dokumentace

© 2024 Atrea