Package: pearing-cli Version: 0.2.0-1 Architecture: amd64 Maintainer: Ben Wilber Installed-Size: 4982 Filename: pool/main/pearing-cli_0.2.0_amd64.deb Size: 1641480 MD5sum: ab2fd5578be6aae7caf8332c74dbe70a SHA1: 67f81fd1a431cb709324976e535404b155f5631c SHA256: e78c5d596ad5e9be8521a670482535130f03ab957adaa571d3025241485dd829 Priority: optional Description: HTTP API client for pearing-server. Package: pearing-server Version: 0.2.0-1 Architecture: amd64 Maintainer: Ben Wilber Installed-Size: 50222 Filename: pool/main/pearing-server_0.2.0_amd64.deb Size: 13970504 MD5sum: 5c1ed9abfeb2db6b79f1b628121f9ef0 SHA1: 39ca1de8d35f4040a1488f681610f29b13639e3c SHA256: c0860870ed2a6b574176d77e5d3f937f7efde9cd3aa0760294ca0cad571841cc Priority: optional Description: Self-hosted Git forge with web UI, API, and smart HTTP Git support. # pearing . `pearing` is a Rust workspace for a small self-hosted Git hosting service. . It runs a single Axum server that combines: . - a JSON API (`/api/v1`) - a server-rendered web UI (auth, profile, admin, repo browsing) - Git smart-HTTP endpoints (clone/fetch/push) . Data is stored in Postgres via SQLx. Git repositories are stored on disk as bare repos. . ## Workspace packages . - root package `pearing-server`: the Axum server application that owns the JSON API, server-rendered web UI, docs pages, and Git smart-HTTP integration - `crates/pearing-cli`: standalone HTTP API client binary (`pearing-cli ...`) - `crates/pearing-core`: shared primitives such as `AppState`, `Paging`, `Page`, and `PagingInfo` - `crates/pearing-db`: Postgres data layer with typed models, SQL query files, migrations, seed binaries, and integration tests - `crates/pearing-events`: dependency-light event wire types, with separate `pearing-events-client` and `pearing-events-server` transport/runtime crates - `crates/pearing-git`: Git smart-HTTP transport and repo filesystem utilities (`init_bare_repo`, `fork_repo`, protocol handling for upload-pack/receive-pack`) - `crates/pearing-adm`: standalone server admin binary for migrations and future maintenance tasks - `crates/pearing-work`: event-driven orchestrator that dispatches Pearing events to local agents . ## Runtime overview . - `pearing-server` parses server runtime flags and starts the application process. - `pearing-cli` calls the HTTP JSON API and prints JSON responses. - `pearing-adm` performs server-side maintenance tasks such as tracked database migrations. - `pearing-work` connects directly to the tail-events API and dispatches matching events to configured agents. - `pearing-server` builds `AppState` (DB pool, templates, static dir, repo dir, CSRF config) and merges routers from: - server API routes - `pearing-git` - server web routes - Session cookies are signed (`SESSION_KEY` environment variable). - The server listens on the configured socket address and prints the bound address on startup. . ## Web and API capabilities . - Users: - signup/signin/signout (web) - CRUD/list/get-self (API, token-auth) - Teams and members: - create/update/list/get teams - add/update/remove/list team members - Repositories: - create/update/list team repos via API - personal and team repo management via web UI - visibility controls (`public`/`private`) - Forking: - create/list/get repo forks via API - fork flows in web UI - Repository browsing (web): - tree/blob/raw views - commits and commit detail - branches and tags - compare and diff pages - archive download routes - Git over HTTP: - `info/refs`, `git-upload-pack`, `git-receive-pack` - auth-aware access for private repos . ## Git HTTP authentication . Git smart-HTTP supports: . - `Authorization: Bearer ` with an API token - `Authorization: Basic ...` with API token auth - `Authorization: Basic ...` with username/email + password auth . For Basic auth, the password value is checked against API tokens first. If the Basic username is non-empty and no token row matches, `pearing` falls back to username/email + password authentication. . ## Database . - Postgres is the primary datastore; SQL lives in `crates/pearing-db/src/sql`. - Migrations live in `crates/pearing-db/migrations`. - A dev Postgres instance can be started with `docker compose up pg`. . ## Running locally . The supported contributor workflow uses local Rust tooling with PostgreSQL 16 provided by Docker Compose. See `CONTRIBUTING.md` for the full project rules, setup details, and validation guidance. . Start PostgreSQL, create a contributor-specific `.env`, and run the server: . ```bash just pg-up just -E .env create-db just -E .env migrate just -E .env run-server ``` . The committed `docker-compose.yml` does not publish host ports. If you want to reach the web UI or API from the host during manual testing, create a gitignored `docker-compose.override.yml` such as: . ```yaml services: dev: ports: - "7327:7327" ``` . ## Development . Common validation commands (see `justfile`): . ```bash just -E .env check just -E .env test just -E .env ready just -E .env sqlx-check ``` . `just ready` runs formatting checks, Clippy, all workspace tests, and the release-tool tests. It accepts extra `cargo test` arguments such as `just -E .env ready --test api`. . ## Releases . Pearing publishes the server, CLI, and Work orchestrator from one strict SemVer workspace version. Annotated `vX.Y.Z` tags on `main` produce native archives for x86_64 and ARM64 Linux, Apple Silicon macOS, and x86_64 and ARM64 Windows. Linux releases also include separate Debian packages for all three products. The `pearing-work` archive and Debian package are self-contained and connect directly to the tail-events API; `pearing-cli` is distributed independently. . The server locates templates and static assets in this order: explicit `TEMPLATES_DIR` or `STATIC_DIR`, `PEARING_DATA_DIR`, the installed `../share/pearing-server` directory relative to the executable, then the source tree for development and tests. . Stable releases update all formulae in the private `benwilber/homebrew-pearing` tap through one tested pull request. Initial macOS and Windows artifacts are unsigned and macOS artifacts are not notarized. Private consumers authenticate with `gh release download` and pre-seed the Homebrew cache as documented in `packaging/homebrew/README.md`; formulae never contain access tokens. . ## License . This project is licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).