# Gitssy

**Self-hosted Git forge, social hub, and optional cloud dev shells — in one fast, cohesive web app.**

Gitssy is for teams and individuals who want **Git hosting under their own control**: browse and edit code in the browser, review changes, collaborate on issues and tasks, and optionally spin up **isolated terminals** next to their repos — without shipping your workflow to a third-party SaaS.

> **Note:** Install scripts, environment files, and some docs still use the historical name **OpenGit** (for example `.opengit.env`). Functionally they refer to the same application stack.

---

## Who it’s for

| Audience | Why Gitssy fits |
|----------|-----------------|
| **Self-hosters & homelabbers** | Run your own “mini GitHub” on a VPS or internal server; your code and metadata stay on your metal. |
| **Small teams & studios** | Repos, PRs, wiki, chat, and notifications in one place — no per-seat tax from an external forge. |
| **Privacy-conscious orgs** | Optional 2FA, admin-controlled registration, trusted IPs, maintenance mode, and **no dependency on a vendor UI** for day-to-day Git. |
| **Developers who live in Git** | **HTTP and SSH** transports, familiar `owner/repo` URLs, and a web UI that mirrors what you expect from modern forges. |

---

## How it looks and feels

Gitssy’s interface is built around a **dark, glassy aesthetic**: layered panels, subtle borders, and accent-driven highlights rather than flat admin chrome. It’s meant to feel like a **focused developer tool**, not a generic CMS.

**Personalization (per user)** goes deep:

- **Color presets** — tint accents, panels, and (on some presets) muted text across the whole UI.
- **Animated backgrounds** — stars, waves, drips, and similar options behind the main layout.
- **Cursor themes** — minimal, ring, glow, and default styles.
- **UI font** — selectable typography for readability and taste.

Together, these options make the instance feel **yours** whether you’re running a public community or a private team server.

---

## Core features

### Git hosting (the heart of the product)

- **Repositories** — create, fork, star, watch; public/private visibility; explore and “my repositories” views.
- **Smart Git over HTTP(S)** — standard `git clone` / `fetch` / `push` against URLs like `https://your-host/Owner/repo.git`; anonymous clone for **public** repos; **push always authenticated**.
- **Git over SSH** — optional **AsyncSSH** sidecar (`opengit-git-ssh` / systemd) on a configurable port, sharing the **same on-disk repos and auth rules** as HTTP.
- **Branches** — create and delete from the web UI.
- **File tree & blobs** — navigate the tree, view rendered files, **raw** endpoints, single-file download, and **ZIP archive** of a branch.
- **Commit history** — log browsing and commit detail views.
- **Contributors** — list, add/remove collaborators, per-user commit stats.

### Edit code without leaving the browser

- Create, upload, move, bulk-delete, and update files with **diff preview** before you commit.
- **Revert** individual file paths or whole commits; **hard reset** when you need to rewind history (with appropriate safeguards in the UI).
- Optional **Ollama** integration: generate **commit titles and descriptions** from a real unified diff, with server-side checks to reduce hallucinated filenames and version numbers.

### Collaboration

- **Pull requests** — open, review, merge, and close; integrated with repo activity.
- **Per-repo wiki** — pages, ordering, default page, backed by the same project context as the code.
- **Issues** — threaded discussion with **@mentions** that notify the right people.
- **Tasks** — lightweight project tasks alongside issues, also with mentions.
- **Security view** — repo security scanning workflow (rescan from the UI).

### Social layer (beyond Git)

- **User profiles** — follow users, show activity and identity.
- **Home feed** — posts with **emoji reactions**; real-time updates over **Socket.IO**.
- **Messenger** — direct messaging between users who **mutually follow** each other.
- **Notifications** — in-app (and real-time) alerts for mentions, PRs, and other events tied to repos.

### Ephemeral dev environments (“shells”)

Gitssy can provision **browser-backed terminals** tied to your workflow, with admin-tunable **CPU, RAM, disk, runtime, and optional network limits**:

