RootIB: RB-20260320004840-3C7A9F12

# 🖥️ Local Backend Launcher — How-To Guide

**Step-by-step instructions for deploying the Barbrick Design backend on your local machine**

> This guide corresponds to the **Local Backend Launcher** panel in `dashboard.html`
> (`https://barbrickdesign.github.io/dashboard.html → Settings → 🖥️ Local Backend Launcher`).

---

## Prerequisites

| Requirement | Minimum Version | Download |
|---|---|---|
| Node.js | 18 LTS | https://nodejs.org/ |
| Git (optional) | any | https://git-scm.com/ |
| npm | bundled with Node | — |

Verify your installation:
```bash
node --version   # should print v18.x or higher
npm --version    # should print 9.x or higher
```

---

## Step 1 — Get the Repository

**Option A — Git clone (recommended)**
```bash
git clone https://github.com/barbrickdesign/barbrickdesign.github.io.git
cd barbrickdesign.github.io
```

**Option B — Download ZIP**
1. Go to `https://github.com/barbrickdesign/barbrickdesign.github.io`
2. Click **Code → Download ZIP**
3. Extract the ZIP, then open a terminal in the extracted folder.

---

## Step 2 — Install Backend Dependencies

```bash
cd backend
npm install
```

This installs Express, `ws`, and all other dependencies listed in `backend/package.json`.

---

## Step 3 — (Optional) Configure Environment Variables

Copy the example environment file and fill in your API keys:

```bash
cp .env.example .env
# Then open .env in any text editor and set the values you need
```

Minimum required for full functionality:
```
GATEWAY_TOKEN=your-secret-token   # Protects the WebSocket gateway
```

> **Tip:** Leave `GATEWAY_TOKEN` empty and the gateway will accept all connections from localhost.

---

## Step 4 — Start the Backend Server

From inside the `backend/` directory:
```bash
node server-main.js
```

Or from the **repo root** using the npm script:
```bash
npm start
```

You should see output like:
```
✅ Barbrick Design backend listening on port 8080
WebSocket gateway ready — connect at ws://localhost:8080
```

---

## Step 5 — Connect the Dashboard

1. Open `https://barbrickdesign.github.io/dashboard.html` in your browser.
2. Click **⚙️ Settings** in the left sidebar.
3. Find the **🖥️ Local Backend Launcher** panel.
4. Click **⚡ Connect to Local Backend**.

The dashboard will:
- Ping `http://localhost:8080/health` to verify the server is running.
- Switch its WebSocket connection from Railway to `ws://localhost:8080`.
- Show a green dot (●) in the sidebar next to **Local Backend**.

---

## Optional — Auto-Start with Health Monitoring

For hands-free operation with automatic restarts:

```bash
# From the repo root:
node backend-auto-start.js
```

`backend-auto-start.js` monitors the backend every 10 seconds and restarts it
if it crashes (up to 5 retries by default).

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `❌ Not reachable` in the dashboard | Make sure `node server-main.js` is running and shows port 8080 |
| `EADDRINUSE: port 8080` | Another process is using port 8080. Stop it or change `PORT` in `backend/server-main.js` |
| CORS errors in the browser console | Access the dashboard via `https://` (GitHub Pages), not a plain `file://` URL |
| `MODULE_NOT_FOUND` on start | Run `npm install` inside the `backend/` folder |
| Backend crashes immediately | Check `.env` — a missing required key can cause a startup error |

---

## Commercial Distribution

For the commercial platform distro, see:
- `QUICKSTART.md` — quick 2-minute setup for end users
- `SETUP_WIZARD.py` — interactive first-run wizard (auto-configures `.env`, GitHub login, API keys)

---

## Support

📧 BarbrickDesign@gmail.com  
🌐 https://barbrickdesign.github.io  
🐛 https://github.com/barbrickdesign/barbrickdesign.github.io/issues