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: *.myapp.acme.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.acme.getwebstack.dev
  🔗 App:  https://app.myapp.acme.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

Accessing your services (unified URLs)​

After gws up, each HTTP service is reachable locally at a unified URL that is identical to the one a visitor uses when you gws share it:

https://<service>.<project>.<org>.getwebstack.dev

The same URL works whether you run the app locally or share it — no per‑environment config, no CORS surprises when you flip between the two. gws up prints these URLs when your deployment is registered with an organization.

  • Port :443 (no port in the URL). On k3d, gws up maps the cluster gateway onto host 443 so the URL is portless, exactly like the shared origin. This is bound to 127.0.0.1 only (not exposed to your LAN).
  • Fallback to :9443. If host 443/80 is already in use, Docker runs rootless, or you use a non‑k3d provider, gws up prints the URL with :9443 and tells you why. Free port 443 (k3d) for full same‑port parity.
  • .local URLs are gone. The CLI no longer emits local.getwebstack.dev hosts — the unified {service}.{projectSlug}.{orgSlug}.getwebstack.dev host is the only one. (The static *.local DNS record is kept only so deployments from older gws versions keep resolving.)

Calling one service from another in the browser​

The unified host is shared across your services (the gws-namespace cookie selects the deployment), so a cross‑subdomain call from client.* to server.* must send that cookie. Configure your app accordingly:

  • Client: send credentials on cross‑origin requests — e.g. fetch(url, { credentials: "include" }) or Axios withCredentials: true.
  • Server: set CORS credentials: true and allow the portless unified origin (https://client.<project>.<org>.getwebstack.dev) — not the :9443 form.

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.acme.getwebstack.dev
  🔗 App: https://app.myapp.acme.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.acme.getwebstack.dev
  🔗 App: https://app.myapp.acme.getwebstack.dev
  🔗 Picker: https://myapp.acme.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.acme.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​