# VPS administration

Reusable Ansible configuration for Debian and Ubuntu servers. Host hardening is implemented first; Docker Compose services will be added in separate directories as the rollout progresses. The local checkout can bootstrap Gitea before it becomes a Git remote.

## Set up a fresh clone

Run Ansible from a macOS or Linux controller with SSH access to the target. Ansible does not support native Windows as a control node.

```sh
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-controller.txt
ansible-galaxy collection install -r requirements.yml
cp inventory/hosts.yml.example inventory/hosts.yml
cp inventory/group_vars/all.yml.example inventory/group_vars/all.yml
cp inventory/host_vars/server1.yml.example inventory/host_vars/server1.yml
```

Edit `inventory/hosts.yml` with the host alias, address, existing SSH account, and current SSH port. Keep hosts you intend to manage under the `debian_servers` group. Rename each `inventory/host_vars/<alias>.yml` to match its alias; set the admin public keys and the ports its services need. Edit `inventory/group_vars/all.yml` for shared defaults. Host-specific values can override them in `host_vars`.

All active inventory `.yml` files are Git ignored. The `.yml.example` templates are tracked, so a clone has a starting point without committing server addresses, access details, or local policy. Create and encrypt `inventory/group_vars/all/vault.yml` as described in [docs/hardening.md](docs/hardening.md).

For the first server, run discovery and then follow the staged [hardening procedure](docs/hardening.md):

```sh
ansible-playbook playbooks/discover.yml -l server1
```

Replace `server1` with the chosen inventory alias. Both the bootstrap and hardening playbooks target `debian_servers` and process hosts one at a time. Use `-l <alias>` for the first rollout.

## Repository layout

- `inventory/`: local host definitions and tracked examples.
- `playbooks/`: discovery, admin bootstrap, and hardening entry points.
- `roles/`: reusable Ansible tasks.
- `docs/`: rollout and security procedures.
- `stacks/<service>/`: planned separate Compose projects for each service.

Planned app stacks will join one external `traefik` network when they need HTTP routing. Traefik route fragments and DIUN image watch files will live alongside each service. The [rollout plan](docs/plan.md) records the Pi pilot and later service deployment.

Commit no plaintext passwords, tokens, private keys, or runtime `.env` files. Keep the Ansible Vault password outside this repository.