# QRknit — Private Git Repository Setup

Notes for setting up and securing `https://git.qrknit.com/` to distribute the private instance source to Pro and Team plan customers.

---

## Recommended Stack: Gitea (or Forgejo)

Gitea is a lightweight self-hosted Git service — single binary, runs in Docker, low resource footprint. Forgejo is a community-maintained fork with the same API; either works.

**Why it fits:**
- Private repos by default
- Per-user access tokens (customers clone with a token, not a password)
- Organisation/team support for managing customer access in bulk
- Runs behind existing Cloudflare/Nginx Proxy Manager setup
- Web UI for repo management
- Gitea API allows automating account and token creation on subscription

---

## Docker Compose

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    restart: unless-stopped
    environment:
      - GITEA__server__DOMAIN=git.qrknit.com
      - GITEA__server__ROOT_URL=https://git.qrknit.com
      - GITEA__server__DISABLE_SSH=true            # HTTPS-only
      - GITEA__service__DISABLE_REGISTRATION=true  # no public sign-ups
      - GITEA__service__REQUIRE_SIGNIN_VIEW=true   # repo browser requires login
    volumes:
      - gitea-data:/data
    ports:
      - "3000:3000"
```

Point Nginx Proxy Manager or Cloudflare proxy host at port 3000, issue a Let's Encrypt cert, done.

---

## Security Configuration

**Disable public registration** — the env var above does this, or set it in the admin panel after first run. Customer accounts are created manually or via the Gitea API.

**Keep the repo private** — set repository visibility to Private in Gitea. `REQUIRE_SIGNIN_VIEW=true` ensures the repo is not visible to unauthenticated requests.

**Per-customer access tokens** — when a customer subscribes to Pro/Team, create them a Gitea account and generate a personal access token scoped to `read:repository` only. Their clone URL:
```
https://<username>:<token>@git.qrknit.com/qrknit/qrknit.git
```

**Revocation** — when a subscription lapses, disable or delete the Gitea account. Their token stops working immediately.

**Behind Cloudflare** — Cloudflare's WAF and rate limiting rules apply at the edge before any request reaches Gitea, which handles brute-force attempts on the token endpoint.

---

## What to Avoid

- **Public GitHub repo** — even a private GitHub repo exposes metadata and depends on GitHub's access controls rather than your own.
- **SSH with shared keys** — harder to revoke per-customer without rotating keys for everyone.
- **Embedding credentials in docs** — `INSTALL.md` shows the clone URL without credentials, which is correct. Credentials should be communicated out-of-band (welcome email, customer portal).

---

## Customer Onboarding Flow

1. Payment confirmed → create Gitea account (manually or via Gitea API)
2. Generate a read-only personal access token (`read:repository` scope)
3. Send welcome email with their clone URL and a link to `INSTALL.md`
4. Subscription cancelled → disable or delete Gitea account

---

## Font Bundling Note (OFL-1.1)

If a future release bundles Google Font files locally (e.g. for air-gapped private instances), the OFL-1.1 licence requires the licence text to be included alongside the `.woff2` files. The current CDN delivery path has no such requirement. See `NOTICES.md` for full licence texts.