Skip to content
StackSolo

Local Development

StackSolo includes a local development environment that mirrors your production setup using Kubernetes.

Prerequisites

Section titled “Prerequisites”
  • OrbStack with Kubernetes enabled (recommended for macOS)
  • Or any local Kubernetes cluster (minikube, Docker Desktop, etc.)
  • kubectl CLI

Quick Start

Section titled “Quick Start”
Terminal window
# Start local environment
stacksolo dev


# Check what's running
stacksolo dev --status


# View logs
stacksolo dev --logs


# Stop everything
stacksolo dev --stop

What Gets Created

Section titled “What Gets Created”

When you run stacksolo dev, it creates Kubernetes resources that mirror your config:

Your ConfigLocal Equivalent
FunctionsK8s Deployment + Service
ContainersK8s Deployment + Service
UIsK8s Deployment + Service
Load balancer routesK8s Ingress
KernelK8s Deployment (NATS + HTTP)
GCP KernelK8s Deployment (HTTP only)

Plus automatic emulators:

  • Firebase Emulator (Firestore, Auth)
  • Pub/Sub Emulator

Default Ports

Section titled “Default Ports”
ServicePort
Ingress (your app)8000
Firebase Firestore8080
Firebase Auth9099
Firebase UI4000
Pub/Sub8085
Kernel HTTP8090
Kernel NATS4222
GCP Kernel8080

Commands

Section titled “Commands”

Start Development

Section titled “Start Development”
Terminal window
stacksolo dev

Builds and deploys all services to local Kubernetes.

Check Status

Section titled “Check Status”
Terminal window
stacksolo dev --status

Shows running pods and their status.

View Logs

Section titled “View Logs”
Terminal window
# All logs
stacksolo dev --logs


# Specific service
stacksolo dev --logs api

Rebuild

Section titled “Rebuild”
Terminal window
# Force regenerate K8s manifests
stacksolo dev --rebuild

Stop

Section titled “Stop”
Terminal window
stacksolo dev --stop

Tears down all Kubernetes resources.

How It Works

Section titled “How It Works”

  1. Manifest Generation: StackSolo reads your config and generates Kubernetes manifests in .stacksolo/k8s/

  2. Image Building: For each function/container, it builds a Docker image locally

  3. Deployment: Applies manifests to your local Kubernetes cluster

  4. Port Forwarding: Sets up ingress so you can access your app at localhost:8000

Environment Variables

Section titled “Environment Variables”

In local dev, environment variable references are resolved:

{
  "env": {
    "DATABASE_URL": "@database/db.connectionString"
  }
}

Becomes something like:

DATABASE_URL=postgres://user:pass@db-service:5432/mydb

Using the Kernel

Section titled “Using the Kernel”

If your config includes a kernel:

{
  "kernel": {
    "name": "main",
    "firebaseProjectId": "my-project",
    "storageBucket": "uploads"
  }
}

Or GCP kernel:

{
  "gcpKernel": {
    "name": "kernel",
    "firebaseProjectId": "my-project",
    "storageBucket": "uploads"
  }
}

The kernel is automatically built from source and deployed locally.

File Watching

Section titled “File Watching”

Services are built with file watching enabled. When you change source files:

  1. The build process runs automatically
  2. Kubernetes picks up the new image
  3. Your changes are live

Troubleshooting

Section titled “Troubleshooting”

Pods stuck in “Pending”

Section titled “Pods stuck in “Pending””

Check if Kubernetes has enough resources:

Terminal window
kubectl describe pod <pod-name> -n stacksolo

Service not accessible

Section titled “Service not accessible”

Check the ingress:

Terminal window
kubectl get ingress -n stacksolo

Build failing

Section titled “Build failing”

Check the build logs:

Terminal window
stacksolo dev --logs <service-name>

Reset everything

Section titled “Reset everything”
Terminal window
stacksolo dev --stop
kubectl delete namespace stacksolo
stacksolo dev

Next Steps

Section titled “Next Steps”