Private
Public Access
ksmithandClaude Sonnet 5
7f579bb508
Deployment artifacts for the two-server architecture from ARCHITECTURE.md §9, grounded in verified Debian 13 (trixie) package facts (Python 3.13, PostgreSQL 17, Node.js 20, redis-server 8.0, certbot 4.0, ufw -- confirmed rather than guessed) rather than a generic "modern Linux" guide: deploy/systemd/chatapp.service, deploy/chatapp.env.example, deploy/backup-postgres.sh, deploy/upgrade.sh, and DEPLOYMENT.md as the actual numbered runbook. Revised mid-implementation once the user clarified the app sits behind an existing, separate Nginx Proxy Manager rather than local Nginx+certbot: dropped the local Nginx config entirely, gunicorn now binds a TCP port instead of a Unix socket, and app/main.py gained a static-file mount + SPA fallback route so gunicorn alone serves the built frontend, /api, and /ws on one port -- what lets NPM's simple one-upstream-per-domain mode work with zero custom path routing. Path-traversal-guarded (full_path comes straight from the URL) and cache-header-differentiated (far-future immutable on Vite's content-hashed assets, no-cache on index.html/sw.js/ manifest so a deploy actually propagates instead of leaving clients on a stale service worker) -- verified locally against a real gunicorn process serving a real frontend build, not just eyeballed. Two real gaps found and fixed alongside the docs, not just noted: gunicorn wasn't a dependency anywhere despite being the whole app-server design, and there was no WebSocket reconnect logic on the client -- a reverse proxy's idle-connection timeout (NPM's or otherwise) would have silently killed a quiet chat connection with nothing to recover it. Added exponential-backoff reconnect to useChatSocket.ts, verified by hand (killed and restarted the local dev backend mid-session, confirmed auto-reconnect and that a message sends successfully afterward with no page reload). Every command in DEPLOYMENT.md that could be verified locally, was: the exact systemd ExecStart line run against local dev Postgres/Redis with clean SIGTERM shutdown, the static-file serving behavior against a real build, both shell scripts syntax-checked. What couldn't be verified from this sandbox (actual Debian 13 hardware, Nginx Proxy Manager itself) is flagged explicitly in the plan rather than claimed. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
56 lines
2.1 KiB
Markdown
56 lines
2.1 KiB
Markdown
# KeepItTalking
|
|
|
|
A web-based team chat service (Mattermost-style, no threaded conversations),
|
|
invite-only. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system design
|
|
and phased build plan.
|
|
|
|
**Phase 1**: auth, open-room CRUD, and single-instance WebSocket chat, backend
|
|
+ a minimal frontend. **Phase 2**: private rooms, room roles (owner/admin/
|
|
member), and room invites — backend only, see below. Later phases (push
|
|
notifications, Redis fan-out, the admin portal, the bot/extension system, and
|
|
production deployment) are tracked as issues in the repo's issue tracker,
|
|
prioritized.
|
|
|
|
## Structure
|
|
|
|
- [`backend/`](backend/) — FastAPI + SQLAlchemy 2.0 (async) + PostgreSQL. See
|
|
[`backend/README.md`](backend/README.md) for local setup, migrations, how to
|
|
create a user (site registration is invite-only — no public sign-up
|
|
endpoint), and the Phase 2 room-roles/invites API.
|
|
- [`frontend/`](frontend/) — React + Vite PWA (login, room list, chat view).
|
|
Still Phase-1-only: it doesn't yet call any of the Phase 2 endpoints. A UI
|
|
redesign is happening separately; frontend work resumes once that lands.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
# 1. Postgres (see backend/README.md for details)
|
|
docker run -d --name chatapp-postgres \
|
|
-e POSTGRES_USER=chatapp -e POSTGRES_PASSWORD=chatapp -e POSTGRES_DB=chatapp \
|
|
-p 5432:5432 postgres:16-alpine
|
|
|
|
# 2. Backend
|
|
cd backend
|
|
python3 -m venv .venv
|
|
.venv/bin/pip install -e ".[dev]"
|
|
cp .env.example .env # then set SESSION_SECRET
|
|
.venv/bin/alembic upgrade head
|
|
.venv/bin/python -m app.cli create-user alice alice@example.com "some-password"
|
|
.venv/bin/uvicorn app.main:app --reload &
|
|
|
|
# 3. Frontend (in another shell)
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Then open http://localhost:5173 and log in with the account created above.
|
|
The Vite dev server proxies `/api` and `/ws` to the backend on `:8000`, so no
|
|
CORS configuration is needed in development.
|
|
|
|
## Deployment
|
|
|
|
See [DEPLOYMENT.md](DEPLOYMENT.md) for the full production runbook — two
|
|
Debian 13 servers, no containers, matching
|
|
[ARCHITECTURE.md §9](ARCHITECTURE.md#9-deployment-architecture--two-linux-servers-no-docker).
|