Last updated: Aug 12, 2025, 01:18 PM UTC

Lessons Learnt: Docker Onboarding Issue

Problem

The onboarding flow wasn't showing in Docker even after completely resetting volumes and using incognito mode. Users were going straight to the main Sasha Studio interface without registration or organization setup.

Root Cause

The local server/database/auth.db file was being copied into the Docker image during build. This database already contained a user from local development, making the system think setup was complete.

Discovery Process

  1. Checked browser localStorage - cleared
  2. Checked Docker volumes - properly removed
  3. Used incognito mode - still no onboarding
  4. Initially thought test users needed to be created
  5. Discovered /api/auth/status returned needsSetup: false
  6. Found server/database/auth.db existed locally
  7. Realized it was being copied into Docker image with the server directory

Solution

Added database files to .dockerignore:

server/database/auth.db
server/database/*.db

Key Learnings

1. Check What's Being Copied to Docker

  • Even with data/ and *.db in .dockerignore, specific paths might still be copied
  • The server/ directory was being copied (needed for code)
  • But server/database/auth.db within it shouldn't be (it's user data)

2. Database Files Are User Data, Not Code

  • Database files should NEVER be in Docker images
  • They should be created fresh in volumes
  • Always add specific database paths to .dockerignore

3. Debug Authentication Issues Systematically

  • Check /api/auth/status endpoint first
  • Verify if users exist in the database
  • Check both volumes AND image contents
  • Don't assume - verify each layer

4. Single-User System Design

  • Sasha is designed as a single-user system
  • First user registers during initial setup
  • No pre-created test users needed
  • This is the correct flow for production

Prevention

  1. Always exclude database files in .dockerignore
  2. Test with completely fresh builds using --no-cache
  3. Verify no user data is baked into images
  4. Document the expected flow clearly

Testing Checklist

  • Run ./docker-clear.sh
  • Use incognito/private browser
  • Should see registration screen first
  • Then organization setup
  • Claude API key step
  • Finally, main interface

Commands for Fresh Testing

# Complete reset
./docker-clear.sh

# Full rebuild (no cache)
./docker-rebuild.sh --no-cache

# Then use incognito browser at http://localhost:3010

Impact

This fix ensures that Docker deployments always start with a clean slate, allowing proper onboarding and preventing confusion about missing setup steps.