📚 docs.plus

docs.plus is a free, real-time collaboration tool built on open-source technologies. It empowers communities to share and organize information logically and hierarchically, making teamwork and knowledge sharing straightforward and effective.

🏗️ Architecture

Monorepo Structure:

• 🌐 packages/webapp - Next.js frontend with TipTap editor
• ⚡ packages/hocuspocus.server - REST API, WebSocket server, and background workers
• 🗄️ packages/supabase - Database migrations and Supabase configuration
• 🔌 packages/extension-* - TipTap extensions (hyperlink, multimedia, indent, inline-code)

Tech Stack:

• Runtime: 🚀 Bun 1.3.2+
• Frontend: ⚛️ Next.js 15, React, TipTap, Tailwind CSS
• Backend: 🔧 Hono, Hocuspocus (Y.js), Prisma ORM
• Database: 🐘 PostgreSQL 17, 🔴 Redis
• Infrastructure: 🐳 Docker Compose, Supabase
• Real-time: 🔌 WebSocket (Hocuspocus), Supabase Realtime

📋 Prerequisites

• 🐳 Docker & Docker Compose v2+ - Install
  • ⚠️ macOS Silicon users: Docker Desktop has IO performance issues. Use OrbStack instead (drop-in replacement, faster, lighter).
• 🚀 Bun >=1.3.2 - Install
• 🗄️ Supabase CLI - Install

🚀 Quick Start

1️⃣ Clone & Install

git clone https://github.com/docs-plus/docs.plus.git
cd docs.plus
bun install

2️⃣ Environment Configuration

Create environment files based on your development mode:

# Required: Create .env.development first (used by Docker dev and as base for local dev)
cp .env.example .env.development

Environment File Mapping:

Docker Compose File	Environment File	Usage
docker-compose.prod.yml	.env.production	Production deployment
docker-compose.dev.yml	.env.development	Docker development (all services in containers)
docker-compose.local.yml	.env.local	Local development (infra in Docker, apps native)

Important Differences:

.env.development (Docker Development):

• Uses Docker service names for inter-container communication:
  • SERVER_RESTAPI_URL=http://rest-api:4000/api (Docker service name)
  • REDIS_HOST=redis (Docker service name)
  • DATABASE_URL is set by Docker Compose (not in file)

.env.local (Local Development):

• Uses localhost for native apps connecting to Docker infrastructure:
  • SERVER_RESTAPI_URL=http://localhost:4000/api (localhost)
  • REDIS_HOST=localhost (localhost)
  • DATABASE_URL=postgresql://...@localhost:5432/... (explicit connection string)
• Auto-created from .env.development when you run make dev-local or make infra-up
• Gitignored - safe for local customizations

Note: .env.local is automatically created from .env.development on first run. You only need to create .env.development manually.

3️⃣ Initialize Supabase

🗄️ Option A: Local Supabase Setup (One-time, ~5-10 min)

Step 1: Start Supabase 🚀

make supabase-start

First run downloads Docker images. Verify with make supabase-status.

Step 2: Activate Extensions 🔌

• Open Supabase Studio
• Go to Integrations
• Activate: pg_cron and pgmq (Queues)

Step 3: Run Migrations 📊

• Open SQL Editor
• Execute scripts from packages/supabase/scripts/ in order: 01-enum.sql through 17-database-extensions.sql

Step 4: Configure Queues ⚙️

• Queue Settings → Enable "Expose Queues via PostgREST"
• Queues → Select message_counter → Manage permissions
• Enable Select/Insert/Update/Delete for: authenticated, postgres, service_role
• Add RLS policy: "Allow anon and authenticated to access messages from queue"

☁️ Option B: Supabase Cloud Setup

If you prefer not to run Supabase locally, you can use a cloud project instead:

Step 1: Create Supabase Project 🚀

1. Go to Supabase Dashboard
2. Create a new project
3. Copy your project URL and anon key from Settings → API

Step 2: Update Environment Variables ⚙️ Update .env.development with your cloud project credentials:

# Server-side (containers → Supabase Cloud)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here

# Client-side (browser → Supabase Cloud)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_WS_URL=wss://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

Step 3: Configure Extensions & Migrations 📊 You still need to configure your cloud project:

• Activate pg_cron and pgmq (Queues) extensions in the Dashboard
• Run SQL scripts from packages/supabase/scripts/ in order via SQL Editor
• Configure queues and permissions (same as local setup)

Note: Make sure your Supabase project allows connections from your Docker network or configure network settings accordingly.

4️⃣ Start Development Environment

Choose one of three options:

🐳 Option A: Full Docker (Default)

All services run in Docker containers. Best for consistent environments.

⚠️ macOS Silicon users: Docker Desktop has slow IO performance (slow Next.js compile/hot reload). Use OrbStack instead for better performance.

make up-dev

Services: 🎯

• 🌐 Webapp: http://localhost:3000
• 🔌 REST API: http://localhost:4000
• ⚡ WebSocket: ws://localhost:4001
• 👷 Worker: http://localhost:4002
• 🐘 PostgreSQL: localhost:5432
• 🔴 Redis: localhost:6379
• 🗄️ Supabase Studio: http://127.0.0.1:54323

💻 Option B: Local Development (macOS-friendly, No Docker IO)

Best for macOS users - Avoids Docker volume IO performance issues. Only infrastructure (PostgreSQL, Redis) runs in Docker. Apps run natively with hot reload.

Step 1: Start Infrastructure 🚀

make infra-up

Step 2: Start Supabase 🗄️

