`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` `git.miguelpedro.xyz.br`	`roles/nginx`	Reverse proxy, TLS termination, and static web server
Certbot	`/etc/letsencrypt/`	`roles/certbot`	Automated Let's Encrypt ECDSA certificate management (`certbot.timer`)
SearXNG	`https://searx.miguelpedro.xyz.br/`	`roles/searxng`	Privacy-respecting metasearch engine served via `uwsgi` Unix socket
Valkey	`127.0.0.1:6379`	`roles/valkey`	Local key-value store backing SearXNG's rate limiter and bot detection
cgit	`https://git.miguelpedro.xyz.br/`	`roles/cgit`	Self-hosted Git web UI (`cgit` + `fcgiwrap`), HTTP clone support, and `git@` SSH hosting (`/srv/git`)

2. Repository Structure

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:

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:

.venv/bin/ansible-playbook site.yml --check --diff

Apply Changes

.venv/bin/ansible-playbook site.yml --diff

Run Specific Roles via Tags

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

ssh git@miguelpedro.xyz.br init my-project.git "My project description"

Listing Existing Repositories via SSH

ssh git@miguelpedro.xyz.br list

Pushing to a Repository

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