# Deployment Guide

## Hardware Requirements

- Raspberry Pi 5 (16GB RAM minimum)
- 256GB storage (microSD or NVMe)
- Raspberry Pi OS
- Always-on power and network connection

## Initial Setup

The Maxy installer handles the full setup. Run it on your Pi:

```bash
npx -y @rubytech/create-maxy
```

This installs all dependencies (Node.js, Neo4j, Cloudflare tunnel, Claude Code), configures the platform, and starts all services.

## What the Installer Does

1. Installs system dependencies
2. Installs Claude Code (the AI engine) and configures it
3. Installs and starts Neo4j (the memory database)
4. Installs and configures the Cloudflare tunnel for remote access
5. Creates your account and sets your PIN
6. Starts the Maxy web server on port 19200
7. Configures systemd so everything restarts automatically if the Pi reboots

## Service Management

Maxy runs via systemd and starts automatically on boot. You don't need to start it manually. To check if it's running, ask Maxy "Check system status."

If you need to restart the service manually (rare), ask Maxy to do it for you.

## Remote Access via Cloudflare

Maxy uses a Cloudflare tunnel to make your local Pi accessible from anywhere without opening router ports. The tunnel is configured during setup and runs as a background service.

Your public URL looks like: `https://your-name.maxy.chat` (or a custom domain you configure).

To check the tunnel status: ask Maxy "Check Cloudflare tunnel status."

To restart the tunnel: ask Maxy "Restart the Cloudflare tunnel."

## Checking Service Status

Ask Maxy: "Check system status."

The `system-status` tool reports the health of all services: Neo4j, the web server, the Cloudflare tunnel, and all active MCP servers.

## If Maxy Won't Start

From the Pi directly:

```bash
sudo systemctl status maxy
sudo journalctl -u maxy -n 50
```

The logs will show which service failed to start and why. Common causes:

- **Neo4j not started** — run `sudo systemctl start neo4j` and retry
- **Port 19200 already in use** — check for another process: `lsof -i :19200`
- **Claude OAuth expired** — the next admin session will prompt you to re-authenticate

## Upgrading

To upgrade Maxy to the latest version, ask Maxy: "Upgrade Maxy." The platform checks the current device identity (hostname and port via `system-status`), then re-runs the installer with explicit `--hostname` and `--port` flags to preserve them across the upgrade.

The docs plugin (this plugin) is upgraded in the same step — you always have the documentation that matches your installed version.

### Automatic upgrade alert

Maxy checks for new releases on every admin session start — whenever you log in, reload the page, or return to the admin chat. When a newer version is available, the Software Update window opens automatically showing your current and the latest version, with a one-click Upgrade button. Dismissing the window (click outside or the close button) defers the alert until your next login or reload; no alert is shown when you are already on the latest version.

The header menu's version indicator still reflects real-time status: a green dot means you are up to date, and an accent-coloured dot means an upgrade is available. Opening the menu refreshes the version check, so a long-lived session can still surface an upgrade that became available after login without reloading the page.