make supabase-start

Step 3: Start Apps 💻

Option 3a: All in one command (recommended)

bun run dev:local

Option 3b: Separate terminals (better for debugging)

# Terminal 1 - Backend REST API
cd packages/hocuspocus.server && bun run dev:rest

# Terminal 2 - Backend WebSocket
cd packages/hocuspocus.server && bun run dev:hocuspocus.server

# Terminal 3 - Backend Worker
cd packages/hocuspocus.server && bun run dev:hocuspocus.worker

# Terminal 4 - Frontend
cd packages/webapp && bun run dev

Or use convenience scripts:

bun run dev:backend  # Start all backend services
bun run dev:webapp   # Start frontend only

Environment Variables:

• ✅ .env.local file at root - automatically created from .env.development on first run
• .env.development - Used by docker-compose.dev.yml (Docker service names: rest-api:4000, redis)
• .env.local - Used by docker-compose.local.yml and native apps (localhost addresses, gitignored)
• Scripts automatically load root .env.local:
  • Backend: Uses bun --env-file ../../.env.local
  • Frontend: Uses dotenv-cli to load root .env.local
• Key differences: .env.local uses localhost instead of Docker service names:
  • SERVER_RESTAPI_URL=http://localhost:4000/api (vs http://rest-api:4000/api in .env.development)
  • REDIS_HOST=localhost (vs redis in .env.development)
  • DATABASE_URL=postgresql://...@localhost:5432/... (explicit, vs set by Docker Compose in .env.development)
• See Step 2: Environment Configuration section above for complete details

Benefits:

• ✅ Native file system performance (no Docker volume overhead)
• ✅ Faster hot reload
• ✅ Better debugging experience
• ✅ Lower resource usage

Access points:

• 🌐 Webapp: http://localhost:3000
• 🔌 REST API: http://localhost:4000
• ⚡ WebSocket: ws://localhost:4001
• 👷 Worker: http://localhost:4002
• 🐘 PostgreSQL: localhost:5432
• 🔴 Redis: localhost:6379
• 🗄️ Supabase Studio: http://127.0.0.1:54323

Stop infrastructure:

make infra-down

🚀 Production Deployment

Production-ready setup for mid-level scale deployments (small-medium teams, moderate traffic).

Architecture: 🏗️

• 📈 Horizontal scaling: REST API (2), WebSocket (3), Worker (2), Webapp (2)
• 🔀 Nginx reverse proxy with load balancing
• ⚡ Resource limits and health checks
• 📊 Production-optimized logging and connection pooling

Setup

1. ⚙️ Configure Environment

   cp .env.example .env.production

   Important: .env.production is used by docker-compose.prod.yml for production deployment.

   Update: database credentials, JWT secret, Supabase URLs, storage credentials, CORS origins.

2. 🔨 Build & Deploy

   make build
   make up-prod

3. 📈 Scaling Adjust replicas in .env.production:

   REST_REPLICAS=2
   WS_REPLICAS=3
   WORKER_REPLICAS=2
   WEBAPP_REPLICAS=2

Production Recommendations: 💡

• 🗄️ Use managed database (AWS RDS, DigitalOcean, Supabase Cloud)
• 🔒 Configure SSL/TLS certificates
• 📊 Set up monitoring (Prometheus, Grafana)
• 💾 Implement database backups
• 🔐 Secure all secrets and credentials

📖 Command Reference

# Building
make build             # Production build
make build-dev         # Development build

# Running (Full Docker)
make up-prod           # Start production
make up-dev            # Start development (all in Docker)

# Running (Local Development - macOS-friendly)
make infra-up          # Start infrastructure only (postgres, redis)
make infra-down        # Stop infrastructure
make infra-logs        # View infrastructure logs
make dev-local         # Start all services (backend + frontend)
make dev-backend       # Start backend services (REST, WS, Worker)
make dev-webapp        # Start frontend only
make dev-rest          # Start REST API only
make dev-ws            # Start WebSocket server only
make dev-worker        # Start Worker only
make migrate           # Run database migrations

# Management
make down              # Stop services (auto-detects env)
make restart           # Restart services (auto-detects env)
make logs              # All logs
make logs-webapp       # Webapp logs
make logs-backend      # Backend logs
make ps                # Container status
make stats             # Resource usage
make clean             # ⚠️ Cleanup + delete volumes (DATA LOSS!)

# Scaling (production)
make scale-webapp      # Scale webapp to 3 replicas
make scale-hocuspocus  # Scale backend services

# Supabase (uses .env.local)
make supabase-start    # Start local Supabase
make supabase-stop     # Stop local Supabase
make supabase-status   # Show Supabase status

Run make help for complete command list.

📁 Project Structure

docs.plus/
├── packages/
│   ├── webapp/              # 🌐 Next.js frontend
│   ├── hocuspocus.server/   # ⚡ REST API, WebSocket, Workers
│   ├── supabase/            # 🗄️ Database migrations
│   └── extension-*/         # 🔌 TipTap extensions
├── docker-compose.dev.yml   # 🐳 Development orchestration
├── docker-compose.prod.yml  # 🚀 Production orchestration
├── Makefile                 # 🛠️ Build & deployment commands
└── .env.example             # ⚙️ Environment template

🤝 Contributing

PRs welcome! See contributing guidelines for details.

📄 License

MIT License - See LICENSE.md

💬 Support

• 💬 Discord: Join our server
• 🐦 Twitter: @docsdotplus
• 🐙 GitHub: docs.plus
• 📧 Email: [email protected]

---