---
name: bigstack-cloud-setup
version: 0.1.0
description: |
  Sets up the Bigscreen cloud repo for local Windows development.
  Checks prerequisites (WSL/Ubuntu, Volta, Node 24, Yarn, Python,
  Redis, PostgreSQL, webpack), clones the repo, configures env files,
  and verifies with yarn dev and tests.
allowed-tools:
  - Bash
  - Read
  - Glob
  - Grep
  - Write
  - AskUserQuestion
---

{{PREAMBLE}}

# /bigstack-cloud-setup — Cloud Development Environment Setup

Set up the Bigscreen cloud monorepo for local development on Windows.

## Overview

The cloud repo is a monorepo with 7 services (admin-api, api, cloud-api, cloud-worker, ws-server, arda-server, arda-webpack), using Yarn workspaces. It requires WSL/Ubuntu for Redis and PostgreSQL, plus several Windows-side tools.

## Workflow

### Step 0: Detect WSL Distro Name

The WSL distro may be registered under different names (e.g. `Ubuntu`, `Ubuntu-18.04`, `Ubuntu-22.04`). Detect it first and use it for all subsequent WSL commands:

```bash
WSL_UBUNTU=$(wsl --list --quiet 2>/dev/null | tr -d '\0' | tr -d '\r' | grep -i "ubuntu" | head -1)
if [ -z "$WSL_UBUNTU" ]; then
  echo "No Ubuntu WSL distro found"
else
  echo "WSL Ubuntu distro: $WSL_UBUNTU"
fi
```

Use `wsl -d "$WSL_UBUNTU"` for **all** WSL commands below. Never hardcode `wsl -d Ubuntu`.

### Step 1: Run Prerequisite Check

Run the prerequisite checker to detect what's installed and what's missing:

```bash
bash "${CLAUDE_SKILL_DIR}/bin/check-prerequisites.sh"
```

This will output a status report for each required component. Review the results with the user.

### Step 2: Install Missing Prerequisites

For each missing prerequisite, ask the user if they want to install it. Follow this order (dependencies matter):

#### 2a: WSL and Ubuntu

WSL is required for Redis and PostgreSQL. Check and install:

```powershell
# Check WSL status (run in PowerShell as admin if needed)
wsl --list --verbose
```

If WSL is not installed or no Ubuntu distro exists:
- Ask the user to run in an **Administrator PowerShell**: `wsl --install -d Ubuntu`
- They will need to reboot after WSL installation
- After reboot, Ubuntu will launch to complete setup (username/password)
- **This is a blocking step** — nothing else works without WSL

#### 2b: Volta and Node.js

```bash
# Check Volta
volta --version 2>/dev/null || echo "MISSING: Install from https://volta.sh/"

# Install Node 18 via Volta
volta install node@24

# Install global tools
volta install typescript ts-node ts-mocha yarn
```

#### 2c: Python 3.10.11

```bash
python --version 2>/dev/null
```

If missing or wrong version, direct the user to: https://www.python.org/downloads/release/python-31011/

**The version must match exactly: 3.10.11**

#### 2d: Redis 6.2.x (in WSL/Ubuntu)

```bash
# Check if Redis is running in WSL
wsl -d "$WSL_UBUNTU" -- redis-cli -v 2>/dev/null
wsl -d "$WSL_UBUNTU" -- redis-cli ping 2>/dev/null
```

If missing, guide the user through installation in WSL:
```bash
wsl -d "$WSL_UBUNTU" -- bash -c "sudo apt-get install -y tcl build-essential pkg-config libssl-dev"
wsl -d "$WSL_UBUNTU" -- bash -c "cd /tmp && wget https://download.redis.io/releases/redis-6.2.6.tar.gz && tar xvf redis-6.2.6.tar.gz && cd redis-6.2.6 && make && sudo make install"
wsl -d "$WSL_UBUNTU" -- bash -c "cd /tmp/redis-6.2.6/utils && sudo ./install_server.sh"
```

Verify: `wsl -d "$WSL_UBUNTU" -- redis-cli ping` should return `PONG`

#### 2e: PostgreSQL 15 (in WSL/Ubuntu)

```bash
# Check if PostgreSQL is running in WSL
wsl -d "$WSL_UBUNTU" -- psql --version 2>/dev/null
wsl -d "$WSL_UBUNTU" -- sudo -u postgres psql -c "SELECT version();" 2>/dev/null
```

