Skip to content

Dev Mode

Jump to bottom
Eric Mann edited this page Jan 7, 2026 · 4 revisions

Development Mode

Development Mode provides a live file synchronization workflow for rapid iteration during development. It watches for file changes on your local machine and automatically syncs them to running pods in your Kubernetes cluster, eliminating the need for full container rebuilds on every change.

How It Works

flowchart LR
    subgraph local["Local Machine"]
        editor["Code Editor"]
        watcher["File Watcher"]
    end

    subgraph cluster["Kubernetes Cluster"]
        pod["Running Pod"]
        app["Application"]
    end

    editor -->|"Save file"| watcher
    watcher -->|"Detect change"| sync["Sync Engine"]
    sync -->|"hostpath/kubectl/configmap"| pod
    pod --> app
    app -->|"Hot reload"| browser["Browser"]
Loading

The Development Loop:

  1. You edit code in your favorite editor
  2. Dev mode detects the file change instantly
  3. Changes sync to running pods (no rebuild needed)
  4. Application picks up changes via hot reload
  5. You see results in your browser immediately

Overview

The displace project dev command starts a development session that:

  • Watches local files for changes in real-time
  • Syncs changes to running pods automatically
  • Debounces rapid changes to prevent sync storms
  • Excludes common non-essential files (node_modules, .git, etc.)
  • Works with local k3d clusters or remote cloud clusters

This dramatically speeds up the development cycle by eliminating the build-push-deploy loop for code changes.

Quick Start

# Start dev mode with local k3d cluster (fastest)
displace project dev --local

Expected output:

🔧 Starting development mode for: my-wordpress-site
📋 Template: wordpress

🎯 Target: displace-local (local) / namespace: my-wordpress-site

📁 Watch paths: [.]
🔄 Sync method: hostpath

🚀 Starting file watcher...

✨ Dev mode active! Watching 127 files
   Press Ctrl+C to stop
💡 Tips:
   - View pods: kubectl get pods -n my-wordpress-site
   - View logs: kubectl logs -f -n my-wordpress-site -l app=my-wordpress-site
   - Changes are synced automatically when you save files

Other common commands:

# Start dev mode with a specific cluster
displace project dev --cluster my-cluster

# Watch specific directories
displace project dev --local --watch ./src --watch ./config

# Use kubectl sync for cloud clusters
displace project dev --cluster my-eks-cluster --sync-method kubectl

Sync Methods

Development mode supports three synchronization methods, each optimized for different scenarios:

flowchart TB
    subgraph methods["Sync Method Comparison"]
        direction LR
        subgraph hostpath["hostpath"]
            hp1["Fastest"]
            hp2["Local k3d only"]
            hp3["Volume mount"]
        end
        subgraph kubectl["kubectl"]
            kc1["Universal"]
            kc2["Any cluster"]
            kc3["kubectl cp"]
        end
        subgraph configmap["configmap"]
            cm1["Config files"]
            cm2["K8s native"]
            cm3["ConfigMap update"]
        end
    end
Loading
Method Speed Cluster Support Best For
hostpath Instant Local k3d only Rapid local development
kubectl Fast Any cluster Remote/cloud clusters
configmap Fast Any cluster Configuration files

1. Host Path Sync (Default for Local)

Method: hostpath

Uses k3d volume mounts to share files directly between host and cluster. This is the fastest method but only works with local k3d clusters.

# Fastest option for local development
displace project dev --local --sync-method hostpath

How it works:

  • k3d mounts your project directory into the cluster
  • File changes are instantly visible inside pods
  • No network transfer required
  • Near-zero latency

Best for:

  • Local k3d development
  • Rapid iteration on code
  • Testing configuration changes

2. kubectl Sync (Default for Remote)

Method: kubectl

Uses kubectl cp to copy changed files to running pods. Works with any cluster but has network latency.

# Works with any cluster (local or cloud)
displace project dev --cluster my-cluster --sync-method kubectl

How it works:

  • Watches for local file changes
  • Uses kubectl cp to copy files to pods
  • Targets specific container if specified
  • Syncs to all matching pods

Best for:

  • Remote cloud clusters (EKS, GKE, AKS, DOKS)
  • Development across network
  • When hostpath not available

3. ConfigMap Sync

Method: configmap

Updates Kubernetes ConfigMaps with file contents. Ideal for configuration files that pods read at runtime.

# For syncing configuration files
displace project dev --sync-method configmap

How it works:

  • Reads file contents when changed
  • Creates or updates ConfigMaps in the cluster
  • Pods automatically pick up ConfigMap changes
  • Works well with config files and environment settings

Best for:

  • Configuration file updates
  • Environment variable changes
  • Files mounted as ConfigMaps in pods

Command Reference

Basic Syntax

displace project dev [flags]

Flags

Flag Short Description
--local -l Use local k3d cluster (fastest dev experience)
--cluster -c Target cluster name
--namespace -n Target Kubernetes namespace
--sync-method Sync method: hostpath, kubectl, or configmap
--watch -w Paths to watch (can be used multiple times)
--container Target container name in pod
--selector Pod selector (e.g., app=myapp)
--no-sync Watch only, don't sync (for debugging)
--verbose -v Show detailed sync output

Examples

# Basic local development
displace project dev --local

# Watch specific directories
displace project dev --local --watch ./src --watch ./public

