# 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
