Cloudzilla

A minimal, self-hosted Git forge — single binary, no external runtime dependencies.

Stack: Go · Templ · HTMX · Alpine.js · Tailwind CSS · PostgreSQL

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

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)

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.

make docker-down        # Stop and remove containers

---

Local Development

Prerequisites: Go 1.27+, PostgreSQL 14+ (or Docker, for the Postgres step below)

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:

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:

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.

---

Documentation

Document	Description
CLAUDE.md	Developer guide: conventions, architecture, adding features
docs/api-reference.md	Full API endpoint tables with auth levels
docs/cli.md	cz remote client: install, login, scopes per command
docs/configuration.md	Config reference, env vars, CLI, production deployment
docs/ROADMAP.md	Full feature roadmap with phase specs and migration details
docs/access-control.md	Permission model: instance, org, and repo levels
docs/code-browser.md	Code browser URL patterns, CodeService API, ref resolution
docs/deployment.md	Docker quick start, env var overrides
docs/git-transport.md	HTTP smart protocol, SSH auth, permission rules
docs/htmx-patterns.md	Fragments, params, inheritance, errors, hx-on, toasts

---

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.

See the LICENSE file for the full license text, including the change date and additional use grants.