From 4b7379914a1865f07b2c54252234cc90158fc253 Mon Sep 17 00:00:00 2001 From: Miguel Dalberto Pedro Date: Thu, 29 Oct 2026 12:48:06 -0300 Subject: feat(iac): establish Ansible baseline for Nginx, SearXNG, Valkey, and Certbot - Reverse-engineer live Debian 13 (trixie) VPS state at miguelpedro.xyz.br - Add modular Ansible roles: common, certbot, valkey, searxng, and nginx - Encrypt SearXNG secret_key using ansible-vault in group_vars/all/vault.yml - Cleanly remove unused example.com Nginx stub symlink (sites-enabled/miguelpedro.xyz.br) - Scaffold cgit + fcgiwrap role (cgit_enabled: false) for upcoming deployment - Add DISCOVERY_REPORT.md, COMMAND_LOG.md, README.md, and AGENT_INSTRUCTIONS.md with Self-Updating Protocol --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..770013d --- /dev/null +++ b/README.md @@ -0,0 +1,96 @@ +# `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`
`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. -- cgit v1.2.3