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

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.