# Target specific namespace
displace project dev --local --namespace my-app

# Sync to specific container
displace project dev --cluster prod --container php-fpm

# Use pod selector
displace project dev --local --selector app=wordpress

# Verbose output for debugging
displace project dev --local --verbose

File Watching

Watched Directories

By default, dev mode watches the current directory. Customize with --watch:

# Watch multiple directories
displace project dev --local \
  --watch ./src \
  --watch ./config \
  --watch ./public

Excluded Patterns

The following patterns are automatically excluded from sync:

Pattern Description
*.git* Git files and directories
*.displace* Displace configuration
node_modules/** Node.js dependencies
vendor/** PHP/Go vendor dependencies
__pycache__/** Python bytecode cache
*.pyc Python compiled files
.DS_Store macOS metadata
*.swp, *.swo, *~ Editor swap files
.env.local, .env*.local Local environment files

Debouncing

Dev mode implements smart debouncing to prevent sync storms:

  • Delay: 500ms after last change before syncing
  • Batching: Multiple rapid changes are grouped
  • Deduplication: Same file changed multiple times syncs once

This prevents overwhelming the cluster during rapid edits like auto-save.

Workflow Examples

PHP/Laravel Development

# Initialize Laravel project
displace project init laravel

# Deploy to local cluster
displace project deploy --cluster displace-local

# Start dev mode watching src directory
displace project dev --local --watch ./src

# Make changes to src/app/Http/Controllers/HomeController.php
# Changes automatically sync to running pods

Static Site Development

# Initialize static site
displace project init static

# Deploy locally
displace project deploy --cluster displace-local

# Start dev mode
displace project dev --local --watch ./content

# Edit content files - changes sync immediately

Node.js/Next.js Development

# Start dev mode watching source files
displace project dev --local \
  --watch ./src \
  --watch ./pages \
  --watch ./components

# Changes to React components sync to pods
# Hot reload picks up changes

Cluster Selection

Dev mode automatically selects the appropriate cluster:

Priority Order

  1. Explicit cluster flag: --cluster my-cluster
  2. Local flag: --local selects local k3d cluster
  3. Project deployment: Uses cluster where project is deployed
  4. Local deployment preferred: Prefers local over remote for dev

Automatic Detection

# If project is deployed to local cluster
displace project dev
# Automatically targets local deployment

# If deployed to multiple clusters, prefer local
displace project dev
# Uses local cluster for dev mode

# If only deployed to remote cluster
displace project dev
# Uses remote cluster with kubectl sync

Container and Pod Targeting

Default Targeting

Dev mode automatically finds pods matching your project:

# Finds pods with label matching project name
displace project dev --local
# Targets pods where app=<project-name>

Custom Pod Selector

# Target specific pods
displace project dev --local --selector app=frontend

# Target by deployment
displace project dev --local --selector deployment=my-app

Container Selection

For pods with multiple containers:

# Target specific container
displace project dev --local --container nginx

Troubleshooting

No Pods Found

Error: no running pods found matching selector: app

Solution:

  1. Check project is deployed: displace project info
  2. Verify pods are running: kubectl get pods -n <namespace>
  3. Use explicit selector: --selector app=<name>

Sync Failures

kubectl cp failed: ...

Solutions:

  1. Check kubectl access: kubectl get pods
  2. Verify container has tar: Some minimal images lack it
  3. Check file permissions in container
  4. Use verbose mode: --verbose

Host Path Not Working

Error: host path mount not configured

Solution: k3d cluster needs volume mount. Create with:

k3d cluster create my-cluster --volume /path/to/project:/app

Or use kubectl sync method:

displace project dev --sync-method kubectl

Files Not Syncing

Check:

  1. File isn't in excluded patterns
  2. Watch path includes the directory
  3. Sync method is appropriate for cluster type
  4. Run with --verbose to see file events

High CPU Usage

Solutions:

  1. Narrow watch scope: --watch ./src instead of .
  2. Check for recursive symlinks
  3. Exclude large directories: node_modules, vendor

Best Practices

Local Development

  1. Use hostpath sync for fastest iteration
  2. Watch only necessary directories to reduce CPU
  3. Use local wildcard DNS for easy access: http://myapp.local.displace.tech

Remote Development

  1. Use kubectl sync for cloud clusters
  2. Target specific directories to minimize transfer
  3. Consider network latency when making rapid changes

General Tips

  1. Start with verbose mode to understand sync behavior
  2. Use pod selector when project has multiple deployments
  3. Combine with hot reload for best experience
  4. Keep watch paths minimal for performance
  5. Use displace project restart to pick up ConfigMap changes that require pod restart

Integration with Templates

Each template is optimized for dev mode:

Static Site

  • Watches ./content directory
  • Instant content updates via hostpath

WordPress

  • Watches ./wp-content for theme/plugin changes
  • PHP changes reflected immediately

Laravel

  • Watches ./src for application code
  • Controllers, views, and routes sync instantly
  • Assets may need rebuild (use npm run dev locally)

Requirements

  • Kubernetes cluster running and accessible
  • kubectl configured and working
  • Project deployed to target cluster
  • Docker running for local k3d clusters

Related Documentation:

Home

Getting Started

Providers

Templates

Development

Guides

Infrastructure

Reference

Clone this wiki locally