x3
29c35f506d
- Add README with features, quick-start (local + Docker) and docs index - Add MIT LICENSE, root .gitignore and .env.example - Add docker-compose.yml (postgres + backend + frontend) - Add root package.json with install:all/dev helpers - Add Gitea CI workflow (backend syntax check, frontend build)
105 lines
3.7 KiB
Markdown
105 lines
3.7 KiB
Markdown
# openStack — Collaborative Workspace (Vue 3 + Express + PostgreSQL)
|
|
|
|
A Notion-like collaborative workspace: rich pages, nested hierarchy, workspaces with
|
|
role-based members, real-time collaboration (Socket.IO), comments, search, and
|
|
light/dark mode. Self-hostable via Node.js or Docker Compose.
|
|
|
|
> **Status:** Web app MVP (see [`docs/ROADMAP.md`](docs/ROADMAP.md) for desktop clients
|
|
> for Windows / macOS / Linux).
|
|
|
|
## Features
|
|
|
|
- **Auth** — Register / login with JWT (access token), bcrypt password hashing.
|
|
- **Workspaces** — Create workspaces, invite members by email (`owner` / `admin` /
|
|
`member` / `viewer`), change roles, remove members.
|
|
- **Pages** — Nested pages (`parent_id`), icon + cover, ordering, TipTap rich-text
|
|
content stored as JSON + rendered HTML.
|
|
- **Real-time collaboration** — Socket.IO rooms per page: live content broadcast,
|
|
presence (who is viewing), typing indicators.
|
|
- **Comments** — Threaded comments per page.
|
|
- **Search** — Full-text search (`ILIKE` on title/content, trigram-ready).
|
|
- **Light / dark mode** — CSS variables + persisted user preference.
|
|
- **Self-hostable** — Documented for bare-metal (`docs/HOSTING.md`) and Docker Compose.
|
|
|
|
## Monorepo layout
|
|
|
|
```text
|
|
openStack/
|
|
├── frontend/ # Vue 3 + Vite + Pinia + Vue Router + TipTap
|
|
├── backend/ # Express + Socket.IO + pg (PostgreSQL)
|
|
├── docs/ # SETUP, HOSTING, API, ARCHITECTURE, ROADMAP
|
|
├── docker-compose.yml # postgres + backend + frontend
|
|
├── .env.example # All required env vars
|
|
└── .gitea/workflows/ # CI (lint + build + test)
|
|
```
|
|
|
|
## Quick start (development)
|
|
|
|
Requirements: Node.js 20+, PostgreSQL 14+.
|
|
|
|
```bash
|
|
# 1. Clone
|
|
git clone https://git.sysdaemon.xyz/x3/openStack.git
|
|
cd openStack
|
|
|
|
# 2. Configure
|
|
cp .env.example .env
|
|
# edit .env -> DATABASE_URL, JWT_SECRET, ports
|
|
|
|
# 3. Database
|
|
createdb openstack
|
|
psql openstack < backend/src/db/schema.sql
|
|
|
|
# 4. Backend
|
|
cd backend && npm install && npm run dev
|
|
# -> http://localhost:3000 (API at /api, health at /api/health)
|
|
|
|
# 5. Frontend (new terminal)
|
|
cd frontend && npm install && npm run dev
|
|
# -> http://localhost:5173
|
|
```
|
|
|
|
Default dev flow creates the first user via **Register** in the UI; that user can then
|
|
create workspaces and invite others by email (invited email must have an account).
|
|
|
|
## Quick start (Docker Compose)
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# set POSTGRES_PASSWORD, JWT_SECRET, etc.
|
|
docker compose up --build
|
|
# frontend -> http://localhost:8080
|
|
# backend -> http://localhost:3000/api/health
|
|
```
|
|
|
|
See [`docs/HOSTING.md`](docs/HOSTING.md) for production (reverse proxy, TLS, backups).
|
|
|
|
## Documentation
|
|
|
|
| Doc | Content |
|
|
|-----|---------|
|
|
| [`docs/SETUP.md`](docs/SETUP.md) | Local dev setup, DB, env vars, troubleshooting |
|
|
| [`docs/HOSTING.md`](docs/HOSTING.md) | Bare-metal hosting + Docker Compose hosting |
|
|
| [`docs/API.md`](docs/API.md) | REST + Socket.IO contract with curl examples |
|
|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Data model, auth, realtime design |
|
|
| [`docs/ROADMAP.md`](docs/ROADMAP.md) | Webapp milestones + desktop clients (Win/Mac/Linux binaries via releases) |
|
|
|
|
## Scripts (root)
|
|
|
|
```bash
|
|
npm run install:all # install backend + frontend deps
|
|
npm run dev # runs backend+frontend concurrently (needs concurrently)
|
|
```
|
|
|
|
## Security notes
|
|
|
|
- Passwords hashed with bcrypt (12 rounds). Never stored in plain text.
|
|
- JWT access tokens (default 7d expiry, configurable). Sent as `Authorization: Bearer <token>`.
|
|
- Rate limiting on `/api/auth/*`. Helmet headers enabled. CORS allow-list via `CORS_ORIGIN`.
|
|
- Workspace access enforced server-side on every route (membership check + role check).
|
|
- Socket.IO authenticates via JWT in `auth.token` and re-checks page access on join.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|