# Cloudzilla

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

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

[![License: BSL 1.1](https://img.shields.io/badge/License-BSL_1.1-blue.svg)](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.