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), 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

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

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)

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.