auberge 0.12.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
135
136
137
138
139
140

# auberge ansible bootstrap

Bootstrap a fresh VPS with initial configuration

## Synopsis

```bash
auberge ansible bootstrap [OPTIONS] [HOST]
```

## Alias

`auberge a b`

## Description

Bootstraps a fresh VPS by running the bootstrap playbook with the bootstrap user (typically root). This is the first command to run on a new VPS before regular Ansible playbooks.

If `HOST` is omitted, you'll be prompted to select a host.

The bootstrap process:

1. Connects as bootstrap user (root) via password or SSH key
2. Creates ansible user with sudo privileges
3. Configures SSH hardening
4. Sets up firewall (UFW)
5. Changes SSH port to custom value

**Critical**: Ensure VPS provider firewall allows custom SSH port BEFORE running.

## Arguments

| Argument | Description                                        |
| -------- | -------------------------------------------------- |
| HOST     | Host name from configuration (omit to be prompted) |

## Options

| Option      | Description                        | Default            |
| ----------- | ---------------------------------- | ------------------ |
| --port PORT | SSH port for initial connection    | 22                 |
| --ip IP     | IP address (required with --force) | Interactive prompt |
| -f, --force | Skip confirmation prompts          | false              |

## Examples

```bash
# Interactive bootstrap (prompts for IP)
auberge ansible bootstrap myserver

# Fully interactive (prompts for host then IP)
auberge ansible bootstrap

# Specify IP address
auberge ansible bootstrap myserver --ip 192.168.1.10

# Custom initial SSH port
auberge ansible bootstrap myserver --port 22222 --ip 192.168.1.10

# Non-interactive mode (requires --ip)
auberge ansible bootstrap myserver --ip 192.168.1.10 --force
```

## Prerequisites

Before running bootstrap:

1. **Add host to configuration**:
   ```bash
   auberge host add myserver 192.168.1.10 --user ansible
   ```

2. **Configure bootstrap user in inventory**:
   The host must have `bootstrap_user` variable set (typically "root")

3. **VPS provider firewall**:
   ```bash
   # Get your custom SSH port
   auberge config get ssh_port

   # Add firewall rule in provider dashboard
   # Allow TCP on your ssh_port value
   ```

4. **Required config values**:
   The CLI validates `admin_user_name`, `hostname`, and `ssh_port` in `config.toml` before running. Set missing values with:
   ```bash
   auberge config set hostname <VALUE>
   auberge config set admin_user_name <VALUE>
   auberge config set ssh_port <VALUE>
   ```
   Optionally set `admin_user_password` for Cockpit web login:
   ```bash
   auberge config set admin_user_password <VALUE>
   ```

5. **Have initial access**:
   - Password access to bootstrap user, OR
   - SSH key already authorized for bootstrap user

## Bootstrap Flow

```
1. Connect as root@host:22 (default port)
2. Create ansible user
3. Configure SSH hardening
4. Change SSH port to custom value
5. Configure UFW firewall
6. Verify ansible user access
```

After bootstrap completes, subsequent commands use the ansible user and custom SSH port.

## Troubleshooting

**Locked out after bootstrap**:

- Cause: Provider firewall not configured
- Fix: Add firewall rule in provider dashboard, reboot VPS

**IP validation fails**:

- Ensure valid IPv4 (e.g., 192.168.1.10) or IPv6 format

**Bootstrap playbook not found**:

- Ensure in project root with ansible/ directory
- Path should be: ansible/playbooks/bootstrap.yml

## Related Commands

- [auberge host add](../host/add.md) - Add host before bootstrapping
- [auberge ansible run](run.md) - Run playbooks after bootstrap
- [auberge ssh keygen](../ssh/keygen.md) - Generate SSH keys

## See Also

- [Bootstrap Guide](../../getting-started/bootstrap.md)
- [SSH Setup](../../getting-started/ssh-setup.md)
- [Firewall Configuration](../../core-concepts/security.md)