swadhin / opencodehub public

docs: rewrite README to be concise and professional

JustAPI Bot committed 3 months ago

6ecf049

1 parent 5fa5633

commit 6ecf049

1 file changed

+62 -433

Files

README.md +62 -433

Showing 1 changed file+62-422

README.md

▼README.md

+62-422

@@ -4,506 +4,135 @@
4	4	<picture>
5	5	<source media="(prefers-color-scheme: dark)" srcset="public/logo-dark.png">
6	6	<source media="(prefers-color-scheme: light)" srcset="public/logo-light.png">
7		- <img src="public/logo-light.png" alt="OpenCodeHub Logo" width="420" />
	7	+ <img src="public/logo-light.png" alt="OpenCodeHub" width="380" />
8	8	</picture>
9	9	</p>
10	10
11		-<p align="center">
12		- <strong>A modern, self-hosted Git platform for teams that want speed, control, and clean workflows.</strong>
13		-</p>
14		-
15	11	<p align="center">
16	12	<a href="https://www.npmjs.com/package/opencodehub-cli"><img src="https://img.shields.io/npm/v/opencodehub-cli?style=flat-square&label=CLI" alt="CLI version"></a>
17	13	<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
18		- <a href="docs/index.md"><img src="https://img.shields.io/badge/docs-available-success?style=flat-square" alt="Docs"></a>
19	14	<a href="https://github.com/swadhinbiswas/OpencodeHub/actions"><img src="https://img.shields.io/badge/CI-passing-success?style=flat-square" alt="CI"></a>
20	15	</p>
21	16
22		-
23		-## Table of Contents
24		-
25		-- [Why OpenCodeHub](#why-opencodehub)
26		-- [Features](#features)
27		-- [Quick Start](#quick-start)
28		-- [Architecture](#architecture)
29		-- [Documentation](#documentation)
30		-- [CLI](#cli)
31		-- [API](#api)
32		-- [Security](#security)
33		-- [Deployment](#deployment)
34		-- [Contributing](#contributing)
35		-- [License](#license)
36		-
37		-
38		-## Why OpenCodeHub
39		-
40		-Most teams eventually hit the same pain points:
41		-
42		-- PRs are too large to review quickly — Stacked PRs let you break changes into reviewable pieces
43		-- Tooling is split across many services — One platform for Git, PRs, CI/CD, issues, and wiki
44		-- Data residency and security requirements — Self-hosted by default, you control everything
45		-- Merge queue complexity — Stack-aware merge queue with speculative builds
46		-- Slow review cycles — AI-powered code review catches issues before human review
47		-
48		-OpenCodeHub is built for that reality.
49		-
50		-
51		-## Features
52		-
53		-### Core Platform
54		-
55		-\| Feature \| Status \| Description \|
56		-\|---------\|--------\|-------------\|
57		-\| Git Hosting \| Ready \| HTTP (Smart Protocol) + SSH git push/pull \|
58		-\| Pull Requests \| Ready \| Comments, reviews, drafts, approvals, suggested changes \|
59		-\| Issues \| Ready \| Labels, milestones, project boards \|
60		-\| Wiki \| Ready \| Repository wiki with revision history \|
61		-\| Organizations \| Ready \| Teams, collaborators, repository settings \|
62		-\| Branch Protection \| Ready \| Required reviews, status checks, push restrictions \|
63		-
64		-### Delivery Workflows
65		-
66		-\| Feature \| Status \| Description \|
67		-\|---------\|--------\|-------------\|
68		-\| Stacked PRs \| Ready \| Graphite-style stack workflows in web + CLI \|
69		-\| Merge Queue \| Ready \| Stack-aware queue with speculative builds and priority lanes \|
70		-\| CI/CD Pipelines \| Ready \| GitHub Actions-compatible engine + Docker-based runner \|
71		-\| Webhooks \| Ready \| Outbound webhooks with event filtering \|
72		-\| Automations \| Ready \| Workflow automation rules \|
73		-
74		-### Security & Governance
75		-
76		-\| Feature \| Status \| Description \|
77		-\|---------\|--------\|-------------\|
78		-\| Authentication \| Ready \| JWT sessions, OAuth (GitHub, Google, GitLab), 2FA/TOTP \|
79		-\| Authorization \| Ready \| RBAC with roles, team permissions, collaborator levels \|
80		-\| Rate Limiting \| Ready \| Redis-backed per-endpoint rate limiting \|
81		-\| CSRF Protection \| Ready \| Double-submit cookie pattern \|
82		-\| Secret Scanning \| Ready \| Detect secrets in commits \|
83		-\| Audit Logging \| Ready \| Track all administrative actions \|
84		-
85		-### Extensibility
86		-
87		-\| Feature \| Status \| Description \|
88		-\|---------\|--------\|-------------\|
89		-\| REST API \| Ready \| 140+ API routes \|
90		-\| GraphQL \| Ready \| Full GraphQL endpoint \|
91		-\| OpenAPI \| Ready \| Auto-generated OpenAPI spec \|
92		-\| CLI \| Ready \| 20+ command groups (`opencodehub-cli`) \|
93		-\| Storage Adapters \| Ready \| 8+ backends (S3, GCS, Azure, Google Drive, etc.) \|
	17	+Self-hosted Git platform with stacked PRs, merge queue, CI/CD, and AI code review. Built for teams that want speed and control.
94	18
95	19	---
96	20
97	21	## Quick Start
98	22
99		-### Prerequisites
100		-
101		-- Node.js >= 20
102		-- npm or bun
103		-- git
104		-- PostgreSQL 14+ (recommended) or SQLite (dev)
105		-
106		-### Docker (Fastest)
107		-
108	23	```bash
109		-# 1. Clone
110	24	git clone https://github.com/swadhinbiswas/OpencodeHub.git
111	25	cd OpenCodeHub
112		-
113		-# 2. Configure
114	26	cp .env.example .env
115		-# Edit .env with your settings
116		-
117		-# 3. Start
118		-docker-compose up -d
119		-
120		-# 4. Create admin user
121		-docker-compose exec app bun run scripts/seed-admin.ts
122		-
123		-# 5. Open
124		-open http://localhost:4321
	27	+docker compose up -d
	28	+docker compose exec app bun run scripts/seed-admin.ts
125	29	```
126	30
127		-### NAS & Edge Deployment (Cloudflare / Tailscale)
128		-
129		-Deploying on a home server or NAS? Use the provided `docker-compose.nas.yml` which includes `cloudflared` and `tailscale` configurations for seamless zero-trust exposure without port forwarding.
130		-
131		-```bash
132		-# Expose via Cloudflare Tunnel
133		-TUNNEL_TOKEN=your_token docker-compose -f docker-compose.nas.yml --profile cloudflare up -d
134		-
135		-# OR Expose via Tailscale
136		-TS_AUTHKEY=your_key docker-compose -f docker-compose.nas.yml --profile tailscale up -d
137		-```
138		-See the [NAS Deployment Guide](docs/administration/deploy-nas.md) and [Exposing NAS Guide](docs/administration/expose-nas.md) for full details.
139		-
140		-
141		-### Manual Setup
142		-
143		-```bash
144		-# 1. Install dependencies
145		-npm install
146		-
147		-# 2. Configure environment
148		-cp .env.example .env
149		-# Edit .env (SQLite defaults work for dev)
150		-
151		-# 3. Initialize database
152		-npm run db:push
153		-
154		-# 4. Create admin user
155		-bun run scripts/seed-admin.ts
156		-
157		-# 5. Start development server
158		-npm run dev
159		-```
160		-
161		-App URL: `http://localhost:3000` (dev) or `http://localhost:4321` (Docker)
162		-
163		-
164		-## Architecture
165		-
166		-```
167		-Clients (Browser / Git CLI / och CLI)
168		- \|
169		- v
170		-OpenCodeHub Platform (Astro SSR + React)
171		- \|-- Web UI
172		- \|-- REST API (140+ routes)
173		- \|-- GraphQL Endpoint
174		- \|-- Git HTTP Server
175		- \|-- SSH Git Server (port 2222)
176		- \|
177		- v
178		-Persistence Layer
179		- \|-- PostgreSQL / SQLite / Turso (Drizzle ORM)
180		- \|-- Redis (sessions, queues, caching)
181		- \|-- Pluggable Storage (S3, GCS, Azure, local, etc.)
182		-```
183		-
184		-### Runtime Processes
185		-
186		-\| Process \| Command \| Purpose \|
187		-\|---------\|---------\|---------\|
188		-\| Main App \| `npm run dev` \| Web UI + API + Git HTTP \|
189		-\| SSH Git \| `npm run git:start` \| SSH git push/pull \|
190		-\| Worker \| `npm run worker:start` \| Background jobs \|
191		-\| Runner \| `npm run runner:start` \| CI/CD pipeline execution \|
192		-
193		-### Tech Stack
194		-
195		-\| Layer \| Technology \|
196		-\|-------\|-----------\|
197		-\| Framework \| Astro 4.x (SSR, Node standalone) \|
198		-\| UI \| React 18 + Tailwind CSS + Radix UI \|
199		-\| Database \| Drizzle ORM (PostgreSQL, SQLite, Turso) \|
200		-\| Auth \| JWT (jose) + bcryptjs + TOTP (otplib) + OAuth (arctic) \|
201		-\| Git \| Native git CLI + simple-git + isomorphic-git \|
202		-\| SSH \| ssh2 library \|
203		-\| CI/CD \| Dockerode (Docker API) \|
204		-\| Storage \| Abstract adapter pattern (8+ backends) \|
205		-\| Queue \| BullMQ + Redis \|
206		-\| CLI \| Commander.js + Inquirer + simple-git \|
207		-
208		-
209		-## Documentation
210		-
211		-Comprehensive documentation is available in the `docs/` directory:
212		-
213		-- [Getting Started](docs/getting-started/installation.md) — Installation and setup
214		-- [Features](docs/features/) — Stacked PRs, AI review, merge queue, CI/CD
215		-- [Guides](docs/guides/) — Team workflows, branch protection, webhooks
216		-- [API Reference](docs/api/rest-api.md) — REST API documentation
217		-- [Administration](docs/administration/) — Deployment, security, monitoring
218		-- [Development](docs/development/) — Architecture, contributing, testing
219		-- [Tutorials](docs/tutorials/) — Hands-on guides
220		-
221		-
222		-## CLI
223		-
224		-The companion CLI is published as `opencodehub-cli`:
225		-
226		-```bash
227		-# Install
228		-npm install -g opencodehub-cli
229		-
230		-# Authenticate
231		-och auth login --url http://localhost:4321
232		-
233		-# Stack workflow
234		-och stack create feature/auth-step-1
235		-och stack submit
236		-och stack sync
237		-
238		-# Merge queue
239		-och queue list
240		-och queue add <pr-number>
241		-
242		-# Interactive cockpit
243		-och focus
244		-```
	31	+Open `http://localhost:4321` and create your admin account.
245	32
246		-[Full CLI Reference](docs/reference/cli-commands.md)
	33	+Requirements: Docker, or Node.js 20+ with PostgreSQL.
247	34
248	35	---
249	36
250		-## API
	37	+## What It Does
251	38
252		-OpenCodeHub provides multiple API interfaces:
	39	+Git Hosting — HTTP smart protocol + SSH push/pull. Forks, mirroring, LFS, wiki.
253	40
254		-### REST API
	41	+Stacked PRs — Break large changes into dependent branches. Each PR builds on the previous. Review in order, merge in order.
255	42
256		-140+ REST endpoints covering all platform features:
	43	+Merge Queue — Stack-aware merge ordering with speculative CI builds. `main` never breaks.
257	44
258		-```bash
259		-# Authentication
260		-curl -X POST http://localhost:4321/api/auth/login \
261		- -H "Content-Type: application/json" \
262		- -d '{"login":"alice","password":"secret"}'
263		-
264		-# Create repository
265		-curl -X POST http://localhost:4321/api/repos \
266		- -H "Authorization: Bearer <token>" \
267		- -H "Content-Type: application/json" \
268		- -d '{"name":"my-project","visibility":"public"}'
269		-
270		-# List pull requests
271		-curl http://localhost:4321/api/repos/alice/my-project/pulls \
272		- -H "Authorization: Bearer <token>"
273		-```
	45	+CI/CD — GitHub Actions-compatible workflows. Docker-based runners. Artifacts, secrets, matrix builds.
274	46
275		-### GraphQL
	47	+AI Code Review — GPT-4, Claude, Gemini, Groq, Ollama, and 5+ more providers. Catches bugs, security issues, and style problems automatically.
276	48
277		-```bash
278		-curl -X POST http://localhost:4321/api/graphql \
279		- -H "Authorization: Bearer <token>" \
280		- -H "Content-Type: application/json" \
281		- -d '{"query": "{ repositories { name owner { username } } }"}'
282		-```
	49	+Issues & Projects — Labels, milestones, custom fields, kanban boards.
283	50
284		-### OpenAPI Spec
	51	+175+ API Endpoints — REST + GraphQL. Full programmatic access to everything.
285	52
286		-The OpenAPI spec is available at:
287		-```
288		-GET /api/openapi.json
289		-```
	53	+CLI — `och` command line tool for stack workflows, reviews, and repository management.
290	54
291	55	---
292	56
293		-## Security
	57	+## Deploy
294	58
295		-OpenCodeHub implements comprehensive security controls:
296		-
297		-- Authentication: JWT sessions with secure cookies, OAuth 2.0, 2FA/TOTP
298		-- Authorization: Role-based access control (RBAC), repository permissions, team permissions
299		-- Data Protection: AES-256-GCM encryption for workflow secrets and AI config
300		-- Transport: HTTPS enforcement in production, TLS 1.2+
301		-- CSRF: Double-submit cookie pattern for state-changing requests
302		-- Rate Limiting: Redis-backed per-endpoint rate limiting
303		-- Input Validation: Zod schema validation on all API inputs
304		-- Secret Scanning: Detect and block secrets in commits
305		-- SSRF Protection: Validate webhook URLs against private IP ranges
306		-
307		-See [Security Best Practices](docs/administration/security.md) for detailed configuration.
308		-
309		-
310		-## Deployment
311		-
312		-### Docker Compose (Recommended)
313		-
314		-The included `docker-compose.yml` spins up:
315		-- OpenCodeHub app (port 4321)
316		-- PostgreSQL database
317		-- Redis cache
318		-- CI runner (Docker-in-Docker)
319		-- Optional: MinIO for S3-compatible storage
	59	+### Docker (Recommended)
320	60
321	61	```bash
322		-docker-compose up -d
	62	+git clone https://github.com/swadhinbiswas/OpencodeHub.git
	63	+cd OpenCodeHub
	64	+cp .env.example .env
	65	+docker compose up -d
	66	+docker compose exec app bun run scripts/seed-admin.ts
323	67	```
324	68
325		-### Production Checklist
	69	+### Render (Free)
326	70
327		-Before deploying to production:
	71	+See [Render Deployment Guide](docs/RENDER-DEPLOYMENT.md). Uses free PostgreSQL + Upstash Redis.
328	72
329		-1. Change ALL secrets:
330		- ```bash
331		- JWT_SECRET=$(openssl rand -hex 32)
332		- SESSION_SECRET=$(openssl rand -hex 32)
333		- INTERNAL_HOOK_SECRET=$(openssl rand -hex 32)
334		- CRON_SECRET=$(openssl rand -hex 32)
335		- RUNNER_SECRET=$(openssl rand -hex 32)
336		- WORKFLOW_SECRET_ENCRYPTION_KEY=$(openssl rand -hex 32)
337		- ```
	73	+### Other Options
338	74
339		-2. Use PostgreSQL (not SQLite)
340		-3. Configure HTTPS with reverse proxy (Nginx/Caddy)
341		-4. Set up Redis for distributed sessions and rate limiting
342		-5. Configure external storage (S3/GCS/Azure instead of local)
343		-6. Enable rate limiting: `RATE_LIMIT_ENABLED=true`
344		-7. Set up SMTP for email notifications
345		-8. Configure backups for PostgreSQL data
346		-
347		-See [Deployment Guide](docs/administration/deployment.md) for detailed instructions.
	75	+\| Platform \| Guide \|
	76	+\|----------\|-------\|
	77	+\| Docker Compose \| [Deployment Guide](docs/administration/deployment.md) \|
	78	+\| NAS (Synology/TrueNAS) \| [NAS Guide](docs/administration/deploy-nas.md) \|
	79	+\| Kubernetes \| [K8s Guide](docs/administration/kubernetes.md) \|
	80	+\| Cloudflare Tunnel \| [Cloudflare Guide](docs/administration/deploy-cloudflare.md) \|
	81	+\| Free Tier Options \| [Free Deployment](docs/FREE-DEPLOYMENT.md) \|
348	82
349	83	---
350	84
351		-## Database
352		-
353		-OpenCodeHub uses Drizzle ORM with support for multiple database engines:
	85	+## Tech Stack
354	86
355		-\| Engine \| Driver \| Use Case \|
356		-\|--------\|--------\|----------\|
357		-\| PostgreSQL \| `pg` \| Production (recommended) \|
358		-\| SQLite \| `better-sqlite3` \| Development, small deployments \|
359		-\| Turso/LibSQL \| `@libsql/client` \| Edge deployments, Vercel \|
360		-
361		-```bash
362		-# Generate migrations
363		-npm run db:generate
364		-
365		-# Apply migrations
366		-npm run db:migrate
367		-
368		-# Push schema (dev)
369		-npm run db:push
370		-
371		-# Open Drizzle Studio
372		-npm run db:studio
373		-```
	87	+\| Layer \| Tech \|
	88	+\|-------\|------\|
	89	+\| Framework \| Astro 4.x SSR + React 18 \|
	90	+\| Database \| PostgreSQL, SQLite, Turso (Drizzle ORM) \|
	91	+\| Auth \| JWT, OAuth, 2FA/TOTP, SSO/SAML \|
	92	+\| CI/CD \| Docker-based runners, GitHub Actions syntax \|
	93	+\| Storage \| Local, S3, MinIO, R2, or any S3-compatible \|
	94	+\| CLI \| Commander.js (`npm i -g opencodehub-cli`) \|
374	95
375	96	---
376	97
377		-## Storage
378		-
379		-All blob storage goes through an abstract `StorageAdapter`:
	98	+## Documentation
380	99
381		-\| Backend \| Adapter \| Use Case \|
382		-\|---------\|---------\|----------\|
383		-\| Local \| `LocalStorageAdapter` \| Development, single-node \|
384		-\| S3 \| `S3StorageAdapter` \| Production (AWS, MinIO, R2) \|
385		-\| Google Cloud \| `GCSStorageAdapter` \| GCP deployments \|
386		-\| Azure Blob \| `AzureStorageAdapter` \| Azure deployments \|
387		-\| Google Drive \| `GoogleDriveStorageAdapter` \| Personal/small team \|
388		-\| OneDrive \| `OneDriveStorageAdapter` \| Microsoft ecosystem \|
389		-\| Dropbox \| `DropboxStorageAdapter` \| Simple cloud storage \|
390		-\| Rclone \| `RcloneStorageAdapter` \| Any rclone-compatible remote \|
	100	+Full docs at [docs.opencodehub.space](https://docs.opencodehub.space/):
391	101
392		-Configure via `STORAGE_DRIVER` environment variable.
	102	+- [Installation](https://docs.opencodehub.space/getting-started/installation/)
	103	+- [Configuration](https://docs.opencodehub.space/administration/configuration/)
	104	+- [Stacked PRs](https://docs.opencodehub.space/features/stacked-prs/)
	105	+- [AI Code Review](https://docs.opencodehub.space/features/ai-review/)
	106	+- [CLI Reference](https://docs.opencodehub.space/reference/cli-commands/)
	107	+- [API Reference](https://docs.opencodehub.space/api/rest-api/)
393	108
394	109	---
395	110
396		-## Development
	111	+## CLI
397	112
398	113	```bash
399		-# Setup
400		-cp .env.example .env
401		-npm install
402		-npm run db:push
403		-bun run scripts/seed-admin.ts
404		-
405		-# Dev server
406		-npm run dev # Web UI + API (port 3000)
407		-npm run git:start # SSH git server (port 2222)
408		-npm run worker:start # Background worker
409		-npm run runner:start # CI runner
410		-
411		-# Quality
412		-npm run lint
413		-npm run typecheck
414		-npm run test
415		-npm run test:coverage
416		-
417		-# Database
418		-npm run db:generate
419		-npm run db:migrate
420		-npm run db:push
421		-npm run db:studio
422		-```
423		-
424		-See [Contributing Guide](CONTRIBUTING.md) and [Development Docs](docs/development/).
425		-
426		-
427		-## Project Structure
428		-
429		-```
430		-OpenCodeHub/
431		-├── src/ # Main application
432		-│ ├── pages/ # Astro routes (UI + API)
433		-│ ├── lib/ # Core business logic (120+ modules)
434		-│ ├── db/ # Database schema and connection
435		-│ ├── components/ # React components
436		-│ ├── middleware.ts # Global middleware
437		-│ └── runner/ # CI runner
438		-├── cli/ # CLI package (opencodehub-cli)
439		-│ └── src/commands/ # CLI command groups
440		-├── packages/ # Additional packages
441		-│ ├── git-rpc-daemon/
442		-│ ├── merge-queue-daemon/
443		-│ ├── ci-runner/
444		-│ └── sdk/
445		-├── docs/ # Documentation
446		-├── docs-site/ # Documentation website
447		-├── scripts/ # Utility scripts
448		-├── docker-compose.yml # Docker Compose setup
449		-├── Dockerfile # Main app container
450		-└── package.json
451		-```
452		-
453		-
454		-## Testing
455		-
456		-- Unit Tests: Vitest (`*.test.ts`)
457		-- E2E Tests: Playwright
458		-- Load Tests: Custom load tests in `tests/load/`
459		-- Accessibility: `@axe-core/playwright`
	114	+npm install -g opencodehub-cli
460	115
461		-```bash
462		-npm run test # Run all tests
463		-npm run test:coverage # Run with coverage
	116	+och auth login --url http://localhost:4321
	117	+och stack create feature/auth
	118	+och stack submit
	119	+och focus
464	120	```
465	121
466	122	---
467	123
468	124	## Contributing
469	125
470		-Contributions are welcome!
471		-
472		-1. Fork the repository
473		-2. Create a feature branch
474		-3. Run lint and tests
475		-4. Open a pull request
	126	+1. Fork the repo
	127	+2. Create a branch
	128	+3. `npm install && npm run db:push && npm run dev`
	129	+4. Run tests: `npm run test`
	130	+5. Open a PR
476	131
477		-See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow and standards.
478		-
479		-
480		-## Community
481		-
482		-- Documentation: [docs/index.md](docs/index.md)
483		-- Issues: [GitHub Issues](https://github.com/swadhinbiswas/OpencodeHub/issues)
484		-- Discussions: [GitHub Discussions](https://github.com/swadhinbiswas/OpencodeHub/discussions)
	132	+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
485	133
486	134	---
487	135
488	136	## License
489	137
490		-MIT. See [LICENSE](LICENSE).
491		-
492		-
493		-<p align="center">
494		- <strong>Ready to get started?</strong><br>
495		- <a href="docs/getting-started/installation.md">Install OpenCodeHub</a> \|
496		- <a href="docs/getting-started/quick-start.md">Quick Start</a> \|
497		- <a href="docs/features/stacked-prs.md">Learn Stacked PRs</a>
498		-</p>
	138	+MIT
499	139