x3
a407a1381a
- SETUP: local dev guide (env vars, DB migrate, backend/frontend, troubleshooting) - HOSTING: bare-metal guide (systemd + Nginx + TLS + backups) and Docker Compose guide (deploy, reverse proxy, updates, backup/restore) - API: REST contract with curl examples and Socket.IO event protocol - ARCHITECTURE: stack, data model, auth model, realtime design, theming - ROADMAP: webapp MVP/next steps plus Tauri desktop clients for Windows, macOS and Linux with release-binary plan
74 lines
2.1 KiB
Markdown
74 lines
2.1 KiB
Markdown
# Setup (Development)
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+
|
|
- PostgreSQL 14+ (local or remote)
|
|
- npm 10+
|
|
|
|
## 1. Clone & configure
|
|
|
|
```bash
|
|
git clone https://git.sysdaemon.xyz/x3/openStack.git
|
|
cd openStack
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env`:
|
|
|
|
| Variable | Purpose | Example |
|
|
|----------|---------|---------|
|
|
| `DATABASE_URL` | Backend Postgres connection | `postgres://openstack:openstackpw@localhost:5432/openstack` |
|
|
| `JWT_SECRET` | Signing key for auth tokens (min 32 random chars) | `openssl rand -hex 32` |
|
|
| `JWT_EXPIRES_IN` | Token lifetime | `7d` |
|
|
| `CORS_ORIGIN` | Allowed frontend origin(s), comma-separated | `http://localhost:5173` |
|
|
| `VITE_API_URL` | Frontend -> backend base URL | `http://localhost:3000/api` |
|
|
| `VITE_SOCKET_URL` | Frontend -> Socket.IO URL | `http://localhost:3000` |
|
|
| `PORT` | Backend listen port | `3000` |
|
|
|
|
## 2. Database
|
|
|
|
```bash
|
|
createdb openstack
|
|
psql "$DATABASE_URL" < backend/src/db/schema.sql
|
|
# or: cd backend && npm install && npm run migrate
|
|
```
|
|
|
|
Verify:
|
|
|
|
```bash
|
|
psql "$DATABASE_URL" -c "SELECT * FROM users LIMIT 1;"
|
|
```
|
|
|
|
## 3. Backend
|
|
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
npm run dev # watch mode on http://localhost:3000
|
|
curl http://localhost:3000/api/health # -> {"ok":true,"db":"up"}
|
|
```
|
|
|
|
## 4. Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # http://localhost:5173
|
|
```
|
|
|
|
Open the frontend, **Register** the first user, create a workspace, invite teammates
|
|
by email (they must register with the same email first).
|
|
|
|
## Troubleshooting
|
|
|
|
- `DATABASE_URL is not set` — you forgot `.env` or didn't export it. Backend reads
|
|
`backend/.env` too if you copy `.env` there, otherwise set env in shell.
|
|
- `db: down` on `/api/health` — Postgres unreachable; check `DATABASE_URL`,
|
|
firewall, `pg_isready`.
|
|
- CORS errors — `CORS_ORIGIN` must exactly match the frontend origin (scheme+host+port).
|
|
- Socket.IO `Invalid token` — log out/in again; token may have expired.
|
|
- `relation "users" does not exist` — schema not applied; run migrate step.
|
|
- Postgres.app on macOS hangs on `psql -h localhost` — use the socket
|
|
(`psql -h /tmp`) or set a password and use TCP; see HOSTING notes.
|