Delonet Dotenv

delonet-dotenv

Choose-your-own-adventure for filling env vars on Jarad's big-chungus server. The body is a routing surface — every section ends with "for X, read references/Y.md". Stop reading the moment your decision is made.

Operating principles

• Two-file split. Non-secrets go in .env. Secrets go in .env.op as op://DeLoSecrets/<Item>/<field> references; resolve at run time with op run --env-file .env.op -- docker compose up. Never paste raw secrets into .env.
• delo.sh by default. Public hostname = <service>.delo.sh. API subdomain = api.<service>.delo.sh. Cloudflare Tunnel routes both into Traefik — no port-forward, no public IP, no certs to manage.
• Cloudflare wins ties. Resend exists as SMTP fallback, but for DNS, Turnstile, R2, email routing, etc., Cloudflare beats every alternative.
• Container-to-container by service name (e.g. postgres, redis). LAN IPs in env files are stale and must be replaced (see gotchas.md).
• Port assumption is bug. Big-chungus is busy. If the stack must bind a host port, pick something in 13000-25000. Better: skip the host bind and let Traefik route via the proxy network.

Routing table

The 60-second decision tree

Encounter an env var. Ask in order:

1. Is it a SECRET? (key, token, password, api_key, encryption_key, webhook_secret)
   YES → put `op://DeLoSecrets/<Item>/<field>` in .env.op, leave .env blank.
         → If item doesn't exist in vault: create it with `op item create`.
         → For routine creds, reuse op://DeLoSecrets/PostgresLocal/{username,password}.
         → See secrets-vault.md.
   NO  → put the literal value in .env.

2. Is it a URL/hostname for THIS stack?
   Public-facing? → https://<service>.delo.sh   (api → https://api.<service>.delo.sh)
   Container-internal? → service name (postgres, redis, calcom, etc.)
   Same host on the LAN? → host.docker.internal (NOT 192.168.1.12, NOT localhost)
   See traefik-routing.md.

3. Is it a PORT?
   Container internal port? → leave at framework default.
   Host bind? → don't, unless absolutely required. If required: 13000-25000, never 3000/5432/6379/80/443/8080.

4. Is it a DATABASE_URL?
   Stack ships its own postgres? → postgresql://<user>:<pass>@postgres:5432/<db>  (stack-internal)
   Need to share an external postgres? → postgresql://<user>:<pass>@host.docker.internal:5432/<db>
   See decisions.md > database.

5. Is it an EMAIL FROM address?
   Service-themed: notifications@<service>.delo.sh, no-reply@<service>.delo.sh
   Personal: jaradd@gmail.com (only when the service legitimately speaks for Jarad).

6. Is it an S3 bucket / object storage?
   → MinIO at https://drive.delo.sh, bucket = <service>-<purpose>, region = us-east-1.
   → Credentials: op://DeLoSecrets/DeLoDrive (MinIO)/{access_key,secret_key} or $MINIO_ACCESS_KEY.

7. Is it telemetry / analytics / Sentry / Posthog?
   → Leave blank unless the user explicitly asks for it. Self-hosted = no third-party telemetry.

8. Is it OAuth (Google / Microsoft / etc.)?
   → Leave blank for first boot. Backfill after the stack is verified up.
   → When ready: op://DeLoSecrets/Google/* etc.

Constants you'll need every time

Full table with provenance and edge cases: constants.md.

Cross-cutting rules

• Secrets must NEVER live in .env. If a key looks secret-shaped (*_KEY, *_SECRET, *_TOKEN, *_PASSWORD, *_DSN, DATABASE_URL containing a password), it goes in .env.op only.
• Generate on demand. NEXTAUTH_SECRET, *_ENCRYPTION_KEY, CRON_API_KEY, etc. → openssl rand -base64 32 (or 24 for AES256). Store generated values in op as a new item, then reference.
• .env.op is committable. It contains references, not secrets. .env is .gitignored.
• Quote ALLOWED_HOSTNAMES correctly. Cal-style: '"calendar.delo.sh","localhost:3000"' (outer single, inner double, comma-separated).
• Traefik label presence ⇒ proxy network membership. Always pair them. A container with traefik labels but not on the proxy network is invisible to Traefik.
• Don't invent items in op. If op item get "<Name>" --vault DeLoSecrets fails, create the item with op item create — don't guess at field names.

Workflow

1. Read the stack's .env.example (or upstream env documentation). Identify every var.
2. For each var, run the 60-second decision tree above. When uncertain, jump to the matching reference.
3. Write non-secrets into .env. Write op:// references into .env.op.
4. If the stack needs to be reachable at <service>.delo.sh, drop a docker-compose.override.yml per traefik-routing.md.
5. Verify: op run --env-file .env.op -- env | grep -E '^(DATABASE|NEXTAUTH|CALENDSO|...)' — all secrets resolve to non-empty values.
6. Bring up: op run --env-file .env.op -- docker compose up -d.
7. Curl the public URL: curl -I https://<service>.delo.sh. Expect 200 or a framework-appropriate redirect.

Out of scope

• Vercel, Render, Fly, AWS, GCP env management. Those are platform-managed; this skill is for big-chungus self-hosting only. Use the platform's secret manager.
• GitHub Actions / CI secrets. Use gh secret set and the repo's secrets UI; don't commit .env.op references for CI use cases.
• Kubernetes manifests / Helm values. Use SealedSecrets, External Secrets Operator, or the cluster's secret store.
• Non-DeLoNET environments (work laptops, customer machines, ephemeral dev VMs). The constants in this skill assume big-chungus.burro-salmon.ts.net.
• Generating the docker-compose itself from scratch. That's the stacks-deploy skill's job. This skill assumes a compose file already exists.
• Shell-level secret loading via secrets.zsh. Treated as legacy fallback; this skill migrates secrets toward op.