Deploy iCommerce on GCP

Run StateSet iCommerce 24/7 for approximately $5-12/month on Google Cloud Platform. This guide walks you through deploying a persistent iCommerce Gateway on a GCP Compute Engine VM using Docker, with durable state, baked-in binaries, and safe restart behavior.

Goal

Deploy a production-ready StateSet iCommerce Gateway on GCP Compute Engine with:

Persistent configuration and workspace data
Docker-based isolated runtime
SSH tunnel access for secure administration
Automatic restart on failure

Pricing varies by machine type and region. Start with the smallest VM that fits your workload and scale up if you encounter out-of-memory errors.

What you’ll build

Create GCP infrastructure

Set up a GCP project, enable billing, and create a Compute Engine VM.

Install Docker runtime

Install Docker for isolated, reproducible application runtime.

Configure persistent storage

Mount host directories for configuration and workspace data that survives restarts.

Deploy the Gateway

Build and launch the iCommerce Gateway with Docker Compose.

Access securely

Connect via SSH tunnel from your local machine.

Prerequisites

Before you begin, ensure you have:

GCP account (free tier eligible for e2-micro)
gcloud CLI installed, or access to the Cloud Console
SSH access from your local machine
Basic familiarity with terminal commands
StateSet API credentials
Model provider credentials (OpenAI, Anthropic, etc.)

Optional integrations:

WhatsApp Business API credentials
Telegram bot token
Gmail OAuth credentials

Quick path (experienced operators)

If you’re familiar with GCP and Docker, follow this condensed workflow:

Create GCP project and enable Compute Engine API
Create Compute Engine VM (e2-small, Debian 12, 20GB)
SSH into the VM
Install Docker
Clone the StateSet iCommerce repository
Create persistent host directories
Configure .env and docker-compose.yml
Bake required binaries, build, and launch

1) Install gcloud CLI

gcloud CLI (recommended)
Cloud Console

Install from the Google Cloud SDK documentation.Initialize and authenticate:

gcloud init
gcloud auth login

2) Create a GCP project

CLI
Console

gcloud projects create my-icommerce-project --name="StateSet iCommerce"
gcloud config set project my-icommerce-project

Enable billing at console.cloud.google.com/billing (required for Compute Engine).Enable the Compute Engine API:

gcloud services enable compute.googleapis.com

3) Create the VM

Machine type comparison

Type	Specs	Cost	Notes
e2-small	2 vCPU, 2GB RAM	~$12/mo	Recommended for production
e2-micro	2 vCPU (shared), 1GB RAM	Free tier eligible	May OOM under load

CLI
Console

gcloud compute instances create icommerce-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small \
  --boot-disk-size=20GB \
  --image-family=debian-12 \
  --image-project=debian-cloud

Go to Compute Engine > VM instances > Create instance
Name: icommerce-gateway
Region: us-central1, Zone: us-central1-a
Machine type: e2-small
Boot disk: Debian 12, 20GB
Click Create

4) SSH into the VM

CLI
Console

gcloud compute ssh icommerce-gateway --zone=us-central1-a

SSH key propagation can take 1-2 minutes after VM creation. If the connection is refused, wait and retry.

5) Install Docker

Run the following commands on the VM:

sudo apt-get update
sudo apt-get install -y git curl ca-certificates
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect:

exit

SSH back in:

gcloud compute ssh icommerce-gateway --zone=us-central1-a

Verify the installation:

docker --version
docker compose version

6) Clone the repository

git clone https://github.com/stateset/stateset-icommerce.git
cd stateset-icommerce

7) Create persistent host directories

Docker containers are ephemeral. All long-lived state must live on the host to survive restarts and rebuilds.

mkdir -p ~/.stateset
mkdir -p ~/.stateset/workspace

8) Configure environment variables

Create a .env file in the repository root:

STATESET_IMAGE=stateset-icommerce:latest
STATESET_GATEWAY_TOKEN=change-me-now
STATESET_GATEWAY_BIND=lan
STATESET_GATEWAY_PORT=18789

STATESET_CONFIG_DIR=/home/$USER/.stateset
STATESET_WORKSPACE_DIR=/home/$USER/.stateset/workspace

STATESET_KEYRING_PASSWORD=change-me-now
XDG_CONFIG_HOME=/home/node/.stateset

Generate strong secrets:

openssl rand -hex 32

Do not commit the .env file to version control. It contains sensitive credentials.

9) Docker Compose configuration

Create or update docker-compose.yml:

services:
  icommerce-gateway:
    image: ${STATESET_IMAGE}
    build: .
    restart: unless-stopped
    env_file:
      - .env
    environment:
      - HOME=/home/node
      - NODE_ENV=production
      - TERM=xterm-256color
      - STATESET_GATEWAY_BIND=${STATESET_GATEWAY_BIND}
      - STATESET_GATEWAY_PORT=${STATESET_GATEWAY_PORT}
      - STATESET_GATEWAY_TOKEN=${STATESET_GATEWAY_TOKEN}
      - STATESET_KEYRING_PASSWORD=${STATESET_KEYRING_PASSWORD}
      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    volumes:
      - ${STATESET_CONFIG_DIR}:/home/node/.stateset
      - ${STATESET_WORKSPACE_DIR}:/home/node/.stateset/workspace
    ports:
      # Keep the Gateway loopback-only; access via SSH tunnel
      - "127.0.0.1:${STATESET_GATEWAY_PORT}:18789"
    command:
      [
        "node",
        "dist/index.js",
        "gateway",
        "--bind",
        "${STATESET_GATEWAY_BIND}",
        "--port",
        "${STATESET_GATEWAY_PORT}"
      ]

