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

🔌 TipTap extensions

Five open-source Tiptap extensions power the docs.plus editor. Each ships on npm under @docs.plus:

bun add @docs.plus/extension-hyperlink

Package	Description
extension-hyperlink	Hyperlink mark, autolink, popovers, URL safety
extension-hypermultimedia	Images, audio, video, and embeds (YouTube, Vimeo, SoundCloud, Loom, X)
extension-indent	Tab / Shift-Tab literal indent with context allowlist
extension-inline-code	Inline code mark (Mod-e, backtick rules)
extension-placeholder	O(1) cursor-based empty-node placeholder

Install notes, recommended pairings, and contributing: extensions/README.md. Release policy: RELEASE_POLICY.md.

Tech Stack:

• Runtime: 🚀 Bun 1.3.7+
• Frontend: ⚛️ Next.js 15/16, React 19, TipTap 3, Tailwind CSS 4
• Backend: 🔧 Hono, Hocuspocus (Y.js), BullMQ, 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.7 - 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 🚀

bun --filter @docs.plus/supabase_back start

First run downloads Docker images. Verify with bun --filter @docs.plus/supabase_back 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)

Backend Environment Variables:

# Supabase connection (for pgmq polling)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# VAPID keys for Web Push
VAPID_PUBLIC_KEY=your-vapid-public-key
VAPID_PRIVATE_KEY=your-vapid-private-key
VAPID_SUBJECT=mailto:support@yourdomain.com

Generate VAPID keys: npx web-push generate-vapid-keys

See docs/PUSH_NOTIFICATION_PGMQ.md for detailed architecture.

Step 5: Configure OAuth Redirect URLs 🔐

Go to Authentication → URL Configuration in Supabase Dashboard and add your Redirect URLs:

https://yourdomain.com
https://yourdomain.com/*
https://admin.yourdomain.com
https://admin.yourdomain.com/*

Replace yourdomain.com with your actual domain.

Step 6: Add Admin Users 👤

Only users in the admin_users table can access the admin dashboard. Run this SQL to grant access:

-- Add admin user by email
INSERT INTO public.admin_users (user_id, created_at)
SELECT id, now() FROM auth.users WHERE email = 'your-admin@example.com';

-- Verify admin users
SELECT u.email, a.created_at
FROM public.admin_users a
JOIN auth.users u ON a.user_id = u.id;

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 🗄️

bun --filter @docs.plus/supabase_back start

Step 3: Start Apps 💻

Option 3a: All in one command (recommended)

make dev-local

Option 3b: Separate terminals (better for debugging)

# Terminal 1 - Backend REST API
bun --filter @docs.plus/hocuspocus dev:rest

# Terminal 2 - Backend WebSocket
bun --filter @docs.plus/hocuspocus dev:ws

# Terminal 3 - Backend Worker
bun --filter @docs.plus/hocuspocus dev:worker

# Terminal 4 - Frontend
bun run dev

Or use convenience commands:

make dev-backend     # Start all backend services (REST + WS + worker)
bun run dev          # 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 via dotenv -e ../../.env.local -- (uniform across backend, frontend, and admin).
• 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 (2), Worker (2), Webapp (2)
• 🔀 Traefik v3 reverse proxy with automatic SSL (Let's Encrypt) and load balancing
• ⚡ Resource limits, health checks, and zero-downtime blue-green deploys
• 📊 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 dev-local         # Start all services (backend + frontend)
make dev-backend       # Start backend services (REST, WS, Worker)

# Frontend / Admin / Supabase (Bun, not Make)
bun run dev                                          # Webapp
bun run dev:admin                                    # Admin dashboard
bun --filter @docs.plus/supabase_back start          # Supabase
bun --filter @docs.plus/hocuspocus prisma:migrate    # Run DB migrations

# Management
make down              # Stop services (auto-detects env)
make logs              # All logs
make ps                # Container status
make clean             # ⚠️ Cleanup + delete volumes (DATA LOSS!)

Run make help for the complete Make surface; bun run (no args) for all root scripts.

📁 Project Structure

docs.plus/
├── apps/
│   ├── webapp/              # 🌐 Next.js frontend
│   ├── hocuspocus.server/   # ⚡ REST API, WebSocket, Workers
│   └── admin-dashboard/     # 🖥️ Admin panel
├── extensions/
│   └── extension-*/         # 🔌 Five publishable @docs.plus TipTap packages
├── packages/
│   └── supabase/            # 🗄️ Database migrations
├── 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.

First contribution? Start here:

• Pick an issue labeled good first issue or help wanted.
• Confirm your setup with bun run check before opening a PR.
• Use our issue and PR templates to speed up review.

🎨 Badges

Using docs.plus? Add a badge to your README and link back.

Variants

Style	Preview	File
Default		badge-docsplus.svg
Light		badge-docsplus-light.svg
Dark		badge-docsplus-dark.svg
Flat-square		badge-docsplus-flat-square.svg
For-the-badge		badge-docsplus-for-the-badge.svg

Usage

Markdown:

[![docs.plus](https://docs.plus/badges/badge-docsplus.svg)](https://docs.plus)

HTML — auto light/dark switching for GitHub READMEs:

<a href="https://docs.plus">
  <picture>
    <source
      media="(prefers-color-scheme: dark)"
      srcset="https://docs.plus/badges/badge-docsplus-dark.svg" />
    <img alt="docs.plus" height="20" src="https://docs.plus/badges/badge-docsplus.svg" />
  </picture>
</a>

Swap the filename for any variant in the table above.

📄 License

MIT License - See LICENSE

💬 Support

• 💬 Discord: Join our server
• 🐦 Twitter: @docsdotplus
• 🐙 GitHub: docs.plus
• 📧 Email: contact@newspeak.house

---