Quickstart

Deploy your first app to Google Cloud in 5 minutes.

Prerequisites

Before you start, install these tools:

1. Node.js 18+

# Check your version
node --version

2. Google Cloud CLI

# macOS
brew install google-cloud-sdk

# Or download from: https://cloud.google.com/sdk/docs/install

3. Terraform

# macOS
brew install terraform

# Or download from: https://developer.hashicorp.com/terraform/downloads

Step 1: Install StackSolo

# Use directly with npx (recommended)
npx stacksolo --version

# Or install globally
npm install -g stacksolo

Step 2: Login to Google Cloud

gcloud auth login
gcloud auth application-default login

Step 3: Initialize a Project

Create a new directory and initialize StackSolo:

mkdir my-app
cd my-app
stacksolo init

The init command will:

1. Ask you to select a GCP project
2. Enable required APIs
3. Ask what type of app you’re building
4. Generate a config file

Step 4: Look at Your Config

After init, you’ll have a .stacksolo/stacksolo.config.json file:

{
  "project": {
    "name": "my-app",
    "gcpProjectId": "your-gcp-project",
    "region": "us-central1",
    "backend": "cdktf",

    "networks": [{
      "name": "main",
      "functions": [{
        "name": "api",
        "runtime": "nodejs20",
        "entryPoint": "api",
        "allowUnauthenticated": true
      }],
      "loadBalancer": {
        "name": "gateway",
        "routes": [
          { "path": "/*", "backend": "api" }
        ]
      }
    }]
  }
}

Step 5: Create Your Function

Create a simple API function:

mkdir -p functions/api

Create functions/api/package.json:

{
  "name": "api",
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

Create functions/api/index.js:

const functions = require('@google-cloud/functions-framework');

functions.http('api', (req, res) => {
  res.json({ message: 'Hello from StackSolo!' });
});

Step 6: Deploy

stacksolo deploy

StackSolo will:

1. Generate CDKTF/Terraform code
2. Create a Cloud Storage bucket for your function code
3. Deploy your Cloud Function
4. Create a load balancer
5. Output the URL

Step 7: Test Your API

curl http://<your-load-balancer-ip>/
# {"message":"Hello from StackSolo!"}

What Just Happened?

StackSolo created these GCP resources:

• A Cloud Storage bucket (for function source code)
• A Cloud Function (Gen2)
• A serverless NEG (Network Endpoint Group)
• A backend service
• A URL map
• An HTTP proxy
• A global IP address
• A forwarding rule

All from a 20-line config file.

Common Commands

# See what would be deployed (dry run)
stacksolo deploy --preview

# Check deployment status
stacksolo status

# View logs
stacksolo logs

# View deploy event history
stacksolo events

# List registered projects
stacksolo list

# Destroy all resources
stacksolo destroy

Starting from a Stack

Want to start with a complete, working application? Clone a pre-built stack:

# List available stacks
stacksolo clone --list

# Clone a stack (e.g., RAG Platform - AI chatbot with admin dashboard)
stacksolo clone rag-platform my-chatbot
cd my-chatbot
npm install
stacksolo deploy

Stacks include full source code, infrastructure config, and documentation.

Adding Another Project

If you want to add another app that shares the same VPC (to avoid GCP quota limits):

# Clone from your existing project
mkdir my-second-app && cd my-second-app
stacksolo clone ../my-app --name my-second-app

# Add your functions/containers to the config, then deploy
stacksolo deploy

The new project will reuse the VPC from my-app instead of creating a new one.

Troubleshooting

”Permission denied” errors

Make sure you’re authenticated:

gcloud auth login
gcloud auth application-default login

“API not enabled” errors

StackSolo tries to enable APIs automatically. If it fails, enable them manually:

gcloud services enable cloudfunctions.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable run.googleapis.com

“Terraform not found”

Install Terraform:

brew install terraform

Next Steps

• Configuration Guide - Learn all config options
• Local Development - Run locally with Kubernetes
• Resource Sharing - Share VPCs, buckets, and registries
• CLI Reference - All commands explained