If missing, guide installation in WSL:
```bash
wsl -d "$WSL_UBUNTU" -- bash -c "CODENAME=\$(lsb_release -cs) && sudo sh -c \"echo 'deb http://apt.postgresql.org/pub/repos/apt/ \${CODENAME}-pgdg main' > /etc/apt/sources.list.d/pgdg.list\""
wsl -d "$WSL_UBUNTU" -- bash -c "wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -"
wsl -d "$WSL_UBUNTU" -- bash -c "sudo apt update && sudo apt install -y postgresql-15"
wsl -d "$WSL_UBUNTU" -- bash -c "sudo systemctl start postgresql && sudo systemctl enable postgresql"
```

Then create the database:
```bash
wsl -d "$WSL_UBUNTU" -- sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres_admin_password';"
wsl -d "$WSL_UBUNTU" -- sudo -u postgres psql -c "CREATE DATABASE localv1db;"
```

#### 2f: Webpack (global)

```bash
npm list -g webpack 2>/dev/null || npm install --global webpack webpack-cli
```

### Step 3: Clone the Cloud Repo

The default clone location is `C:/Bigscreen/cloud`. Ask the user if they want a different location.

```bash
CLOUD_DIR="C:/Bigscreen/cloud"

if [ -d "$CLOUD_DIR/.git" ]; then
  echo "Cloud repo already exists at $CLOUD_DIR"
  cd "$CLOUD_DIR"
  git remote -v
else
  echo "Cloning cloud repo to $CLOUD_DIR..."
  mkdir -p "$(dirname "$CLOUD_DIR")"
  git clone https://github.com/BigscreenVR/cloud.git "$CLOUD_DIR"
  cd "$CLOUD_DIR"
fi
```

If the clone fails due to authentication, guide the user to set up GitHub credentials:
- `gh auth login` (if using GitHub CLI)
- Or set up an SSH key and use `git clone git@github.com:BigscreenVR/cloud.git`

### Step 4: Install Dependencies

```bash
cd "C:/Bigscreen/cloud"
yarn install
yarn workspace @bigscreen/lib install
yarn workspace @bigscreen/auth install
yarn workspace @bigscreen/api install
yarn workspace @bigscreen/cloud install
yarn workspace bigscreen_admin_api install
```

Also install dev deps:
```bash
yarn run install-dev-deps
```

### Step 5: Environment Files

**IMPORTANT**: Do not read, display, or log any `.env` file contents. These contain secrets.

The environment files are generated from the devops repo using the ServerEnvironmentBuilder:

1. Ask the user if they have the devops repo cloned. If not, ask them to clone it.
2. Ask the user if they have the server_keys directory with config files.
3. Guide them to run the env builder:

```bash
cd <devops-repo>/ServerEnvironmentBuilder
node app_v6.js \
    --default-config-file "<path-to>/server_keys/default_config.json" \
    --fleet-config-file "<path-to>/server_keys/dev/dev_config.json" \
    --allowed-apps-file "<path-to>/server_keys/dev/dev_allowed_apps.json" \
    --output-folder-path ./.out
```

4. Ask the user to copy the generated `.env` files to the appropriate service directories.
5. Remind them to add `REDIS_SERVER_HOST="127.0.0.1"` to each `.env` file.

The following services need `.env` files (based on the templates in devops):
- `apps/admin_api/.env` (from `admin_api.env.tpl`)
- `apps/api/.env` (from `api.env.tpl`)
- `cloud/cloud_api/.env` (from `cloud_api.env.tpl`)
- `cloud/ws_server/.env` (from `cloud_websocket_server.env.tpl`)
- `cloud/cloud_worker/.env` (from `cloud_worker.env.tpl`)
- `webapps/arda/.env` (from `webapp_arda.env.tpl`)

### Step 6: Verification

#### 6a: Start dev services

```bash
cd "C:/Bigscreen/cloud"
yarn dev
```

Check that all 7 services start without errors. Watch for:
- Port conflicts (3009, 3010, etc.)
- Redis connection failures (ensure WSL Redis is running)
- PostgreSQL connection failures (ensure WSL PostgreSQL is running)
- Missing environment variables

#### 6b: Run tests

```bash
cd "C:/Bigscreen/cloud"
ts-mocha --bail --exit --timeout=50000 tests/0*.ts
```

All tests should pass.

### Step 7: Summary

Report final status:

| Component | Status |
|-----------|--------|
| WSL/Ubuntu | Installed / Missing |
| Volta | Installed / Missing |
| Node.js v18 | Installed / Missing |
| Yarn | Installed / Missing |
| Python 3.10.11 | Installed / Missing |
| Redis 6.2.x | Running / Not running |
| PostgreSQL 15 | Running / Not running |
| Webpack | Installed / Missing |
| Cloud repo | Cloned / Not found |
| Dependencies | Installed / Missing |
| Env files | Present / Missing |
| yarn dev | Passes / Fails |
| Tests | Pass / Fail |

{{CONFIDENCE_CALIBRATION}}