🧠 Deep Solutions

Architectural fixes and established solutions for the homelab deployment.

🔓 Frictionless Authentication

• Captcha: Disabled via config.json (captcha: { enabled: false }).
• Email Bypass: Bypassing email verification requires patching AuthController.ts to respect strict_email_verification_required: false (by default it forces confirmation for all non-temp accounts).
• Session Cache: Puter aggressively caches user state in Valkey (sessions:v2:uuid:* and users:id:*). Direct DB modifications require targeted cache eviction via valkey-cli -c DEL <key> (Cluster Mode).

🌍 Networking Quirks

• Subdomain Offset: Express.js subdomain offset defaults to 2. For os.loca.zone (3 parts), this breaks { subdomain: '' } routing. Solved dynamically in server.ts: app.set('subdomain offset', domain.split('.').length).
• S3 Path Style: AWS S3 SDK uses virtual-hosted style by default, causing ENOTFOUND puter-thumbnails.s3. Resolved by enforcing "forcePathStyle": true in the thumbnailStore config.

🐳 Docker Build Optimization

• Cache Busting: Modifying backend TypeScript files doesn’t reliably bust the Docker COPY . . cache layer when using touch. Content must be modified to trigger a proper recompilation.
• Worker Preamble: The worker build must be sequenced after the puter-js build completes to avoid race conditions (ENOENT puter.js).