To expose the Gateway publicly, remove the 127.0.0.1: prefix from the port mapping and configure firewall rules accordingly. See the security documentation for guidance.

10) Bake required binaries into the image

Installing binaries inside a running container is a common mistake. Anything installed at runtime will be lost on restart. All external binaries required by skills must be installed at image build time.

If you add new skills later that depend on additional binaries, you must:

Update the Dockerfile
Rebuild the image
Restart the containers

Example Dockerfile

FROM node:22-bookworm

RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*

# Gmail CLI
RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog

# Google Places CLI
RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces

# WhatsApp CLI
RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli

# Add more binaries as needed using the same pattern

WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts

RUN corepack enable
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build

ENV NODE_ENV=production

CMD ["node","dist/index.js"]

11) Build and launch

docker compose build
docker compose up -d icommerce-gateway

Verify binaries are installed:

docker compose exec icommerce-gateway which gog
docker compose exec icommerce-gateway which goplaces
docker compose exec icommerce-gateway which wacli

Expected output:

/usr/local/bin/gog
/usr/local/bin/goplaces
/usr/local/bin/wacli

12) Verify the Gateway

docker compose logs -f icommerce-gateway

Success output:

[gateway] listening on ws://0.0.0.0:18789

13) Access from your local machine

Create an SSH tunnel to forward the Gateway port:

gcloud compute ssh icommerce-gateway --zone=us-central1-a -- -L 18789:127.0.0.1:18789

Open in your browser:

http://127.0.0.1:18789/

Enter your gateway token to authenticate.

Persistence reference

All long-lived state must survive restarts, rebuilds, and reboots. Docker is not the source of truth.

Component	Location	Persistence	Notes
Gateway config	`/home/node/.stateset/`	Host volume mount	Includes tokens, settings
Model auth profiles	`/home/node/.stateset/`	Host volume mount	OAuth tokens, API keys
Skill configs	`/home/node/.stateset/skills/`	Host volume mount	Skill-level state
Agent workspace	`/home/node/.stateset/workspace/`	Host volume mount	Code and agent artifacts
WhatsApp session	`/home/node/.stateset/`	Host volume mount	Preserves QR login
Keyring	`/home/node/.stateset/`	Host volume + password	Requires `STATESET_KEYRING_PASSWORD`
External binaries	`/usr/local/bin/`	Docker image	Must be baked at build time
Node runtime	Container filesystem	Docker image	Rebuilt every image build
OS packages	Container filesystem	Docker image	Do not install at runtime

Updates

To update StateSet iCommerce on the VM:

cd ~/stateset-icommerce
git pull
docker compose build
docker compose up -d

Troubleshooting

SSH connection refused

SSH key propagation can take 1-2 minutes after VM creation. Wait and retry. Check your OS Login profile:

gcloud compute os-login describe-profile

Ensure your account has the required IAM permissions (Compute OS Login or Compute OS Admin Login).

Out of memory (OOM)

If using e2-micro and hitting OOM, upgrade to e2-small or e2-medium:

# Stop the VM
gcloud compute instances stop icommerce-gateway --zone=us-central1-a

# Change machine type
gcloud compute instances set-machine-type icommerce-gateway \
  --zone=us-central1-a \
  --machine-type=e2-small

# Start the VM
gcloud compute instances start icommerce-gateway --zone=us-central1-a

Container fails to start

Check logs for errors:

docker compose logs icommerce-gateway

Verify environment variables are set correctly:

docker compose config

Service accounts (security best practice)

For personal use, your default user account works fine. For automation or CI/CD pipelines, create a dedicated service account with minimal permissions: Create a service account:

gcloud iam service-accounts create icommerce-deploy \
  --display-name="iCommerce Deployment"

Grant Compute Instance Admin role:

gcloud projects add-iam-policy-binding my-icommerce-project \
  --member="serviceAccount:icommerce-deploy@my-icommerce-project.iam.gserviceaccount.com" \
  --role="roles/compute.instanceAdmin.v1"

Avoid using the Owner role for automation. Use the principle of least privilege. See GCP IAM roles documentation for details.

Next steps

Messaging Channels

Set up WhatsApp, Telegram, and other messaging integrations.

Skills

Configure and extend agent capabilities with custom skills.

CLI Reference

Learn the full CLI command set for managing your iCommerce instance.

Security

Review security best practices for production deployments.

​Deploy iCommerce on GCP

​Goal

​What you’ll build

​Prerequisites

​Quick path (experienced operators)

​1) Install gcloud CLI

​2) Create a GCP project

​3) Create the VM

​Machine type comparison

​4) SSH into the VM

​5) Install Docker

​6) Clone the repository

​7) Create persistent host directories

​8) Configure environment variables

​9) Docker Compose configuration

​10) Bake required binaries into the image

​Example Dockerfile

​11) Build and launch

​12) Verify the Gateway

​13) Access from your local machine

​Persistence reference

​Updates

​Troubleshooting

​SSH connection refused

​OS Login issues

​Out of memory (OOM)

​Container fails to start

​Service accounts (security best practice)

​Next steps

Messaging Channels

Skills

CLI Reference

Security

Deploy iCommerce on GCP

Goal

What you’ll build

Prerequisites

Quick path (experienced operators)

1) Install gcloud CLI

2) Create a GCP project

3) Create the VM

Machine type comparison

4) SSH into the VM

5) Install Docker

6) Clone the repository

7) Create persistent host directories

8) Configure environment variables

9) Docker Compose configuration

10) Bake required binaries into the image

Example Dockerfile

11) Build and launch

12) Verify the Gateway

13) Access from your local machine

Persistence reference

Updates

Troubleshooting

SSH connection refused

OS Login issues

Out of memory (OOM)

Container fails to start

Service accounts (security best practice)

Next steps