Getwebstack

Getwebstack offers a quick way to build a full-stack application and deploy it locally and in the cloud, with the help of prebuilt, cloud native, micro-apps. We promote breaking the monolith architecture into composable and reusable modules from the beginning, starting from well-defined business areas.

Documentation

You can find detailed use of Getwebstack CLI on the documentation page.

Support

For any issue you can contact us on Discord.

Quick start

Getwebstack offers a cli, gws, through which you can build and manage your app.

1. Prerequisites

gws is build using NodeJs. Please install node and npm. You can install from here.

2. Install gws

Install the cli.

npm install -g @getwebstack/gws

3. Login

In order to have access to the features of the CLI, you must first log in.

gws login

3. Create a new project

Now you can create your first project.

gws project init --name cool-project

4. Add a landing-page

We will use a prebuilt frontend component based on Angular from our library of micro-frontends.

You will need to mention what is the route where the component will be accessible from, as well as associating a local domain. In this example we will route all the traffic to the landing page.

gws component add --name landing --template angular
? Route path: /(.*)
? Local host: local-project.com

You can check all the available components here.

5. Start your app locally

Option 1: Using Minikube (Local Development)

This will start a Minikube cluster and deploy the project locally.

gws up --target local

This command will:

• Start a Minikube cluster with Docker driver
• Enable ingress and install cert-manager
• Use *.getwebstack.com wildcard DNS (no /etc/hosts editing required!)
• Setup SSL certificates with mkcert for all hosts defined in webstack.json
• Automatically create cert-manager ClusterIssuer and Certificate resources
• Build Docker images locally
• Deploy all services to a dedicated Kubernetes namespace based on the project name (lowercase, non-alphanumeric characters replaced with -)
• By default, if the namespace already exists, prompts whether to delete and recreate it
• Print commands you can run (e.g., minikube service <name> --url) to reach services without additional tunnelling

Note on hostnames: Your webstack.json should use *.getwebstack.com domains (e.g., myproject.getwebstack.com, api-myproject.getwebstack.com). These domains automatically resolve to 127.0.0.1 without any configuration!

Note for Linux users: Minikube services are reachable directly at the Minikube VM IP (see minikube ip). Use minikube service <name> --url or kubectl port-forward to reach workloads from your machine—no minikube tunnel required.

Options:

• --clean: Automatically delete and recreate namespaces without prompting (clean deployment)

  gws up --target local --clean

• --skip-validation: Bypass dependency pre-flight checks (not recommended unless you know what you are doing)

  gws up --target local --skip-validation

• --skip-dev: Disable dev mode (Mutagen file sync, auto-rebuild watchers) and use static deployment (default: false)

  gws up --target local --skip-dev

• --no-interactive: Disable interactive prompts for automated environments (CI/CD)

  gws up --target local --no-interactive

• --verbose or -v: Show detailed command output (useful for debugging deployment issues)

  gws up --target local --verbose

• --debug: Show full command output including all system commands and their results

  gws up --target local --debug

By default, gws up shows only high-level progress messages. Use --verbose to see detailed deployment steps, or --debug for complete output including all kubectl commands and their results.

Development Access Modes

GetWebStack CLI provides two modes for accessing your local services:

Local Mode (Default)

Fast, private access via port-forwarding with chisel tunnels:

gws up --target local

Your services are automatically accessible at http://<service-name>.local.getwebstack.dev:<port>.

Features:

• ✅ Chisel-based reliable tunnels (auto-reconnecting)
• ✅ Runs as background daemon on host machine
• ✅ Health monitoring with auto-restart every 10 seconds
• ✅ Port conflict detection and resolution
• ✅ Tunnels persist after closing terminal
• ✅ Works on Windows, macOS, Linux

Example URLs:

• Service: api-service → http://api.local.getwebstack.dev:8080
• Service: app-service → http://app.local.getwebstack.dev:3000

Check tunnel status:

gws status

Stop tunnels:

gws down

Public Mode (Optional)

