# Setup Guide

## Prerequisites

Before running the installer, verify your environment meets these requirements.

| Requirement | Minimum Version | Notes |
|-------------|----------------|-------|
| macOS | 13 Ventura | Required for launchd integration |
| Node.js | 22.0.0 | Installer will offer to install via Homebrew |
| Python | 3.12 | Some tools depend on it |
| Homebrew | any | Installed automatically if missing |
| PM2 | any | Installed globally by the installer |
| Claude Code CLI | any | `claude` must be on PATH |
| SQLite3 | 3.x | Usually pre-installed on macOS |
| Git | 2.x | Usually pre-installed on macOS |

You also need:
- An **Anthropic API key** from [console.anthropic.com](https://console.anthropic.com)
- A **Google Cloud project** with the Calendar API enabled (only if installing the calendar module)

## Step-by-Step Installation

### 1. Clone the Repository

```bash
git clone <repo-url> teletraan-framework
cd teletraan-framework
```

### 2. Run the Installer

```bash
./install.sh
```

The installer opens an interactive wizard. If you prefer an AI-guided experience:

```bash
./install.sh --agent
```

### 3. Enter Your System Name

The wizard asks for a short name for your system (e.g. `homelab`, `myserver`). This is used in PM2 service names and log labels.

### 4. Choose an Install Path

Default: `~/teletraan`. The installer copies service files here. You can use any writable directory.

### 5. Provide Your Anthropic API Key

Paste your API key when prompted. It is saved to `config/system.json` and injected into the conductor agent's environment.

### 6. Select Modules

The installer lists available modules with their descriptions and dependencies:

```
Available modules:
  [1] notifications  — in-app notification store (no dependencies)
  [2] calendar       — Google Calendar sync (requires: notifications)
  [3] status         — host/service/site monitoring (requires: notifications)
  [4] telegram-bridge — Telegram ↔ conductor routing (no dependencies)

Select modules to install (comma-separated numbers, or Enter to skip):
```

If you select `calendar`, the installer automatically includes `notifications`.

### 7. Module-Specific Configuration

For each selected module, the installer runs its interactive setup:

**notifications** — no configuration required.

**calendar** — prompts for:
- Path to your Google OAuth credentials JSON file
- Path to your Google token JSON file (can be generated; see Google OAuth Setup below)

**status** — prompts for:
- Hosts to monitor (hostname, SSH user, optional key path)
- Network targets to ping
- Services to check (name, host, port)
- Sites to monitor (URL, expected status code)

**telegram-bridge** — prompts for:
- Telegram bot token (from @BotFather)
- Authorized Telegram user IDs
- Channel server URL and secret

### 8. Installation Completes

The installer:
1. Copies each module to `<installPath>/services/<name>/`
2. Runs `npm install && npm run build` for each module
3. Generates a PM2 ecosystem config at `<installPath>/ecosystem.config.js`
4. Starts all services with `pm2 start`
5. Configures PM2 to auto-start on login with `pm2 startup`
6. Runs health checks on each service port
7. Prints a summary

### 9. Verify Installation

```bash
pm2 list
```

All services should show status `online`. You can also run:

```bash
./scripts/health-check.sh
```

## Google OAuth Setup

The calendar module and the web dashboard both use Google OAuth. Follow these steps to create credentials.

### Create a Google Cloud Project

1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Click **New Project**, name it (e.g. `Teletraan`), and click **Create**
3. Select your new project from the project dropdown

### Enable Required APIs

1. In the left menu, go to **APIs & Services > Library**
2. Search for and enable:
   - **Google Calendar API**
   - (for dashboard login) No additional API needed — OAuth is built in

### Create OAuth Credentials

1. Go to **APIs & Services > Credentials**
2. Click **+ Create Credentials > OAuth client ID**
3. Application type: **Web application**
4. Name: `Teletraan`
5. Authorized redirect URIs: add `http://localhost:3006/api/auth/callback/google`
6. Click **Create**
7. Download the JSON file — this is your `credentials.json`

### Configure the Consent Screen

1. Go to **APIs & Services > OAuth consent screen**
2. User type: **External** (or Internal if using Google Workspace)
3. Fill in App name, support email, developer contact
4. Add scopes: `openid`, `email`, `profile`, `https://www.googleapis.com/auth/calendar`
5. Add your email as a test user

### Generate an Initial Token (calendar module)

Run this helper once to authorize the calendar module:

```bash
node -e "
const {google} = require('googleapis');
const fs = require('fs');
const creds = JSON.parse(fs.readFileSync('credentials.json'));
const {client_id, client_secret, redirect_uris} = creds.installed || creds.web;
const auth = new google.auth.OAuth2(client_id, client_secret, redirect_uris[0]);
const url = auth.generateAuthUrl({access_type:'offline', scope:['https://www.googleapis.com/auth/calendar']});
console.log('Open this URL:', url);
"
```

Open the URL, authorize, copy the `code` from the redirect URL, then exchange it:

```bash
node -e "
const {google} = require('googleapis');
const fs = require('fs');
const creds = JSON.parse(fs.readFileSync('credentials.json'));
const {client_id, client_secret, redirect_uris} = creds.installed || creds.web;
const auth = new google.auth.OAuth2(client_id, client_secret, redirect_uris[0]);
auth.getToken('PASTE_CODE_HERE').then(({tokens}) => {
  fs.writeFileSync('token.json', JSON.stringify(tokens, null, 2));
  console.log('Token saved to token.json');
});
"
```

Provide the paths to `credentials.json` and `token.json` when the installer prompts you.

## First Login to the Dashboard

1. Open `http://localhost:3006` in your browser
2. Click **Sign in with Google**
3. Complete the Google OAuth consent flow
4. You are redirected back to the dashboard

The dashboard connects to the channel server at `localhost:7100` automatically.

## Verifying Everything Works

```bash
# Check all PM2 processes
pm2 list

# Run the health check script
./scripts/health-check.sh

# View conductor agent logs
pm2 logs conductor

# Test the channel server directly
curl http://localhost:7100/health
```

Expected output from the health check:

```
[PASS] channel-server  :7100
[PASS] notifications   :8087
[PASS] calendar        :8084
[PASS] status          :8086
Overall: 4/4 services healthy
```

## Common First-Time Issues

**`claude: command not found`**
Claude Code CLI is not on your PATH. Install it and ensure `~/.local/bin` or wherever it lives is in your shell's PATH.

**`PM2 not found`**
Run `npm install -g pm2` and re-run the installer, or run `./install.sh` again — it will detect and install PM2.

**Calendar module fails health check**
The Google token is missing or expired. Re-run the calendar module setup:

```bash
./scripts/add-module.sh calendar
```

**Port already in use**
Another process is on one of Teletraan's ports. Find it with `lsof -i :<port>` and stop it, or edit `config/system.json` to use different ports (requires re-running the installer).

**Permission denied on install.sh**
```bash
chmod +x install.sh
```
