auberge 0.9.0

CLI tool for managing self-hosted infrastructure with Ansible
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# auberge ansible run

Run Ansible playbooks on hosts

## Synopsis

```bash
auberge ansible run [OPTIONS]
```

## Alias

`auberge a r`

## Description

Executes Ansible playbooks on target hosts. Supports check mode (dry run), tag filtering, and interactive host/playbook selection.

**Important warnings are shown for**:

- bootstrap.yml: Provider firewall configuration required
- apps.yml: Cloudflare API token and port 853 configuration

## Config Validation

Before executing any playbook, the CLI validates required config values from `config.toml` and exits with an error if any are missing or empty.

| Playbook           | Required config keys                                    |
| ------------------ | ------------------------------------------------------- |
| bootstrap.yml      | `hostname`, `admin_user_name`, `ssh_port`               |
| hardening.yml      | (none)                                                  |
| infrastructure.yml | `admin_user_name`, `domain`, `tailscale_authkey`        |
| apps.yml           | `admin_user_name`, `domain`, `cloudflare_dns_api_token` |
| other playbooks    | `admin_user_name`, `domain`                             |

Example error output:

```
✗ Missing required config values:
✗   'admin_user_name' is required. Run: auberge config set admin_user_name <VALUE>
✗   'domain' is required. Run: auberge config set domain <VALUE>
Error: 2 required config value(s) missing in config.toml
```

## Automatic Dependency Resolution

When `--tags` is provided **without** `--playbook`, the CLI auto-resolves which playbooks need to run based on the tags:

- App tags (e.g., `paperless`, `baikal`) trigger `infrastructure.yml` first (full run, idempotent), then `apps.yml` with only the specified tags
- Infrastructure tags (e.g., `tailscale`, `caddy`) run only `infrastructure.yml` with those tags
- Mixed tags run both playbooks in order: infrastructure first, then apps

Specifying `--playbook` explicitly **bypasses** auto-resolution — only the named playbook runs.

## Options

| Option              | Description                                                                        | Default               |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------- |
| -H, --host HOST     | Target host                                                                        | Interactive selection |
| -p, --playbook PATH | Playbook path (bypasses auto-resolution when combined with `--tags`)               | Interactive selection |
| -C, --check         | Run in check mode (dry run)                                                        | false                 |
| -t, --tags TAGS     | Comma-separated tags to run (auto-resolves playbooks when `--playbook` is omitted) | All tasks             |
| --skip-tags TAGS    | Comma-separated tags to skip                                                       | None                  |
| -f, --force         | Skip confirmation prompts (for CI/CD)                                              | false                 |

## Examples

```bash
# Interactive mode (select host and playbook)
auberge ansible run

# Run specific playbook on specific host
auberge ansible run --host myserver --playbook ansible/playbooks/apps.yml

# Dry run (check mode)
auberge ansible run --host myserver --playbook ansible/playbooks/apps.yml --check

# Run with specific tags
auberge ansible run --host myserver --playbook ansible/playbooks/apps.yml --tags freshrss,baikal

# Auto-resolve: deploys full infrastructure first, then paperless from apps.yml
auberge ansible run --host myserver --tags paperless

# Explicit playbook: runs only apps.yml with the tag (no infra auto-deploy)
auberge ansible run --host myserver --playbook ansible/playbooks/apps.yml --tags paperless

# Skip confirmations (for automation)
auberge ansible run --host myserver --playbook ansible/playbooks/bootstrap.yml --force
```

## Bootstrap Warnings

When running bootstrap.yml, you'll see:

```
IMPORTANT: Provider Firewall Configuration Required
Before running bootstrap, ensure your VPS provider's firewall
allows your custom SSH port (separate from UFW on the VPS)

Required steps:
  1. Get your ssh_port: auberge config get ssh_port
  2. Log into your VPS provider dashboard (IONOS, etc.)
  3. Add firewall rule: Allow TCP on your ssh_port
  4. Save and confirm the rule is active

Without this, you'll be locked out after SSH port change!
```

## Apps Playbook Warnings

When running apps.yml:

**Cloudflare API Token**:

- Zone → Zone → Read
- Zone → DNS → Edit
- Set with: `auberge config set cloudflare_dns_api_token your-token`

**Port 853 (DNS over TLS)**:

- Must be opened in VPS provider firewall
- Required for Blocky DoT functionality

## Related Commands

- [auberge deploy](../deploy.md) - Deploy apps (recommended for app deployments)
- [auberge ansible bootstrap](bootstrap.md) - Bootstrap a new VPS
- [auberge select playbook](../select/playbook.md) - Select playbook interactively

## See Also

- [Ansible Playbooks](../../core-concepts/ansible.md)
- [Bootstrap Process](../../getting-started/bootstrap.md)
- [Applications](../../applications/README.md)