# First Deployment
Detailed walkthrough of deploying Auberge for the first time.
## Prerequisites
- Auberge installed (`cargo install auberge`)
- A VPS with root access
- SSH key for VPS access
- (Optional) Cloudflare account for DNS
## Step 1: Add Your VPS
Add your VPS as a host:
```bash
auberge host add my-vps 203.0.113.10
```
You'll be prompted for:
- **SSH user**: Usually `root` for initial setup
- **SSH port**: Default is `22`
- **SSH key**: Optional, defaults to `~/.ssh/identities/{user}_{hostname}`
## Step 2: Generate SSH Key (Optional)
If you don't have an SSH key:
```bash
auberge ssh keygen --host my-vps
```
This creates a key at `~/.ssh/identities/root_my-vps`.
## Step 3: Bootstrap VPS
Before bootstrapping, set the required values:
```bash
auberge config init
auberge config set hostname my-vps
auberge config set admin_user_name yourname
auberge config set admin_user_email you@example.com
auberge config set ssh_port 22022
# Optional: only needed for Cockpit web console login
auberge config set admin_user_password your-linux-password
```
Then run the bootstrap playbook:
```bash
auberge ansible bootstrap --host my-vps --ip 203.0.113.10
```
This:
- Sets server hostname (from `hostname` in `config.toml`)
- Creates an admin user (optionally sets a Linux password if `admin_user_password` is configured)
- Disables root SSH login
- Changes SSH port (from `ssh_port` in `config.toml`)
- Configures basic security
**Important**: Configure your VPS provider's firewall to allow your custom SSH port before running bootstrap.
## Step 4: Configure
Initialize config and set required values:
```bash
auberge config init
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
```
See `config.example.toml` for all available options.
## Step 5: Deploy Full Stack
```bash
auberge deploy --all --host my-vps
```
This runs:
- Hardening (firewall, fail2ban)
- Infrastructure (Caddy, DNS)
- Applications (all services)
**Note**: Bootstrap is not included — run `auberge ansible bootstrap` separately (Step 3).
## Step 6: Verify DNS Records
DNS A records for app subdomains are created automatically during deployment. Verify they were provisioned:
```bash
auberge dns status
```
To manually create or re-sync all records (e.g. for apps without automatic provisioning):
```bash
auberge dns set-all --host my-vps
```
## Step 7: Verify Services
Check that services are running:
```bash
ssh user@my-vps 'systemctl status caddy php*-fpm freshrss'
```
Access services in your browser:
- `https://cal.yourdomain.com`
- `https://rss.yourdomain.com`
## Step 8: Create First Backup
```bash
auberge backup create --host my-vps
```
This backs up all application data locally.
## Troubleshooting
### Can't Connect via SSH After Bootstrap
Your VPS provider's firewall may be blocking the new SSH port. Log into the provider's control panel and allow the custom port.
### Services Not Starting
Check logs:
```bash
ssh user@my-vps 'journalctl -u php*-fpm -n 50'
```
### DNS Records Not Created
Verify Cloudflare API token has correct permissions:
- Zone → DNS → Edit
- Zone → Zone → Read
## Next Steps
- [Backup & Restore](../backup-restore/overview.md) - Regular backups
- [Running Playbooks](../deployment/running-playbooks.md) - Deploy specific services
- [CLI Reference](../cli-reference/auberge.md) - All commands