# `miguelpedro.xyz.br` Infrastructure-as-Code (IaC)

This repository manages the configuration and state of the `miguelpedro.xyz.br` VPS (Debian 13 `trixie`) using **Ansible** and **Ansible Vault**.

---

## 1. Architecture & Managed Services

| Service | Domain / Endpoint | Role | Description |
| :--- | :--- | :--- | :--- |
| **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** | `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`) |

---

## 2. Repository Structure

```text
my-infra/
├── ansible.cfg                 # Ansible configuration (inventory, roles_path, vault_password_file)
├── site.yml                    # Main playbook entrypoint
├── inventory/
│   └── hosts.yml               # Target VPS inventory (root@miguelpedro.xyz.br)
├── group_vars/
│   └── all/
│       ├── vars.yml            # Global non-sensitive variables & feature flags
│       └── vault.yml           # AES-256 encrypted secrets (ansible-vault)
├── roles/
│   ├── common/                 # System packages & build dependencies
│   ├── certbot/                # Let's Encrypt packages, timer, and cert checks
│   ├── valkey/                 # Valkey server installation & systemd service
│   ├── searxng/                # SearXNG user, git checkout, settings.yml, limiter.toml, uwsgi ini
│   ├── nginx/                  # nginx.conf, vhost templates, clean sites-enabled management
│   └── cgit/                   # Prepared role for upcoming cgit + fcgiwrap deployment
├── AGENT_INSTRUCTIONS.md       # Operational guide & Self-Updating Protocol for AI agents
├── DISCOVERY_REPORT.md         # Reverse-engineered state map of the VPS
└── COMMAND_LOG.md              # Running log of discovery and verification commands
```

---

## 3. Usage & Operations

### Prerequisites
A local Python virtual environment (`.venv`) with `ansible-core` is pre-configured in this repository, along with a git-ignored `.vault_pass` file for automatic decryption of `group_vars/all/vault.yml`.

If setting up on a new machine:
```bash
python3 -m venv .venv
.venv/bin/pip install ansible-core
# Place your Ansible Vault password in .vault_pass (chmod 600 .vault_pass)
```

### Dry-Run (Check for Configuration Drift)
Always run in `--check --diff` mode first to preview changes without modifying the VPS:
```bash
.venv/bin/ansible-playbook site.yml --check --diff
```

### Apply Changes
```bash
.venv/bin/ansible-playbook site.yml --diff
```

### Run Specific Roles via Tags
```bash
.venv/bin/ansible-playbook site.yml --tags "nginx" --diff
.venv/bin/ansible-playbook site.yml --tags "searxng" --diff
```

### Managing Secrets (`ansible-vault`)
Sensitive values (such as `vault_searxng_secret_key`) are encrypted in [`group_vars/all/vault.yml`](file:///home/mpedro/Repos/my-infra/group_vars/all/vault.yml).
- **View encrypted secrets:**
  ```bash
  .venv/bin/ansible-vault view group_vars/all/vault.yml
  ```
- **Edit encrypted secrets:**
  ```bash
  .venv/bin/ansible-vault edit group_vars/all/vault.yml
  ```

---

## 4. Using `cgit` & Managing Git Repositories

`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
   ```