README.md
Rama main · réplica de lectura del repositorio original.
# Cloudzilla
A minimal, self-hosted Git forge — single binary, no external runtime dependencies.
**Stack:** Go · Templ · HTMX · Alpine.js · Tailwind CSS · PostgreSQL
[](LICENSE)
> **Alpha**: Cloudzilla is under active development. APIs and features may change. Not recommended for production use
> yet.
---
## Milestones
| Milestone | Scope | Status |
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| **M1 — Core Platform** (Phases 0–15.3) | Identity, git hosting, issues, PRs, code review, orgs, wikis, discussions, gists, search, and 50+ features across 100+ migrations | **Complete** |
| **M2 — Advanced Infrastructure** (Phases 16–20) | Container registry, Git LFS, CI/CD pipelines, clustering, GraphQL API | In progress |
---
## Architecture
```mermaid
graph TB
subgraph Client["Client"]
Browser["Browser (HTMX)"]
GitCLI["git CLI"]
SSHCLI["SSH Client"]
end
subgraph Cloudzilla["Cloudzilla (Single Binary)"]
HTTP["HTTP Server :8080\n(chi router)"]
SSH["SSH Server :2222\n(gliderlabs/ssh)"]
subgraph Layers["Application Layers"]
Handler["Handlers\n(page + API + git HTTP)"]
Service["Services\n(business logic)"]
Store["Stores\n(SQL queries / sqlx)"]
end
subgraph Frontend["Embedded Frontend"]
Templates["Templ Components"]
Static["Tailwind CSS + HTMX"]
end
end
subgraph Data["Persistence"]
PG[("PostgreSQL")]
Repos["Bare Git Repos\n(on disk)"]
end
Browser -->|"HTTP/HTTPS"| HTTP
GitCLI -->|"HTTP Smart Protocol"| HTTP
SSHCLI -->|"SSH git transport"| SSH
HTTP --> Handler
SSH --> Handler
Handler --> Service
Service --> Store
Store --> PG
Service --> Repos
Handler --> Templates
Templates --> Static
classDef client fill:#4A90D9,stroke:#2C5F8A,color:#fff
classDef server fill:#27AE60,stroke:#1A7A40,color:#fff
classDef data fill:#8E44AD,stroke:#6C3483,color:#fff
classDef frontend fill:#7F8C8D,stroke:#566573,color:#fff
class Browser,GitCLI,SSHCLI client
class HTTP,SSH,Handler,Service,Store server
class PG,Repos data
class Templates,Static frontend
```
---
## Features
- **Git hosting**: HTTP + SSH smart protocol, branch/tag management, code browser with blame, commit history and diffs,
clone URLs
- **Pull requests**: fast-forward / merge / squash strategies, diff view, draft PRs, auto-merge, conflict detection
- **Code review**: PR reviews (approve/request changes), inline line comments, code review suggestions with one-click
apply, CODEOWNERS auto-assign
- **Issues**: open/close workflow, labels, assignees, milestones, pinning, locking, private issues, issue templates
- **Organizations**: shared namespaces with owner/member roles, org profile pages, member management
- **Access control**: three-tier permissions (instance/org/repo), branch protection rules, deploy keys, personal access
tokens
- **Authentication**: JWT cookies, Google OAuth, TOTP 2FA with recovery codes, LDAP/SAML SSO, invitation system
- **Collaboration**: wikis, discussions, gists, profile READMEs, repository topics, stars, forks, reactions, @mentions,
saved replies
- **Notifications**: in-app notifications with unread badge, email notifications (SMTP), watching/subscriptions
- **Webhooks**: push/issues/PR events, HMAC-SHA256 signing, retry with backoff, event filtering, delivery logs
- **Search**: full-text search across repos, issues, PRs, and users (PostgreSQL tsvector + GIN) with word-prefix
matching and live topnav suggestions; advanced code search
- **Project management**: Kanban boards, milestones with progress tracking, activity feed
- **Infrastructure**: releases with tags, commit status API, audit log, OAuth apps, repository archive/templates,
soft-delete/recovery, explore/trending, dependency graph
- **Repositories**: import from another Git host, pull mirrors with scheduled sync, edit, rename and delete files from
the browser
- **Storage**: avatars and markdown image attachments on local disk or S3-compatible storage
- **Admin**: first-run setup wizard, site settings, invitation management, user suspension, password-reset links,
superadmin controls
- **Operations**: health and readiness probes, Prometheus metrics, backup and restore, per-user API rate limits and
per-owner quotas
- **CLI**: `cz` remote client for repos, issues and PRs, and `cz-admin` for server-side operator commands
---
## Quick Start
### Docker (recommended)
```bash
make docker-build
make docker-run
# Run migrations
docker exec -it cloudzilla-app-cloudzilla-1 /app/cz-admin migrate
# Open http://localhost:8080 — redirects to /setup to create superadmin
```
All data persists in Docker named volumes (`cloudzilla_data`, `postgres_data`). Set `CZ_AUTH_JWT_SECRET` in
`docker-compose.yml` before exposing publicly.
```bash
make docker-down # Stop and remove containers
```
---
### Local Development
**Prerequisites:** Go 1.27+, PostgreSQL 14+ (or Docker, for the Postgres step below)
```bash
go mod tidy
make setup-tailwind # One-time: download Tailwind CLI
make setup-templ # One-time: install the templ CLI
make setup-air # One-time: install the reloader `make dev` uses
```
Start Postgres. The simplest option is the `postgres` service from the bundled compose file, which is preconfigured with
the user/db that `config.yaml` expects:
```bash
docker compose up -d postgres # exposes 5432 to host; data persists in postgres_data volume
```
Prefer a native install? Run any PostgreSQL 14+ and create a `cloudzilla` role and database (password `cloudzilla`) — or
edit the DSN in `config.yaml` to match what you already have.
Then run migrations and start the dev server:
```bash
make migrate # Run DB migrations
make dev # Backend + Tailwind watch on http://localhost:8080
```
First visit redirects to `/setup` to create your superadmin account.
For a populated instance to click around in, run `make seed` after `make migrate` on a fresh database instead of
visiting `/setup`. It writes the repositories to `./git-repos`, where `make dev` reads them. See
[`cz-admin seed`](./docs/configuration.md#cz-admin-seed).
---
## Documentation
| Document | Description |
| -------------------------------------------------- | ----------------------------------------------------------- |
| [CLAUDE.md](./CLAUDE.md) | Developer guide: conventions, architecture, adding features |
| [docs/api-reference.md](./docs/api-reference.md) | Full API endpoint tables with auth levels |
| [docs/cli.md](./docs/cli.md) | `cz` remote client: install, login, scopes per command |
| [docs/configuration.md](./docs/configuration.md) | Config reference, env vars, CLI, production deployment |
| [docs/ROADMAP.md](./docs/ROADMAP.md) | Full feature roadmap with phase specs and migration details |
| [docs/access-control.md](./docs/access-control.md) | Permission model: instance, org, and repo levels |
| [docs/code-browser.md](./docs/code-browser.md) | Code browser URL patterns, CodeService API, ref resolution |
| [docs/deployment.md](./docs/deployment.md) | Docker quick start, env var overrides |
| [docs/git-transport.md](./docs/git-transport.md) | HTTP smart protocol, SSH auth, permission rules |
| [docs/htmx-patterns.md](./docs/htmx-patterns.md) | Fragments, params, inheritance, errors, hx-on, toasts |
| [docs/notifications.md](./docs/notifications.md) | Notification types, service API, extension pattern |
| [docs/organizations.md](./docs/organizations.md) | OrgService API, endpoints, role model |
| [docs/pr-merge.md](./docs/pr-merge.md) | Merge strategies, conflict detection, PRDiffResult |
| [docs/repo-import.md](./docs/repo-import.md) | Background clone jobs, SSRF guard, `import.*` config |
| [docs/repo-mirrors.md](./docs/repo-mirrors.md) | Pull mirrors: sync, scheduler, read-only guard, credentials |
| [docs/storage.md](./docs/storage.md) | Local and S3 backends, object layout, avatars, attachments |
| [docs/webhooks.md](./docs/webhooks.md) | Webhook events, HMAC signing, dispatch pattern |
---
## Make Targets
| Target | Description |
| ----------------------- | ------------------------------------------------------------------ |
| `make setup-tailwind` | Download Tailwind CLI (one-time) |
| `make setup-templ` | Install the templ CLI (one-time) |
| `make setup-air` | Install the reloader `make dev` uses (one-time) |
| `make generate-templ` | Regenerate `*_templ.go` from `*.templ` files |
| `make download-mermaid` | Download mermaid.min.js (one-time; auto-runs in build/dev) |
| `make download-htmx` | Download htmx.min.js (once per version; auto-runs in build/dev) |
| `make build-css` | Compile Tailwind CSS |
| `make dev` | Run backend + Tailwind + templ watch concurrently |
| `make build` | Full build: download assets, compile CSS, generate templ, build Go |
| `make migrate` | Run DB migrations |
| `make seed` | Fill a fresh, migrated database with test data |
| `make lint` | Run golangci-lint |
| `make test` | Run unit tests (no database required) |
| `make test-db` | Start the test database container |
| `make test-integration` | Run all tests including integration tests (requires Docker) |
| `make clean` | Remove build artifacts |
| `make docker-build` | Build Docker image |
| `make docker-run` | Start with docker compose (detached) |
| `make docker-down` | Stop and remove containers |
---
## Project Structure
```
cmd/
server/ # HTTP server entrypoint
frontend/ # Static files (embedded in binary)
static/
main.css # Compiled Tailwind output
mermaid.min.js # served at /static/mermaid.min.js
htmx.min.js # served at /htmx.min.js
alpine.min.js # served at /alpine.min.js
cz-admin/ # Operator CLI (cobra)
cz/ # Remote client for developers (cobra)
internal/
config/ # Config loading (viper + YAML)
db/ # DB connection + migration runner
migrations/ # SQL files (embedded via embed.FS)
model/ # Data structs (db + json tags)
store/ # Store layer (raw SQL via sqlx)
service/ # Business logic (calls stores)
handler/ # HTTP handlers (page + API + git)
middleware/ # Auth, logger, CORS, RequireSetup
assets/ # Serves frontend/ under content-hash URLs, with ETags and gzip
router/ # chi route registration
ssh/ # SSH server (gliderlabs/ssh)
view/ # Templ components
layout/ # Base layout component
pages/ # Page components
fragments/ # HTMX fragment components
tailwind/ # Tailwind CSS v4 entry point: theme tokens, sources
docs/ # Architecture and feature docs
```
---
## License
Cloudzilla is licensed under the [Business Source License 1.1](LICENSE).
See the [LICENSE](LICENSE) file for the full license text, including the change date and additional use grants.