YasharBasiralolomi

networks & isolation

• homelab — the shared edge network. Exactly one container per stack joins it (web or stack-nginx).
• security — Authelia, Loki/Alloy, the Docker socket proxy, the edge and Grafana.
• Per-stack private networks; data networks are internal: true (no route in or out).
• Separate egress networks for the only containers that must call the internet.
• No host ports for any product stack — the edge reaches containers by name.

edge nginx

• Custom image, one conf.d vhost per service, shared includes for CDN guard and forward-auth.
• Wildcard Let's Encrypt cert (ECDSA P-256) via acme.sh DNS-01 — renewal never depends on ports 80/443 being open.
• resolver 127.0.0.11 + variable proxy_pass so the edge still boots when one upstream is down.
• Explicit default_server: unknown hosts and bare-IP hits get a 404/444, never an app.
• stub_status on a dedicated listener only reachable from the Docker network.

logs & metrics pipeline

nginx ─ access_json.log ─▶ alloy ─▶ loki ─▶ grafana
   fields: status, host, upstream time, TLS cipher,
           via_cdn, edge_addr   # labels: status, server_name only
nginx-exporter ┐
cadvisor       ├─▶ prometheus ─▶ grafana + alert rules
nabz /metrics  │   # app scrapes use bearer tokens
hamrahpay      ┘

• Only low-cardinality fields become Loki labels; IPs and URIs stay in the log line.
• cAdvisor keeps only the Compose labels dashboards filter on.

delivery & supply chain

• Self-hosted GitLab CE + Runner; every product lives in its own repo.
• Nexus as artifact and Docker registry.
• Security-relevant images pinned by tag and digest; app images versioned (:1.0.0).
• WUD tracks image updates; a separate CVE scanner host reads container metadata through a read-only Docker socket proxy (POST=0).
• All builds and tests run in containers — no language toolchains on the host.

read path & caching

• The API reads cache only — stale-while-revalidate; no request ever waits on a provider.
• Redis TTL bounds memory; staleness is a separate policy (*_MAX_STALE_AGE) computed at read time: fresh · stale · unavailable.
• Redis loss falls back to Postgres transparently.
• History stored as 5-minute candles; sparse ranges back-filled once per asset/timeframe per 5 min under a Redis lock.

data model

• market_assets synced at boot from a single typed registry — adding an asset is one registry edit.
• market_quotes_latest, price_history (PK symbol, tf, ts; 5m…1d).
• api_keys store only an HMAC-SHA256 hash; api_audit_logs never store credentials.
• SQL migrations run at startup under a Postgres advisory lock.

API contract

• Base /api/v1, Bearer auth (JWT or nbz_… key), OpenAPI at /api/docs.
• Envelope {success, data, meta}; errors carry a stable code and a requestId.
• Search is Persian/English/symbol, tolerant of ZWNJ and Arabic/Persian letter variants.
• New provider = one adapter implementing MarketDataProvider + one factory line.

operations

• /health, /ready (PG + Redis), /metrics — internal only, 404 at the edge.
• Metrics for request latency, cache hit/miss, provider errors and latency, stale counts, rejected quotes, auth failures; Prometheus alert rules on top.
• Mock provider exists for development and is refused at boot when APP_ENV=production.

categorisation & insight

• Merchant normalisation (POS STARBUCKS #123 → Starbucks), rule-based categories and tags.
• User corrections become rules applied to the merchant's past and future transactions.
• Recurring payments/income, internal-transfer matching, unusual-spend alerts — every insight carries its evidence.

data model decisions

• Amounts signed numeric(18,2) plus explicit type — sign alone can't express transfers.
• Dates Gregorian date, timestamps UTC timestamptz; display in Asia/Tehran.
• One reporting currency per user; accounts carry their own currency for later multi-currency.
• Opaque server-side sessions, no JWT — revocable, nothing to leak to JS.

Ask Spendly (local AI)

• llama.cpp serving a 3B instruct model on spendly-llm — an internal: true network with no gateway.
• The model gets the question text only; answers are computed from the user's own data by the backend. Questions are not logged.
• Model downloaded once by a setup job and verified by SHA-256 before use.

reports & exports

• Monthly/yearly reports in Jalali or Gregorian, rendered to PDF on the server with correct Persian shaping.
• PDF renderer refuses every external URL — a merchant name can't make the server fetch anything (SSRF).
• CSV cells starting with = + - @ are escaped (formula injection).

pricing engine

final_usd = base + fixed + base × percent / 100
toman     = ceil(final_usd × rate / 10 000) × 10 000
# Decimal arithmetic only — no floats

• Precedence: plan override › service default › system default; a manual Toman price beats the formula.
• Every order snapshots base, markups, rate and total — later price changes never rewrite history.

sensitive-data envelope

seal(ring, plaintext, aad) →
  { keyId, nonce: 96-bit random, ciphertext‖tag }
# AES-256-GCM · AAD binds ciphertext to its record

• Key ring from a Docker secret: {"current":"k1","keys":{…}}. Rotation = add k2, switch current, restart.
• Old rows still open with their stored key ID; old keys retire once those rows are purged (7 days after delivery).

container profile

• Compose anchor x-hardening on every service: no-new-privileges, cap_drop: ALL, log rotation, graceful stop.
• Postgres gets back only the five capabilities it needs to start.
• Memory, CPU and PID limits on every container; app and worker run as uid 1000 with read-only rootfs + tmpfs.
• Migrations run at app start; worker starts only after the app is healthy.

backup & recovery

• Backup container checks hourly; runs when the newest dump is older than 7 days: pg_dump -Fc + receipts tarball.
• Directory 700, files 600, newest 6 kept; each run recorded in backup_runs and shown on the admin health page.
• Restore test script restores the newest dump into a throwaway Postgres and counts rows.

real client IP — done right

• set_real_ip_from only for CDN ranges, header ar-real-ip — nobody else can influence $remote_addr.
• A geo map on $realip_remote_addr (the TCP peer, before rewriting) classifies every request as cdn · internal · direct.
• Upstreams get X-Forwarded-For $remote_addr — overwritten, never appended.

firewall rules

# LAN keeps working
-A DOCKER-USER -s <lan> -p tcp -m multiport
   --dports 80,443 -j RETURN
# everything not from the CDN set is dropped
-A DOCKER-USER -p tcp -m multiport --dports 80,443
   -m conntrack --ctstate NEW
   -m set ! --match-set cdn4 src -j DROP

• DOCKER-USER is the only correct hook — published container ports are DNAT'd to FORWARD and never touch INPUT.

daily CDN range refresh

• systemd timer fetches the official list; one fetch feeds realip, the geo map and the ipset.
• Refuses: non-200, empty, HTML/JSON bodies, any non-CIDR line, private ranges, 0.0.0.0/0, fewer than 8 entries, or a count change outside 60–500 %.
• Timestamped backup → atomic write → nginx -t → auto-rollback on failure → reload → ipset swap (the set is never empty).

Termix container

• Image pinned by tag + digest; no host port; cap_drop: ALL with only the five capabilities its privilege drop needs.
• Secrets supplied from a 600-mode env file so the app never writes keys next to its own ciphertext.
• Telemetry, registration, password reset, RDP/VNC and proxy-auth all disabled and locked by env.
• WebSocket paths protected by forward-auth too — no bypass rules.