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

---

## 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. Deploying `cgit` (Upcoming)

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