# Slackzilla Setup Guide

This guide covers local development and production. Slackzilla contains a Slack bot, a dashboard/webhook server, and a React client built with Vite.

## Prerequisites

- Node.js and npm.
- A Slack app installed in a workspace.
- Git for deployment features.
- Linux, sudo, and systemd for production service files.
- An AI provider key only if the AI assistant is required.

## Create the Slack App

1. Open [Slack API Your Apps](https://api.slack.com/apps) and create a blank app in the target workspace.
2. Add a bot user and install the app.
3. Copy the Bot User OAuth Token (`xoxb-...`) as `SLACK_BOT_TOKEN`.
4. Create an app-level token with `connections:write` and set it as `SLACK_APP_TOKEN`.
5. Copy the app Signing Secret as `SLACK_SIGNING_SECRET`.
6. Add the scopes and slash commands required by `manifest.json` (or just copy whatever is in `manifest.json` into App Manifest > replace all existing content with it > Save Changes > Install App).

The bot uses Socket Mode, so it does not require a public inbound Slack HTTP endpoint.

## Environment Files

Copy `bot/.env.example` to `bot/.env` and set:

```bash
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
AI_API_KEY=...                 # optional
AI_MODEL=openai/gpt-6-luna
AI_URL=https://ai.hackclub.com/proxy/v1/chat/completions
```

Copy `server/.env.example` to `server/.env` and set:

```bash
WEBHOOK_SECRET=...
PORT=9000
PROJECT_DIR=/absolute/path/to/slackzilla
BRANCH=main
REPO_URL=https://github.com/your-user/slackzilla.git
ADMIN_PASSWORD_HASH=pbkdf2$sha512$600000$salt$derived-key
ADMIN_SESSION_SECRET=...
COOKIE_SECURE=false
```

The dashboard reads `bot/.env` for the bot token during local development. Keep secrets out of version control. `PROJECT_DIR` must exist; it is used for the webhook (CI/CD deployment)

## Generate an Admin Hash

Use the bot command, ask the ai assistant or use the dashboard to generate a hash for you:

```bash
/sz-hash pbkdf2 sha512 600000 your-password
```

Copy the returned `pbkdf2$...` value into `ADMIN_PASSWORD_HASH`. PBKDF2 is explained in [security.md](security.md).

## Local Development

Install dependencies:

```bash
npm ci
```

For React hot reload:

```bash
npm run dev
```

This serves the client at `http://localhost:5173`, but does not start the API, telemetry, logs, or bot.

For the complete local runtime:

```bash
npm start
```

This builds and lints the client, then starts the bot, the api, the RAG and dashboard server. The dashboard is available at `http://localhost:9000`. On Windows, Linux-only actions such as `systemctl` and Bash deployment are expected not to work.

## Dashboard Features

- `/` public dashboard.
- `/status` host, process, disk, network, and bot telemetry.
- `/commands` command reference and trusted command runner.
- `/ai` repository-aware question answering and related visual assets.
- `/api` HTTP endpoint reference.
- `/docs` in-app developer documentation.
- `/logs` bounded log viewer.
- `/admin/login` admin session flow.
- `/admin` authenticated controls and feedback management.

## AI Assistant

Set `AI_API_KEY` and restart the server to enable model answers. The assistant retrieves text outside `priv/`, ignores environment files and dependencies, and can return relevant images from `assets/attachments/`. It does not parse binary image contents.

The public API accepts:

```json
{
    "question": "How does the feedback API work?"
}
```

Command execution is explicit and should be treated as trusted functionality because commands may generate secrets, call external services, or mutate data.

### Calling RAG Tools Locally

The AI endpoint exposes a controlled tool set to the model. The model may request these tools while processing `POST /api/ask`:

```bashs
getStatus          current status without telemetryHistory
getCommands        available command metadata (with filters)
getReleaseInfo     current version and release-history changes
runCommand         allowlisted read-only utility command output
getLogs            latest 10 log entries
getErrors          latest 10 structured errors (stacks opt-in)
getMetrics         current runtime metrics
getRoutes          routes discovered by the RAG index
```

Start the dashboard server first, then send a normal AI request. The response is SSE, so use an SSE-capable client or `curl`:

For release questions, `getReleaseInfo` reads `package.json`, `release-history.json`, and the `/sz-release` implementation at `bot/cmds/release.js`. It is also available directly as `GET /api/release`, with an optional `?version=v0.9.5-beta` query parameter.

To test the repository pipeline without contacting an AI provider:

```bash
npm run rag -- "How does the /api/ask request flow work?" # this returns what the ai recieves
```
add `--ai` to see the AI's response.

To call tools directly, use `npm run rag:use-tool` with the tool name: e.g.

```bash
npm run rag:use-tool -- --getStatus
npm run rag:use-tool -- --getCommands
npm run rag:use-tool -- --getReleaseInfo
npm run rag:use-tool -- --getLogs
npm run rag:use-tool -- --getErrors
npm run rag:use-tool -- --getMetrics
npm run rag:use-tool -- --getRoutes
```

This direct adapter call still enforces the read-only allowlist, timeout, output-size limit, sanitisation, and activity events. See [RAG.md](RAG.md) for the complete data flow and security boundaries.

## Production Services

On Linux:

```bash
cp bot/.env.example bot/.env
cp server/.env.example server/.env
```

1. Run `npm ci` and configure both `.env` files.
2. Build with `npm run build`.
3. Copy `server/slackzilla.service` and `server/slackzilla-webhook.service` to `/etc/systemd/system/`.

```
cp server/slackzilla.service /etc/systemd/system/
cp server/slackzilla-webhook.service /etc/systemd/system/
```

4. Ensure service users, working directories, paths, and environment loading match the host.

```bash
sudo apt update
sudo systemctl daemon-reload
sudo systemctl enable --now slackzilla.service slackzilla-webhook.service
```

Restart after code or environment changes:

```bash
sudo systemctl restart slackzilla
sudo systemctl restart slackzilla-webhook
```

Use a reverse proxy for HTTPS and set `COOKIE_SECURE=true` when HTTPS is active.

Use an API client for JSON POST requests, authenticated APIs, CSRF headers, and webhook signatures.

## Troubleshooting

| Symptom                       | Check                                                                               |
| ----------------------------- | ----------------------------------------------------------------------------------- |
| Bot will not connect          | Slack tokens, signing secret, app scopes, and Socket Mode.                          |
| AI returns configuration text | `AI_API_KEY`, `AI_URL`, and `AI_MODEL`; restart after changes.                      |
| Admin login loops             | Password hash, session secret, cookie settings, and HTTPS/`COOKIE_SECURE`.          |
| Feedback reply fails          | Bot token must be available to the dashboard process and the user ID must be valid. |
| Disk is unavailable           | Confirm `PROJECT_DIR` exists and is readable.                                       |
| Webhook returns 401           | Compare `WEBHOOK_SECRET` and raw-body signature; see [webhook.md](webhook.md).      |
| Service action fails locally  | Control actions target Linux systemd hosts.                                         |
| Dashboard changes are missing | Rebuild and restart the dashboard service.                                          |

For implementation details read [api.md](api.md), [architecture.md](architecture.md), and [security.md](security.md).