Public access for webhooks, mobile testing, or team sharing:

gws up --target local --enable-public-tunnel

Your services are accessible at https://<username>.public.getwebstack.dev/<service>.

Features:

• ✅ Public HTTPS URLs (shareable anywhere)
• ✅ Per-developer isolation (username-based subdomains)
• ✅ Single tunnel per developer (not per service)
• ✅ Path-based routing (e.g., /api, /app, /docs)
• ✅ Token-based authentication
• ✅ Auto-deploys nginx-ingress if not present
• ✅ SSL certificate validation before deployment

Example URLs:

• Service: api-service → https://vlad.public.getwebstack.dev/api
• Service: app-service → https://vlad.public.getwebstack.dev/app
• Service: docs-service → https://vlad.public.getwebstack.dev/docs

⚠️ Security Warning: Your local development environment is publicly accessible while public tunnel is active. Use only for testing webhooks, mobile access, or sharing with team.

Prerequisites for public mode:

• Tunnel auth token in ~/.gws/tunnel-token (obtain from team lead)
• DNS propagated for *.public.getwebstack.dev
• Production tunnel server deployed (see docs/implementations/task-29-dev-tunnel-implementation.md)

Comparison: Local vs Public Mode

| Feature | Local Mode | Public Mode | |---------|------------|-------------| | Access | Your machine only | Anywhere on internet | | Speed | Fastest | Slight latency | | Webhooks | ❌ Won't work | ✅ Works | | Mobile Testing | ❌ Same network only | ✅ Any network | | Security | ✅ Private | ⚠️ Public | | Ports | Custom (8080, 3000, etc.) | Standard (80, 443) | | Setup | Automatic | Requires auth token |

Stopping Services

# Stop tunnels only (keeps Kubernetes resources running)
gws down

# Stop tunnels and delete project namespace
gws down --delete-namespace

# Stop everything (delete entire Minikube cluster)
gws down --delete-cluster

Prerequisites for local deployment:

