# Development Setup
## Prerequisites
- Rust toolchain (1.70+)
- Ansible (for playbook development)
- mise (for environment management)
- age (for encrypting secrets)
## Bootstrap
Run the setup script to install required development tools:
```bash
./setup
```
This installs:
- mise (environment and tool version manager)
- Rust toolchain
- Ansible and ansible-lint
- Other dev dependencies (dprint, dasel, pkl, etc.)
## Configuration
All configuration is managed via `config.toml`. Initialize the config file:
```bash
auberge config init
```
Key values to set:
```bash
auberge config set admin_user_name yourname
auberge config set admin_user_email you@example.com
auberge config set domain example.com
auberge config set cloudflare_dns_api_token your-token
auberge config set baikal_admin_password your-password
auberge config set webdav_password your-password
auberge config set tailscale_authkey your-authkey
auberge config set ssh_port 22022
```
See `config.example.toml` for all available options including subdomain overrides.
## Host Management
Hosts can be managed in two ways:
### Option 1: XDG Config (Recommended for end users)
For users installing via `cargo install`, hosts are managed in `~/.config/auberge/hosts.toml`:
```bash
# Add a host interactively
auberge host add my-vps
# Or non-interactively
auberge host add my-vps 203.0.113.10 --user admin --port 22
# List hosts
auberge host list
# Show host details
auberge host show my-vps
# Edit host
auberge host edit my-vps
# Remove host
auberge host remove my-vps
```
The `hosts.toml` format:
```toml
[[hosts]]
name = "auberge"
address = "203.0.113.10"
user = "sripwoud"
port = 22
tags = ["production"]
description = "Main VPS"
```
### Option 2: Ansible Inventory (Recommended for developers)
For development, keep using `ansible/inventory.yml` in the repository:
```yaml
all:
children:
vps:
hosts:
auberge:
ansible_host: "{{ lookup('env', 'AUBERGE_HOST') }}"
ansible_port: 22
bootstrap_user: root
```
### Priority Order
The CLI checks hosts in this order:
1. `~/.config/auberge/hosts.toml` (if exists and not empty)
2. `ansible/inventory.yml` (fallback for developers)
## API Keys and Tokens
### Cloudflare API Token
Required for DNS-01 ACME challenges via Lego certificate automation:
1. Log into [Cloudflare Dashboard](https://dash.cloudflare.com)
2. Navigate to: My Profile → API Tokens → Create Token
3. Use the "Edit zone DNS" template
4. Configure permissions:
- Zone → DNS → Edit
- Zone → Zone → Read
5. Set zone resources to your domain
6. Copy the token and add to config:
```bash
auberge config set cloudflare_dns_api_token your-token
```
**Note**: IP whitelisting is optional (all IPs are allowed by default)
### Tailscale
Required for VPN mesh networking:
1. Generate auth key at [Tailscale Admin Console](https://login.tailscale.com/admin/settings/keys)
2. Set reusable and ephemeral flags as needed
3. Store the key:
```bash
auberge config set tailscale_authkey your-authkey
```
## Building
```bash
mise run build
# or
cargo build --release
```
Binary output: `target/release/auberge`
## Testing
```bash
cargo test
```
## Linting
```bash
mise run lint
# or separately
cargo clippy
ansible-lint
```
## VPS Provider Firewall
Before running bootstrap playbook, configure your VPS provider's firewall to allow your custom SSH port:
1. Check your SSH port: `auberge config get ssh_port`
2. Log into your VPS provider control panel (IONOS, DigitalOcean, Hetzner, etc.)
3. Add firewall rule to allow TCP traffic on your `ssh_port`
4. Save the rule
This prevents lockout when Ansible changes SSH from port 22 to your custom port.