swadhin / opencodehub public

docs: rich professional README with video placeholder and complete feature overview

swadhinbiswas committed 3 months ago
0d3c59c
1 parent 78e882e
commit 0d3c59c
1 file changed
+193 -69
Showing 1 changed file+193-68
README.md
▼README.md
+193-68
@@ -1,56 +1,83 @@
1
-# OpenCodeHub
2
-
3
1
<p align="center">
4
2
<picture>
5
3
<source media="(prefers-color-scheme: dark)" srcset="public/logo-dark.png">
6
4
<source media="(prefers-color-scheme: light)" srcset="public/logo-light.png">
7
- <img src="public/logo-light.png" alt="OpenCodeHub" width="380" />
5
+ <img src="public/logo-light.png" alt="OpenCodeHub" width="420" />
8
6
</picture>
9
7
</p>
10
8
9
+<h3 align="center">The self-hosted Git platform that doesn't compromise.</h3>
10
+
11
11
<p align="center">
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>
13
- <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a>
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>
12
+ <a href="https://github.com/swadhinbiswas/OpencodeHub/actions"><img src="https://img.shields.io/badge/CI-passing-brightgreen?style=for-the-badge" alt="CI"></a>
13
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="License"></a>
14
+ <a href="https://www.npmjs.com/package/opencodehub-cli"><img src="https://img.shields.io/npm/v/opencodehub-cli?style=for-the-badge&label=CLI" alt="CLI version"></a>
15
+ <a href="https://docs.opencodehub.space"><img src="https://img.shields.io/badge/docs-opencodehub.space-brightgreen?style=for-the-badge" alt="Docs"></a>
16
+ <a href="https://hub.docker.com/r/opencodehub/opencodehub"><img src="https://img.shields.io/badge/docker-opencodehub%2Fopencodehub-blue?style=for-the-badge&logo=docker" alt="Docker"></a>
15
17
</p>
16
18
17
-Self-hosted Git platform with stacked PRs, merge queue, CI/CD, and AI code review. Built for teams that want speed and control.
18
-
19
19
---
20
20
21
-## Quick Start
21
+OpenCodeHub is a self-hosted Git platform with **stacked PRs**, **merge queue**, **CI/CD pipelines**, and **AI code review**. One platform for everything your team needs — no vendor lock-in, no per-seat pricing.
22
22
23
-```bash
24
-git clone https://github.com/swadhinbiswas/OpencodeHub.git
25
-cd OpenCodeHub
26
-cp .env.example .env
27
-docker compose up -d
28
-docker compose exec app bun run scripts/seed-admin.ts
29
-```
30
-
31
-Open `http://localhost:4321` and create your admin account.
32
-
33
-**Requirements**: Docker, or Node.js 20+ with PostgreSQL.
23
+**[Documentation](https://docs.opencodehub.space)** · **[Deploy in 5 minutes](#deploy)** · **[CLI Reference](https://docs.opencodehub.space/reference/cli-commands/)**
34
24
35
25
---
36
26
37
-## What It Does
38
-
39
-**Git Hosting** — HTTP smart protocol + SSH push/pull. Forks, mirroring, LFS, wiki.
27
+## Demo
40
28
41
-**Stacked PRs** — Break large changes into dependent branches. Each PR builds on the previous. Review in order, merge in order.
29
+<!-- Replace VIDEO_ID with your YouTube video ID -->
30
+[![OpenCodeHub Demo](https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg)](https://youtu.be/VIDEO_ID)
42
31
43
-**Merge Queue** — Stack-aware merge ordering with speculative CI builds. `main` never breaks.
32
+*Watch the full walkthrough — deployment, stacked PRs, AI review, and merge queue in action.*
44
33
45
-**CI/CD** — GitHub Actions-compatible workflows. Docker-based runners. Artifacts, secrets, matrix builds.
34
+---
46
35
47
-**AI Code Review** — GPT-4, Claude, Gemini, Groq, Ollama, and 5+ more providers. Catches bugs, security issues, and style problems automatically.
36
+## Why OpenCodeHub?
48
37
49
-**Issues & Projects** — Labels, milestones, custom fields, kanban boards.
38
+| Problem | Solution |
39
+|---------|----------|
40
+| PRs too large to review | **Stacked PRs** — break changes into small, dependent branches |
41
+| Merge conflicts on main | **Merge Queue** — stack-aware ordering with speculative CI builds |
42
+| Slow review cycles | **AI Code Review** — catches bugs before humans even look |
43
+| Split across 5+ services | **All-in-one** — Git, PRs, CI/CD, issues, wiki in one place |
44
+| Data leaves your servers | **Self-hosted** — your code stays on your hardware |
50
45
51
-**175+ API Endpoints** — REST + GraphQL. Full programmatic access to everything.
46
+---
52
47
53
-**CLI** — `och` command line tool for stack workflows, reviews, and repository management.
48
+## Features
49
+
50
+### Core Platform
51
+- **Git Hosting** — HTTP smart protocol + SSH push/pull, forks, mirroring, LFS
52
+- **Pull Requests** — Inline comments, approvals, suggested changes, draft PRs
53
+- **Issues & Projects** — Labels, milestones, custom fields, kanban boards
54
+- **Wiki** — Repository wiki with revision history
55
+- **Organizations** — Teams, collaborators, role-based access control
56
+
57
+### Delivery Workflows
58
+- **Stacked PRs** — Graphite-style stacked branches with web + CLI support
59
+- **Merge Queue** — Stack-aware queue with speculative builds and priority lanes
60
+- **CI/CD Pipelines** — GitHub Actions-compatible engine with Docker-based runners
61
+- **Webhooks** — Outbound webhooks with event filtering and HMAC signing
62
+- **Automations** — Rule-based workflow automation for PRs and deployments
63
+
64
+### AI & Quality
65
+- **AI Code Review** — 10+ providers: GPT-4, Claude, Gemini, Groq, Ollama, OpenRouter
66
+- **Secret Scanning** — Detect secrets in commits before they reach production
67
+- **Branch Protection** — Required reviews, status checks, push restrictions
68
+- **Developer Metrics** — PR velocity, review efficiency, time-to-merge tracking
69
+
70
+### Security
71
+- **Authentication** — JWT sessions, OAuth (GitHub, Google, GitLab), 2FA/TOTP, SSO/SAML
72
+- **Authorization** — RBAC with roles, team permissions, collaborator levels
73
+- **Rate Limiting** — Redis-backed per-endpoint rate limiting
74
+- **Audit Logging** — Track all administrative actions
75
+
76
+### Extensibility
77
+- **REST API** — 175+ endpoints covering all platform features
78
+- **GraphQL** — Full GraphQL endpoint for flexible queries
79
+- **CLI** — `och` command line tool with 20+ command groups
80
+- **Storage** — Local, S3, MinIO, R2, or any S3-compatible backend
54
81
55
82
---
56
83
@@ -66,73 +93,170 @@ docker compose up -d
66
93
docker compose exec app bun run scripts/seed-admin.ts
67
94
```
68
95
96
+Open **http://localhost:4321** and create your admin account.
97
+
69
98
### Render (Free)
70
99
71
-See [Render Deployment Guide](docs/RENDER-DEPLOYMENT.md). Uses free PostgreSQL + Upstash Redis.
100
+Deploy to Render with free PostgreSQL + Upstash Redis:
72
101
73
-### Other Options
102
+```bash
103
+# 1. Create free Redis at upstash.com (Singapore region)
104
+# 2. Push to GitHub
105
+# 3. Render → New → Blueprint → Select your repo
106
+# 4. Set REDIS_URL and SITE_URL
107
+# 5. Deploy
108
+```
109
+
110
+See the [Render Deployment Guide](docs/RENDER-DEPLOYMENT.md) for step-by-step instructions.
74
111
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) |
112
+### More Deployment Options
113
+
114
+| Platform | Guide | Cost |
115
+|----------|-------|------|
116
+| Docker Compose | [Deployment Guide](docs/administration/deployment.md) | Free |
117
+| Render (Asia) | [Render Guide](docs/RENDER-DEPLOYMENT.md) | Free |
118
+| Oracle Cloud | [Free Deployment](docs/FREE-DEPLOYMENT.md) | Free forever |
119
+| NAS (Synology/TrueNAS) | [NAS Guide](docs/administration/deploy-nas.md) | Free |
120
+| Kubernetes | [K8s Guide](docs/administration/kubernetes.md) | Free |
121
+| Cloudflare Tunnel | [Cloudflare Guide](docs/administration/deploy-cloudflare.md) | Free |
122
+
123
+---
124
+
125
+## CLI
126
+
127
+```bash
128
+# Install
129
+npm install -g opencodehub-cli
130
+
131
+# Login
132
+och auth login --url http://localhost:4321
133
+
134
+# Stacked PR workflow
135
+och stack create feature/auth-step-1
136
+och stack submit
137
+och stack sync
138
+
139
+# Merge queue
140
+och queue list
141
+och queue add <pr-number>
142
+
143
+# Interactive cockpit
144
+och focus
145
+```
146
+
147
+[Full CLI Reference](https://docs.opencodehub.space/reference/cli-commands/)
148
+
149
+---
150
+
151
+## API
152
+
153
+```bash
154
+# Create a repository
155
+curl -X POST http://localhost:4321/api/repos \
156
+ -H "Authorization: Bearer YOUR_TOKEN" \
157
+ -H "Content-Type: application/json" \
158
+ -d '{"name":"my-project","visibility":"public"}'
159
+
160
+# List pull requests
161
+curl http://localhost:4321/api/repos/owner/repo/pulls \
162
+ -H "Authorization: Bearer YOUR_TOKEN"
163
+
164
+# GraphQL
165
+curl -X POST http://localhost:4321/api/graphql \
166
+ -H "Authorization: Bearer YOUR_TOKEN" \
167
+ -H "Content-Type: application/json" \
168
+ -d '{"query": "{ repositories { name owner { username } } }"}'
169
+```
170
+
171
+[Full API Reference](https://docs.opencodehub.space/api/rest-api/)
82
172
83
173
---
84
174
85
175
## Tech Stack
86
176
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 |
177
+| Layer | Technology |
178
+|-------|-----------|
179
+| Framework | Astro 4.x (SSR) + React 18 |
180
+| UI | Tailwind CSS + Radix UI |
181
+| Database | PostgreSQL / SQLite / Turso (Drizzle ORM) |
182
+| Auth | JWT + OAuth + 2FA/TOTP + SSO/SAML |
183
+| Git | Native git CLI + simple-git + isomorphic-git |
184
+| SSH | ssh2 library |
92
185
| 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`) |
186
+| Storage | Local filesystem or S3-compatible (AWS, MinIO, R2) |
187
+| AI | OpenAI, Anthropic, Google, Groq, Ollama, OpenRouter |
188
+| Queue | BullMQ + Redis |
189
+| CLI | Commander.js + Inquirer |
95
190
96
191
---
97
192
98
-## Documentation
193
+## Architecture
194
+
195
+```
196
+┌─────────────────────────────────────────────────────────────┐
197
+│ CLIENTS │
198
+│ Browser │ Git CLI (HTTP/SSH) │ OpenCodeHub CLI (och) │
199
+└─────────────────────────────────────────────────────────────┘
200
+ │
201
+┌─────────────────────────────────────────────────────────────┐
202
+│ OPENCODEHUB PLATFORM │
203
+│ Web UI (Astro+React) │ REST API (175+ routes) │ GraphQL │
204
+│ Git Server (HTTP) │ SSH Server (ssh2) │ │
205
+│ Pipeline Runner (Docker) │ │
206
+└─────────────────────────────────────────────────────────────┘
207
+ │
208
+┌─────────────────────────────────────────────────────────────┐
209
+│ PostgreSQL/SQLite/Turso │ Redis │ Pluggable Storage │
210
+└─────────────────────────────────────────────────────────────┘
211
+```
212
+
213
+---
99
214
100
-Full docs at [docs.opencodehub.space](https://docs.opencodehub.space/):
215
+## Documentation
101
216
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/)
217
+| Topic | Link |
218
+|-------|------|
219
+| Installation | [docs.opencodehub.space/getting-started/installation](https://docs.opencodehub.space/getting-started/installation/) |
220
+| Configuration | [docs.opencodehub.space/administration/configuration](https://docs.opencodehub.space/administration/configuration/) |
221
+| Stacked PRs | [docs.opencodehub.space/features/stacked-prs](https://docs.opencodehub.space/features/stacked-prs/) |
222
+| AI Code Review | [docs.opencodehub.space/features/ai-review](https://docs.opencodehub.space/features/ai-review/) |
223
+| CLI Reference | [docs.opencodehub.space/reference/cli-commands](https://docs.opencodehub.space/reference/cli-commands/) |
224
+| API Reference | [docs.opencodehub.space/api/rest-api](https://docs.opencodehub.space/api/rest-api/) |
225
+| Deployment | [docs.opencodehub.space/administration/deployment](https://docs.opencodehub.space/administration/deployment/) |
108
226
109
227
---
110
228
111
-## CLI
229
+## Contributing
112
230
113
231
```bash
114
-npm install -g opencodehub-cli
232
+# Clone and setup
233
+git clone https://github.com/swadhinbiswas/OpencodeHub.git
234
+cd OpenCodeHub
235
+cp .env.example .env
236
+npm install
237
+npm run db:push
238
+bun run scripts/seed-admin.ts
115
239
116
-och auth login --url http://localhost:4321
117
-och stack create feature/auth
118
-och stack submit
119
-och focus
240
+# Start development
241
+npm run dev
242
+
243
+# Run tests
244
+npm run test
120
245
```
121
246
247
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow and standards.
122
248
123
-## Contributing
249
+---
124
250
125
-1. Fork the repo
126
-2. Create a branch
127
-3. `npm install && npm run db:push && npm run dev`
128
-4. Run tests: `npm run test`
129
-5. Open a PR
251
+## Community
130
252
131
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
253
+- **GitHub**: [github.com/swadhinbiswas/OpencodeHub](https://github.com/swadhinbiswas/OpencodeHub)
254
+- **Documentation**: [docs.opencodehub.space](https://docs.opencodehub.space)
255
+- **Issues**: [GitHub Issues](https://github.com/swadhinbiswas/OpencodeHub/issues)
256
+- **Discussions**: [GitHub Discussions](https://github.com/swadhinbiswas/OpencodeHub/discussions)
132
257
133
258
---
134
259
135
260
## License
136
261
137
-MIT
262
+[MIT](LICENSE) — Use it however you want.
138
263