• Minikube installed
• kubectl (optional, useful for debugging; CLI talks to the Kubernetes API directly)
• Docker Engine running locally (CLI optional; gws talks to the Docker API via dockerode)
• mkcert installed for SSL certificates
• chisel installed for local tunnels (install: brew install chisel on macOS, curl https://i.jpillora.com/chisel! | bash on Linux, scoop install chisel on Windows)
• Git installed (the CLI reads repository metadata during setup)
• Mutagen (optional, auto-installed for file sync feature)

gws up now validates these dependencies and their minimum versions before starting the deployment. If something is missing or outdated, the CLI will:

1. Offer to install missing dependencies automatically (interactive mode)
2. Show actionable installation commands for your operating system
3. Exit early before attempting deployment

Interactive Installation: When a required dependency is missing, gws up will prompt you to install it automatically:

? Would you like to install missing dependencies now? (mkcert) › (Y/n)

If you choose "Yes", the CLI will run the appropriate installation commands for your OS (e.g., brew install mkcert on macOS, sudo apt install mkcert on Ubuntu).

Non-Interactive Mode:

• Use --skip-validation to bypass all dependency checks (not recommended)
• Use --no-interactive to disable installation prompts (useful for CI/CD environments)
• In CI environments (detected via CI env var), interactive prompts are automatically disabled

🔥 Mutagen File Sync and Hot Reload

NEW: gws up now uses Mutagen for intelligent file synchronization and automatic rebuilds during local development. This enables a fast inner development loop where code changes sync to containers in under 1 second without manual rebuilds!

What happens when you run gws up:

1. Auto-detects project types (Node.js, TypeScript, Angular, React, Next.js, Vue, Astro, Python, Go, Java, Rust)
2. Generates skaffold.yaml configurations with smart sync patterns per project type
3. Validates all configurations before starting
4. Watches for file changes and automatically:
   • Syncs code changes (.ts, .js, .py, etc.) → 2-3 seconds ⚡
   • Rebuilds images when Dockerfile changes → 30-60 seconds 🔄
   • Redeploys when Kubernetes manifests change → 10 seconds 📦

How File Sync Works:

| File Type | Sync Method | Speed | Example | |-----------|-------------|-------|----------| | Source code (.ts, .js, .py) | Bidirectional Mutagen sync | 0.5-1 sec | Edit src/app.ts → instantly reflected in container |

First-Time Setup:

When you first run gws init, the CLI will:

1. Scan your workspace for services
2. Detect project types with confidence levels (✅ high, ⚠️ medium, ❓ low)
3. Allow you to confirm or correct detections
4. Generate skaffold.yaml for each service
5. Update webstack.json with service configurations

gws init

# Output:
# 🔍 Detecting project types for Skaffold configuration...
#
# 📦 Detected Projects:
#
# ✅ getwebstack-api:
#    Type: typescript (high confidence)
#    Path: /workspace/getwebstack-api
#    Detected from: package.json, typescript detected
#
# ✅ getwebstack-app:
#    Type: angular (high confidence)
#    Path: /workspace/getwebstack-app
#    Detected from: package.json, @angular/core dependency
#
# ? Are these project type detections correct? › (Y/n)

Manual Configuration for Generic Types:

If the CLI detects a project as generic or you're using an unsupported framework, it will generate a basic skaffold.yaml template with TODO comments and helpful guidance:

# TODO: This is a generic Skaffold configuration that may need customization
# Please review and adjust the following:
#   - Verify the Dockerfile path and target
#   - Customize sync patterns for your project structure
#   - Add appropriate port forwarding
#   - Check Kubernetes manifest paths
# Documentation: https://skaffold.dev/docs/

apiVersion: skaffold/v4
kind: Config
metadata:
  name: my-service
# ... rest of config

Supported Project Types:

• Node.js/TypeScript: Express, Nest.js, plain Node
• Frontend Frameworks: Angular, React, Next.js, Vue, Astro
• Backend Languages: Python (Flask, FastAPI), Go, Java (Maven, Gradle), Rust
• Generic: Any project with manual configuration

Development Workflow:

# 1. Initialize project (one-time setup)
gws init

# 2. Start development with Mutagen file sync and auto-rebuild
gws up --target local

# 🚀 Starting Skaffold development mode...
#    📁 File watching enabled - your changes will auto-sync
#    🔄 Dockerfile changes will trigger rebuilds
#    ⚡ Press Ctrl+C to stop

# 3. Edit your code
# → Changes sync automatically in 2-3 seconds!

# 4. Edit Dockerfile
# → Automatic rebuild triggered

# 5. Press Ctrl+C to stop when done

Disabling Skaffold:

If you need to use static deployment without dev mode:

gws up --target local --skip-dev

Mutagen Installation:

Mutagen is automatically installed when needed. The CLI will:

1. Check if Mutagen is already installed
2. Try package manager installation (Homebrew on macOS, apt/yum on Linux, Chocolatey on Windows)
3. Fall back to direct binary download if needed
4. Verify installation and version compatibility

Note: On Windows, Mutagen installation may require administrator privileges. If you're not running as admin, the CLI will provide manual installation instructions.

Troubleshooting:

• File sync not working? Use gws status to check Mutagen sync sessions and gws dev logs <service> to view watcher logs
• Slow rebuilds? Ensure you're using BuildKit and Docker layer caching
• Port conflicts? Run gws up which validates and detects port conflicts across services
• Need static deployment? Use --skip-dev flag to disable Mutagen file sync and auto-rebuild watchers

For more details, see the Skaffold documentation.

Option 2: Using the cloud cluster

This will deploy to your configured cloud environment.

gws cluster start

The components have live reloading enabled. If you change something in the code of the component, the changes will automatically apply.

6. Check deployment status

While the project is initialised you can check the status of deployment for the landing component.

gws component status landing

7. Check logs

In addition to the status, you can also check the logs in the component to get more details.

gws component logs landing

8 Test the app

Once the setup of the component is complete you can test it in your browser.

Open https://local-project.com.