Skip to main content

gws up

Deploy services to a Kubernetes cluster.

Usage​

gws up [options]

Output:

🚀 Deploying GetWebstack...

✓ Validating dependencies...
  ✓ Docker: 24.0.0
  ✓ Git: 2.40.0
  ✓ mkcert: 1.4.4

✓ Creating k3d cluster 'myapp'... (15s)
✓ Generating TLS certificates...
  ✓ Created: *.local.getwebstack.dev

✓ Building Docker images...
  ✓ api: localhost:5000/myapp-api:latest (25s)
  ✓ app: localhost:5000/myapp-app:latest (30s)

✓ Deploying to namespace 'myapp'...
  ✓ Created namespace
  ✓ Deployed 2 services
  ✓ Pods running (2/2)

✓ Configuring Gateway API...
  ✓ Created HTTPRoutes
  ✓ Port-forward active (8080, 9443)

✓ Starting file sync...
  ✓ api: active (0.5s latency)
  ✓ app: active (0.6s latency)

✓ Activating auto-rebuild watchers...
  ✓ Watching Dockerfiles

Deployment successful! 🎉

Services available at:
  🔗 API:  https://api.myapp.local.getwebstack.dev
  🔗 App:  https://app.myapp.local.getwebstack.dev

File sync active:
  📁 File sync: ✓ (0.5s latency)
  🔄 Auto-rebuild: ✓ (Dockerfile changes)

Next steps:
  - Edit code locally (changes sync automatically)
  - View status: gws status
  - View logs: gws logs
  - Stop: gws down

Note: This command must be run from within your project directory.

Options​

OptionDescriptionDefault
-w, --worktree <name>Worktree name to deployMain project deployment
-p, --project <name>Project name to deploy fromAuto-detected from current directory
-y, --yesSkip confirmation promptsfalse

Examples:


# Deploy from a specific project, a specific worktree
gws up -p myapp -w feature-auth 

# Deploy specific worktree for current directory project.
gws up -w feature-auth

# Deploy from a specific project. Deploys the main project, not a worktree.
gws up -p myapp

# Skip prompts
gws up -y

# deploy project from current dorectory
gws up

Multirepo Behavior​

When running gws up in a multirepo setup, the command deploys all services from each repository to a single Kubernetes namespace.

Project Structure​

myapp/                          # Parent directory
├── .worktrees/                 # Shared worktrees folder (at parent level)
│   └── feature-auth/           # One folder per worktree name
│       ├── api/                # Worktree for api repo
│       │   └── src/
│       └── app/                # Worktree for app repo
│           └── src/
├── api/                        # Git repo 1
│   ├── .git/
│   └── src/
└── app/                        # Git repo 2
    ├── .git/
    └── src/

Deploying Main Workspace​

cd myapp
gws up

What happens:

  1. Detects all repositories in myapp/ (api, app)
  2. Builds Docker image for each service
  3. Deploys all services to namespace myapp
  4. Sets up routing for all services

Result:

Services available at:
  🔗 API: https://api.myapp.local.getwebstack.dev
  🔗 App: https://app.myapp.local.getwebstack.dev

Deploying Worktree​

cd myapp
gws up -w feature-auth

What happens:

  1. Detects all repositories in myapp/
  2. Finds worktree feature-auth under .worktrees/
  3. Builds Docker images from worktree directories
  4. Deploys all services to namespace myapp-feature-auth
  5. Sets up routing for all services

Result:

Services available at (same hostnames as the default deployment;
the `gws-namespace` cookie selects this fork):
  🔗 API: https://api.myapp.local.getwebstack.dev
  🔗 App: https://app.myapp.local.getwebstack.dev
  🔗 Picker: https://myapp.local.getwebstack.dev (choose deployment)

Key Points:

  • All services from different repos deploy to the same namespace
  • Each worktree gets its own isolated namespace
  • File sync is active for all services in the deployment

Troubleshooting​

Docker Not Running​

# Start Docker Desktop (macOS/Windows)
open -a Docker

# Or start Docker daemon (Linux)
sudo systemctl start docker

# Verify
docker ps

# Try again
gws up

Port Already in Use​

# Find process using port
sudo lsof -ti:8080

# Kill process
sudo lsof -ti:8080 | xargs kill -9

# Try again
gws up

Build Failed​

# Ensure Dockerfile exists
ls api/Dockerfile

# Check pod logs
gws logs api

DNS Not Resolving​

# Test DNS
nslookup api.myapp.local.getwebstack.dev
# Should return: 127.0.0.1

# Flush DNS cache:
#    macOS: sudo dscacheutil -flushcache
#    Linux: sudo systemd-resolve --flush-caches
#    Windows: ipconfig /flushdns

See Also​