jpmschweitzerandClaude Opus 4.7
a355751437
Clide is being rebuilt as a Flutter desktop app. The Python Textual implementation moves wholesale into legacy/ rather than being deleted: its pane model, panel set, git skills, and panel communication design are real thought that should remain readable next to the new code while the rebuild finds its shape. Git's rename tracking preserves history, so `git log -- legacy/` still works. The Flutter rebuild lives at the repo root alongside a Go sidecar (the architecture claudian was heading toward, which folds into clide as a core component rather than a separate plugin project). Bootstrap of the new shape lands in subsequent commits. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
174 lines
5.3 KiB
Markdown
174 lines
5.3 KiB
Markdown
# Web Deployment
|
|
|
|
Clide runs in a browser via a two-layer stack:
|
|
|
|
```
|
|
Browser (code.schweitz.net)
|
|
└─ clide-web (FastAPI + uvicorn, port 8888)
|
|
└─ tmux (session persistence)
|
|
└─ clide (Textual TUI)
|
|
└─ claude code (embedded PTY)
|
|
```
|
|
|
|
## Components
|
|
|
|
| Layer | Purpose | Config |
|
|
|-------|---------|--------|
|
|
| **clide-web** | FastAPI server: HTML page, WebSocket ↔ PTY bridge, REST API | systemd service on port 8888 |
|
|
| **tmux** | Session persistence (detach/reattach on browser disconnect) | Managed by clide-web |
|
|
| **clide** | TUI IDE wrapper around Claude Code | Spawned by tmux |
|
|
|
|
## Installation
|
|
|
|
From the clide project root:
|
|
|
|
```bash
|
|
sudo bash deploy/install-clide-web.sh
|
|
```
|
|
|
|
This:
|
|
1. Installs `clide-web` Python package into the clide venv
|
|
2. Installs `clide-web.service` systemd unit
|
|
3. Enables and starts the service
|
|
|
|
### First-Run Setup
|
|
|
|
After installing, run the setup wizard to configure projects directory and clide binary path:
|
|
|
|
```bash
|
|
clide-web-setup
|
|
```
|
|
|
|
Settings are stored in `~/.clide/clide.db` as UserPreference records.
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.12+ with clide venv set up (`make setup`)
|
|
- `tmux` installed (`sudo dnf install tmux` / `sudo apt install tmux`)
|
|
|
|
### Reverse Proxy
|
|
|
|
For external access, configure your reverse proxy (e.g., Nginx Proxy Manager) to:
|
|
- Proxy `code.schweitz.net` → `localhost:8888`
|
|
- Enable WebSocket support
|
|
|
|
## Architecture
|
|
|
|
### clide-web
|
|
|
|
FastAPI application serving:
|
|
- `GET /` — HTML page with xterm.js terminal + toolbar
|
|
- `GET /projects/{name}` — Project terminal page
|
|
- `WS /projects/{name}/ws` — WebSocket terminal bridge
|
|
- `GET /api/projects` — List available git repos
|
|
- `GET /api/sessions` — List active tmux sessions
|
|
- `GET /health` — Health check for reverse proxy
|
|
|
|
**WebSocket Protocol:**
|
|
|
|
| Prefix | Direction | Purpose |
|
|
|--------|-----------|---------|
|
|
| `0` | both | Terminal data |
|
|
| `1` | both | Control message (JSON) |
|
|
| `2` | client→server | Resize: `cols,rows` |
|
|
|
|
### tmux
|
|
|
|
Managed programmatically by clide-web. One session per project (`clide-<project>`).
|
|
|
|
- Browser disconnect → tmux session persists, reconnect shows current state
|
|
- Clide exit (Alt+Q) → `pane-died` hook auto-respawns a fresh Clide instance
|
|
- Status bar hidden for clide-web sessions only (user's other tmux sessions unaffected)
|
|
- Full environment inherited (HOME, PATH, etc.)
|
|
|
|
### Keybindings
|
|
|
|
All keys pass through directly to Clide — no intermediate layer captures keys.
|
|
No keybinding conflicts (unlike the previous Zellij-based setup).
|
|
|
|
### Database
|
|
|
|
SQLite database at `~/.clide/clide.db` shared between clide and clide-web.
|
|
Uses SQLModel (Pydantic-native ORM by FastAPI's creator).
|
|
|
|
Tables:
|
|
- **Project** — name, path, theme, last_accessed
|
|
- **Session** — tmux session name, status, last_activity
|
|
- **UserPreference** — key/value settings (projects_dir, clide_bin, port, etc.)
|
|
- **ConnectionLog** — client IP, connect/disconnect timestamps
|
|
|
|
## Configuration
|
|
|
|
Settings priority: environment variables > database preferences > defaults.
|
|
|
|
Environment variables (prefix `CLIDE_WEB_`):
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `CLIDE_WEB_HOST` | `0.0.0.0` | Server bind address |
|
|
| `CLIDE_WEB_PORT` | `8888` | Server port |
|
|
| `CLIDE_WEB_PROJECTS_DIR` | `/mnt/media/Projects` | Directory containing git repos |
|
|
| `CLIDE_WEB_CLIDE_BIN` | `clide` | Path to clide binary |
|
|
| `CLIDE_WEB_DB_PATH` | `~/.clide/clide.db` | SQLite database path |
|
|
|
|
## URL Patterns
|
|
|
|
- `code.schweitz.net` — auto-selects first project
|
|
- `code.schweitz.net/projects/clide` — opens/attaches to the clide project
|
|
|
|
The toolbar dropdown allows switching projects. URL updates via `history.pushState`.
|
|
|
|
## Operations
|
|
|
|
### Service Management
|
|
|
|
```bash
|
|
# Using make targets (from clide-web/ directory)
|
|
make start-server # Start the systemd service
|
|
make stop-server # Stop the systemd service
|
|
make restart-server # Restart the systemd service
|
|
make status-server # Show service status
|
|
make logs-server # Tail service logs
|
|
|
|
# Or directly with systemctl
|
|
systemctl status clide-web
|
|
sudo systemctl restart clide-web
|
|
journalctl -u clide-web -f
|
|
```
|
|
|
|
### Session Management
|
|
|
|
```bash
|
|
# List sessions
|
|
tmux list-sessions
|
|
|
|
# Kill a specific session
|
|
tmux kill-session -t clide-myproject
|
|
|
|
# Kill all clide sessions
|
|
tmux list-sessions | grep ^clide- | cut -d: -f1 | xargs -I{} tmux kill-session -t {}
|
|
```
|
|
|
|
## Files
|
|
|
|
```
|
|
clide-web/ # Python package
|
|
├── clide_web/
|
|
│ ├── server.py # FastAPI app, routes, WebSocket handler
|
|
│ ├── sessions.py # tmux session manager
|
|
│ ├── pty_bridge.py # PTY ↔ WebSocket bridge
|
|
│ ├── config.py # Pydantic settings with DB overlay
|
|
│ ├── setup_wizard.py # Interactive first-run configuration
|
|
│ └── static/
|
|
│ ├── index.html # HTML page (toolbar + xterm.js)
|
|
│ └── vendor/ # Vendored xterm.js (no CDN dependencies)
|
|
├── pyproject.toml
|
|
└── Makefile
|
|
deploy/
|
|
├── install-clide-web.sh # Installation script (run with sudo)
|
|
└── clide-web.service # systemd unit file
|
|
clide/
|
|
├── models/db.py # SQLModel table definitions (shared)
|
|
└── services/database.py # SQLite engine and session factory
|
|
```
|