- **Docker** or **Podman** backends (auto-detected sockets).
- Optional **Kata** / **gVisor-style** isolation paths for stricter boundaries (see `wiki/kata.md` and `wiki/podman.md`).
- **Socket.IO** + **gevent**-friendly design so terminal I/O doesn’t stall the rest of the app when configured accordingly.

These are ideal for **quick repros**, **CI-adjacent checks**, or **teaching** — without giving every user SSH to the host.

---

## Unique strengths

1. **Single cohesive app** — Git, social feed, chat, shells, billing hooks, and admin tools share one database and one session model; no bolted-on micro-frontends.
2. **Two Git transports, one authorization model** — enable HTTP, SSH, or both; the same rules gate access.
3. **AI-assisted commits that respect the diff** — Ollama is optional and **off by default**; when on, prompts and scrubbing favor **grounded** messages over creative fiction.
4. **Credits + Stripe** — optional monetization: credits ledger, subscriptions, regional currency support, and admin-tuned pricing — for public instances that need to fund hosting.
5. **Operator-grade controls** — maintenance mode, backups (with first-time restore paths), SMTP for mail, trusted IPs, Git **policy** hooks, profiler, and clone-size limits — aimed at real deployments, not just demos.

---

## Speed and architecture (why it stays responsive)

- **Flask** application with **Gunicorn**; **gevent** workers recommended for production so long-lived **Socket.IO** sessions and normal HTTP requests don’t block each other.
- **Redis message queue** for Socket.IO when you run **multiple workers** behind nginx — horizontal scale without losing realtime events (see `wiki/scaling-socketio.md`).
- Git HTTP uses **streaming** `git upload-pack` / `git receive-pack` subprocesses integrated with app auth — similar spirit to `git-http-backend`, but native to Gitssy’s permission model.
- Optional **`OPENGIT_REQUEST_TIMING`** logging to spot slow endpoints in production.

---

## Choice and flexibility

| Area | Options |
|------|---------|
| **Database** | **SQLite** by default (`git.db`); **PostgreSQL** via `DATABASE_URL` — same schema, automatic SQL dialect adaptation (`wiki/databases.md`). |
| **Git access** | HTTP(S) only, SSH only, or both — toggled in admin settings. |
| **Shell isolation** | Docker, Podman, optional Kata / gVisor-related paths — pick what your host supports. |
| **Appearance** | Presets, backgrounds, cursors, fonts — users aren’t locked into one look. |
| **Commerce** | Stripe and credits can be **disabled** for purely internal instances. |

Configuration commonly lives in **`.opengit.env`** at the app root (e.g. `DATABASE_URL`, `REDIS_URL` / `SOCKETIO_REDIS_URL` for scaled realtime).

---

## Documentation and operations

- **Operator / architecture docs:** [`wiki/README.md`](wiki/README.md) — start there for Git transports, nginx, databases, Podman/Kata, Socket.IO scaling, and timezones.
- **Install & update:** project `scripts/` (`install_opengit.sh`, `update.sh`, `fresh_install.sh`, etc.) and service units under `scripts/*.service`.
- **Health check:** `GET /ping` returns a simple JSON OK for load balancers.

---

## Tech stack (high level)

- **Python / Flask**, **Flask-Login**, **Flask-SocketIO**
- **GitPython** + system `git` for repository operations
- **PostgreSQL** (`psycopg2`) or **SQLite**
- **Redis** (optional, for Socket.IO scaling)
- **Stripe**, **requests**, **APScheduler**
- **AsyncSSH** (Git SSH daemon)
- **Docker** API (shells; Podman via compatible socket)

Runtime dependencies are listed in [`requirements.txt`](requirements.txt).

---

## Version

The current release line is recorded in [`VERSION`](VERSION) at the repository root (e.g. `2026.03.20-8`).

---

## Contributing and ethos

Gitssy aims to be **boring where it matters** (Git compatibility, auth, storage layout) and **expressive where users spend time** (UI, collaboration, optional shells). If you improve docs, fix edge cases in transport auth, or polish the repository UI, you’re aligned with the project’s direction.

Welcome to Gitssy — **your forge, your rules, your speed.**
