openStack/README.md

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 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) in workspaces or books, icon + cover, ordering, TipTap rich-text with tables + checklists, stored as JSON + HTML.
• Books 📚 — Independent containers for pages, collapsible in the sidebar.
• Tasks ✅ — Kanban (todo/doing/doing→done), priorities, deadlines, assignees, links to books/pages, per-team boards.
• Teams 👥 — Teams with managers/members, own workspaces (TEAM_"name" badge), permission groups (e.g. Team Creators: teams.create/edit/invite, workspace.invite).
• Invites + notifications 🔔 — Pending invites with accept/decline, bell with unread badge (polling + realtime push), notifications for invites and chat messages.
• Team chat 💬 — Realtime workspace channel via Socket.IO.
• Uploads 📤 — Avatar/background images uploadable (served from /uploads).
• Calendar 🗓️ — Deadlines from tasks appear automatically.
• Time tracking ⏱️ — Top-right timer, entries linkable to books, history list.
• Settings window ⚙️ — Profile (name, email, avatar, password), appearance (light/dark/system), language (Deutsch, English, 中文), background image + blur.
• Admin dashboard 🛡️ — Stats, user management (admin flag, delete).
• User discovery 🔎 — Fuzzy search to find and invite collaborators.
• 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

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+.

# 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

Open the frontend: on first start a web installer guides you through creating the admin account and your first workspace. Afterwards the team registers via the UI and joins workspaces by email invite (invited email must have an account).

Quick start (Docker Compose)

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 for production (reverse proxy, TLS, backups).

Documentation

Doc	Content
docs/SETUP.md	Local dev setup, DB, env vars, troubleshooting
docs/HOSTING.md	Bare-metal hosting + Docker Compose hosting
docs/API.md	REST + Socket.IO contract with curl examples
docs/ARCHITECTURE.md	Data model, auth, realtime design
docs/ROADMAP.md	Webapp milestones + desktop clients (Win/Mac/Linux binaries via releases)

Scripts (root)

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.