From eab4f5746a69783e4e3a3c05808ab58b5d2f494d Mon Sep 17 00:00:00 2001
From: Miguel Dalberto Pedro <miguel.pedro@precisioninno.com>
Date: Thu, 29 Oct 2026 16:42:44 -0300
Subject: feat(cgit): deploy cgit, fcgiwrap, and dedicated git SSH server

- Enable cgit role (cgit_enabled: true) for git.miguelpedro.xyz.br
- Provision dedicated 'git' user/group (/srv/git, git-shell, authorized_keys)
- Add custom git-shell commands ('init' and 'list') for remote bare repo creation
- Configure /etc/cgitrc with HTTP clone support, Pygments syntax highlighting, and README rendering
- Add Nginx virtual host with automatic TLS upgrade once Let's Encrypt cert is present
- Update DISCOVERY_REPORT.md, COMMAND_LOG.md, README.md, and AGENT_INSTRUCTIONS.md per Self-Updating Protocol
---
 README.md | 41 +++++++++++++++++++++++++++++++----------
 1 file changed, 31 insertions(+), 10 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 770013d..e92509b 100644
--- a/README.md
+++ b/README.md
@@ -8,11 +8,11 @@ This repository manages the configuration and state of the `miguelpedro.xyz.br`
 
 | Service | Domain / Endpoint | Role | Description |
 | :--- | :--- | :--- | :--- |
-| **Nginx** | `miguelpedro.xyz.br`<br>`searx.miguelpedro.xyz.br` | [`roles/nginx`](file:///home/mpedro/Repos/my-infra/roles/nginx/tasks/main.yml) | Reverse proxy, TLS termination, and static web server |
+| **Nginx** | `miguelpedro.xyz.br`<br>`searx.miguelpedro.xyz.br`<br>`git.miguelpedro.xyz.br` | [`roles/nginx`](file:///home/mpedro/Repos/my-infra/roles/nginx/tasks/main.yml) | Reverse proxy, TLS termination, and static web server |
 | **Certbot** | `/etc/letsencrypt/` | [`roles/certbot`](file:///home/mpedro/Repos/my-infra/roles/certbot/tasks/main.yml) | Automated Let's Encrypt ECDSA certificate management (`certbot.timer`) |
 | **SearXNG** | `https://searx.miguelpedro.xyz.br/` | [`roles/searxng`](file:///home/mpedro/Repos/my-infra/roles/searxng/tasks/main.yml) | Privacy-respecting metasearch engine served via `uwsgi` Unix socket |
 | **Valkey** | `127.0.0.1:6379` | [`roles/valkey`](file:///home/mpedro/Repos/my-infra/roles/valkey/tasks/main.yml) | Local key-value store backing SearXNG's rate limiter and bot detection |
-| **cgit** *(Prepared)* | `git.miguelpedro.xyz.br` | [`roles/cgit`](file:///home/mpedro/Repos/my-infra/roles/cgit/tasks/main.yml) | Ready-to-enable role (`cgit_enabled: false`) for self-hosted Git web UI via `fcgiwrap` |
+| **cgit** | `https://git.miguelpedro.xyz.br/` | [`roles/cgit`](file:///home/mpedro/Repos/my-infra/roles/cgit/tasks/main.yml) | Self-hosted Git web UI (`cgit` + `fcgiwrap`), HTTP clone support, and `git@` SSH hosting (`/srv/git`) |
 
 ---
 
@@ -84,13 +84,34 @@ Sensitive values (such as `vault_searxng_secret_key`) are encrypted in [`group_v
 
 ---
 
-## 4. Deploying `cgit` (Upcoming)
+## 4. Using `cgit` & Managing Git Repositories
 
-The `cgit` role ([`roles/cgit`](file:///home/mpedro/Repos/my-infra/roles/cgit/tasks/main.yml)) is already scaffolded. When ready to deploy:
-1. Ensure DNS for `cgit_domain` (default `git.miguelpedro.xyz.br`) points to the VPS.
-2. In [`group_vars/all/vars.yml`](file:///home/mpedro/Repos/my-infra/group_vars/all/vars.yml), set:
-   ```yaml
-   cgit_enabled: true
+`cgit` is active (`cgit_enabled: true`) and serves repositories from `/srv/git` under the dedicated `git` user (`git-shell`).
+
+### Creating a New Repository via SSH
+A custom `git-shell` helper command (`init`) is installed so you can create bare repositories remotely without logging into root:
+```bash
+ssh git@miguelpedro.xyz.br init my-project.git "My project description"
+```
+
+### Listing Existing Repositories via SSH
+```bash
+ssh git@miguelpedro.xyz.br list
+```
+
+### Pushing to a Repository
+```bash
+git remote add origin git@miguelpedro.xyz.br:my-project.git
+git push -u origin master
+```
+
+### Enabling HTTPS for `git.miguelpedro.xyz.br`
+Once your DNS `A` record for `git.miguelpedro.xyz.br` points to `189.126.106.41`:
+1. Request the Let's Encrypt certificate on the VPS:
+   ```bash
+   ssh root@miguelpedro.xyz.br "certbot certonly --nginx -d git.miguelpedro.xyz.br"
+   ```
+2. Re-run the `cgit` role—[`roles/cgit/templates/site-cgit.conf.j2`](file:///home/mpedro/Repos/my-infra/roles/cgit/templates/site-cgit.conf.j2) automatically detects `/etc/letsencrypt/live/git.miguelpedro.xyz.br/fullchain.pem` and switches the Nginx virtual host to HTTPS with HTTP-to-HTTPS redirect:
+   ```bash
+   .venv/bin/ansible-playbook site.yml --tags "cgit" --diff
    ```
-3. Run `.venv/bin/ansible-playbook site.yml --tags "cgit" --diff`.
-4. Provision TLS via Certbot (`certbot --nginx -d git.miguelpedro.xyz.br`) and update [`roles/cgit/templates/site-cgit.conf.j2`](file:///home/mpedro/Repos/my-infra/roles/cgit/templates/site-cgit.conf.j2) to include the SSL directives.
-- 
cgit v1.2.3