oikos/docs/archive/installer-recon.md

Installer Reconnaissance

1. Environment Variables (from .env.example)

Auto-generatable (openssl rand -hex 32)

Variable	Purpose
SESSION_SECRET	Express session signing key
DB_ENCRYPTION_KEY	SQLCipher encryption key

Has sensible defaults

Variable	Default	Notes
PORT	3000
NODE_ENV	production	Hardcoded in docker-compose.yml
DB_PATH	/data/oikos.db	Hardcoded in docker-compose.yml
SESSION_SECURE	true	Set to false in docker-compose when no reverse proxy
OPENWEATHER_CITY	Berlin
OPENWEATHER_UNITS	metric
OPENWEATHER_LANG	de
APPLE_CALDAV_URL	https://caldav.icloud.com
SYNC_INTERVAL_MINUTES	15
RATE_LIMIT_WINDOW_MS	60000
RATE_LIMIT_MAX_ATTEMPTS	5
RATE_LIMIT_BLOCK_DURATION_MS	900000

User-provided (optional integrations)

Variable	Integration
OPENWEATHER_API_KEY	Weather widget
GOOGLE_CLIENT_ID	Google Calendar sync
GOOGLE_CLIENT_SECRET	Google Calendar sync
GOOGLE_REDIRECT_URI	Google Calendar sync
APPLE_USERNAME	Apple CalDAV sync
APPLE_APP_SPECIFIC_PASSWORD	Apple CalDAV sync

Docker-compose overrides

These are set in docker-compose.yml environment: section and override .env:

• NODE_ENV=production
• DB_PATH=/data/oikos.db
• SESSION_SECURE=false (default, commented advice to remove for reverse proxy)

2. Docker Setup

• Service name: oikos
• Image: ghcr.io/ulsklyc/oikos:latest (or local build)
• Port: 0.0.0.0:3000:3000
• Volume: oikos_data:/data (named volume)
• Env file: .env
• Restart policy: unless-stopped
• Health check: GET http://localhost:3000/health — interval 30s, timeout 10s, 3 retries, 10s start period

3. Health Check Endpoint

GET /health → { status: "ok", timestamp: "2025-..." }

Returns HTTP 200 when the app is running and the DB is initialized. Excluded from rate limiting.

4. Admin Creation — Current Mechanisms

a) setup.js (CLI)

• Interactive Node.js script, run via npm run setup (node --import dotenv/config setup.js)
• Directly accesses the SQLite DB via server/db.js
• Prompts: username, display_name, password (with confirmation)
• Checks if admin already exists, asks to confirm if so
• Limitation: Requires direct filesystem access to the DB — does NOT work when the app runs in Docker (DB is inside container volume at /data/oikos.db)

b) POST /api/v1/auth/users (API)

• Creates a new user
• Requires: Active admin session + CSRF token
• Fields: { username, display_name, password, avatar_color?, role? }
• Limitation: Unusable for first-time setup (chicken-and-egg: need admin to create admin)

c) scripts/seed-demo.js

• Demo data seeding script — creates users directly via DB
• Not a setup mechanism, but shows the user schema

5. Gap Analysis — What's Missing

A bootstrap API endpoint is needed. Neither existing mechanism allows creating the first admin user when the app runs in Docker without shell access.

Proposed solution: Add POST /api/v1/auth/setup endpoint:

• Only succeeds when the users table has zero rows
• No authentication required (it IS the authentication bootstrap)
• Accepts: { username, display_name, password }
• Returns: { user: { id, username, display_name, role: 'admin' } }
• After the first user exists, returns 403 ("Setup already completed")
• Rate-limited to prevent abuse during the brief window

6. Existing Files to Be Aware Of

• .dockerignore already excludes docs/, scripts/, test-*.js, .env*
• tools/ is NOT in .dockerignore yet — needs to be added
• docs/installation.md exists — should be updated to reference the new installers
• docs/install.html exists — appears to be a landing page, not an installer