Skip to main content

​
cubby dev

Start a local development environment with Docker. This provides a production-like environment on your machine with hot reload and a local Postgres database.

​
Usage

cubby dev [flags]

​
Flags

FlagDescriptionDefault
--resetReset database (deletes all local data)false
--prod-modeSimulate production environment (NODE_ENV=production)false

​
Examples

# Start development
cubby dev

# Start fresh with empty database
cubby dev --reset

# Test production build locally
cubby dev --prod-mode

​
What Happens

  1. Validation - Checks for cubby.yaml and Docker
  2. Port detection - Finds available ports (default: 3000 for app, 5432 for database)
  3. Secret injection - Loads local secrets (set via cubby secrets set)
  4. Compose generation - Creates docker-compose.dev.yml
  5. Container build - Builds your app container
  6. Database start - Starts Postgres with health check
  7. Schema sync - Runs prisma db push automatically
  8. Log streaming - Shows combined app and database logs

​
Output

Starting development environment...
Finding available ports...
Injecting 2 local secret(s)
Generating Docker Compose configuration...
Building containers (this may take a moment on first run)...
Starting containers...
Waiting for database to be ready...
Database schema synchronized
Development environment ready!

  App:      http://localhost:3000
  Database: postgresql://cubby:cubby@localhost:5432/cubby

Streaming logs (Ctrl+C to stop)...

​
How It Differs from npm run dev

Featurecubby devnpm run dev
DatabasePostgres in DockerManual setup required
SecretsInjected from cubby secretsManual .env file
EnvironmentProduction-like containerNode.js directly
Schema syncAutomaticManual prisma db push
CleanupAutomatic on Ctrl+CNone

​
Database Persistence

Data persists between cubby dev sessions in a Docker volume named cubby-db-<appname>. To start fresh: 
cubby dev --reset
This deletes the volume and creates a new database.

​
Local Secrets

Secrets set with cubby secrets set are automatically injected: 
# Set a secret for local development
cubby secrets set OPENAI_API_KEY

# Start dev (secret is injected)
cubby dev
The secret is available as process.env.OPENAI_API_KEY in your app.

​
Port Conflicts

If port 3000 or 5432 is in use, cubby dev automatically finds alternatives: 
Default ports in use. Using: app=3001, database=5433

​
Stopping Development

Press Ctrl+C to stop. This:
  • Kills log streaming
  • Stops containers
  • Cleans up docker-compose.dev.yml
Your database data is preserved for next time.

​
Requirements

  • Docker must be running
  • Project must have cubby.yaml (run cubby init first)

​
Troubleshooting

​
”Docker is not running”

Start Docker Desktop and try again.

​
”Not a Cubby app directory”

Run cubby init first, or cd to a directory with cubby.yaml.

​
”Database failed to become healthy”

The Postgres container may be slow to start. Try: 
cubby dev --reset

​
Schema Sync Warning

If prisma db push fails, you’ll see a warning but dev continues: 
Schema sync warning: [error message]
Continuing without schema sync...
Run npx prisma db push manually to see the full error.