# Tags

Tags allow selective execution of specific parts of playbooks without running everything.

## Overview

**Purpose:** Run only specific tasks/roles without executing entire playbook

**Syntax:**

```bash
auberge ansible run --tags tag1,tag2,tag3     # Comma-separated
auberge ansible run --skip-tags tag1,tag2
```

**Benefit:** Faster deployments, targeted updates

## Automatic Infrastructure Dependencies

When `--tags` is used **without** `--playbook`, the CLI auto-resolves playbook dependencies:

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

To run **only** the app playbook without infrastructure, specify `--playbook` explicitly:

```bash
# Auto-resolves: runs infrastructure.yml (full) + apps.yml --tags baikal
auberge ansible run --tags baikal

# Explicit: runs only apps.yml --tags baikal (no infrastructure)
auberge ansible run --playbook playbooks/apps.yml --tags baikal
```

## Tag Categories

Tags in Auberge are organized by:

- **Layer** (bootstrap, hardening, infrastructure, apps)
- **Component** (specific services/apps)
- **Category** (security, network, storage)

### Layer Tags

Run entire layers:

```bash
# Bootstrap layer only
auberge ansible run --tags bootstrap

# Hardening layer only
auberge ansible run --tags hardening

# Infrastructure layer only
auberge ansible run --tags infrastructure

# Applications layer only
auberge ansible run --tags apps
```

### Component Tags

#### Infrastructure Components

```bash
# SSH configuration
auberge ansible run --tags ssh

# Firewall (UFW)
auberge ansible run --tags ufw
auberge ansible run --tags firewall  # Alias

# Reverse proxy
auberge ansible run --tags caddy

# Package management
auberge ansible run --tags apt

# Shell environment
auberge ansible run --tags bash

# Intrusion prevention
auberge ansible run --tags fail2ban

# Kernel hardening
auberge ansible run --tags kernel_hardening
```

#### Application Components

```bash
# DNS + ad-blocking
auberge ansible run --tags blocky

# Calendar/contacts (CalDAV/CardDAV)
auberge ansible run --tags baikal

# RSS reader
auberge ansible run --tags freshrss

# Music streaming
auberge ansible run --tags navidrome

# Ebook library
auberge ansible run --tags calibre

# File sharing
auberge ansible run --tags webdav

# VPN
auberge ansible run --tags wireguard

# URL shortener
auberge ansible run --tags yourls
```

### Category Tags

Group related components:

```bash
# All security-related tasks
auberge ansible run --tags security

# All network-related tasks
auberge ansible run --tags network

# All storage/media apps
auberge ansible run --tags storage

# All web applications
auberge ansible run --tags web
```

## Tag Combinations

### Multiple Tags (OR Logic)

Run tasks with **any** of the specified tags:

```bash
# Run Baikal OR FreshRSS OR Navidrome
auberge ansible run --tags baikal,freshrss,navidrome
```

**Result:** All three applications deploy.

### Skip Tags

Run everything **except** specified tags:

```bash
# Run all apps except Navidrome
auberge ansible run --tags apps --skip-tags navidrome
```

### Combine Tags and Skip-Tags

```bash
# Run only apps, but skip Calibre
auberge ansible run --tags apps --skip-tags calibre
```

## Common Patterns

### Update Single Application

```bash
# Auto-resolves: runs full infrastructure first, then Baikal from apps.yml
auberge ansible run --host auberge --tags baikal

# Explicit: runs only Baikal tasks from apps.yml (no infrastructure)
auberge ansible run --host auberge --playbook playbooks/apps.yml --tags baikal
```

**Without `--playbook` (auto-resolve), what runs:**

- Full `infrastructure.yml` (idempotent — skips unchanged)
- Baikal installation, configuration, PHP-FPM pool, Caddy, data directory setup
- Service restart (if config changed)

**With `--playbook apps.yml` (explicit), what runs:**

- Baikal tasks only (no infrastructure)

**What never runs in either case:**

- Other applications
- Bootstrap/hardening layers

### Update Multiple Related Apps

```bash
# Update all media/storage apps
auberge ansible run --tags baikal,navidrome,calibre,webdav
```

### Update Infrastructure + One App

```bash
# Update Caddy and Baikal (e.g., after changing Caddy route)
auberge ansible run --tags caddy,baikal
```

### Security Updates Only

```bash
# Apply all security-related changes
auberge ansible run --tags security
```

**Includes:**

- fail2ban
- UFW
- SSH hardening
- Kernel hardening

### Full Deployment

```bash
# Deploy all apps (hardening + infrastructure + apps)
auberge deploy --all
```

## Tag Hierarchy

Some tags inherit others:

```
apps
├── blocky
├── calibre
├── freshrss
├── navidrome
├── baikal
├── webdav
├── wireguard
└── yourls
```

Running `--tags apps` executes all child application tags.

```
security
├── fail2ban
├── kernel_hardening
├── ufw
└── ssh
```

Running `--tags security` executes all security-related tasks.

## Tag Reference

### Complete Tag List

| Tag                | Layer     | Description          |
| ------------------ | --------- | -------------------- |
| `bootstrap`        | Layer     | Initial VPS setup    |
| `hardening`        | Layer     | Security hardening   |
| `infrastructure`   | Layer     | Core services        |
| `apps`             | Layer     | All applications     |
| `ssh`              | Component | SSH configuration    |
| `ufw`, `firewall`  | Component | UFW firewall         |
| `caddy`            | Component | Reverse proxy        |
| `apt`              | Component | Package management   |
| `bash`             | Component | Shell environment    |
| `fail2ban`         | Component | Intrusion prevention |
| `kernel_hardening` | Component | Kernel security      |
| `blocky`           | App       | DNS + ad-blocking    |
| `baikal`           | App       | CalDAV/CardDAV       |
| `freshrss`         | App       | RSS reader           |
| `navidrome`        | App       | Music streaming      |
| `calibre`          | App       | Ebook library        |
| `webdav`           | App       | File sharing         |
| `wireguard`        | App       | VPN                  |
| `yourls`           | App       | URL shortener        |
| `security`         | Category  | All security tasks   |
| `network`          | Category  | All network tasks    |
| `storage`          | Category  | All storage tasks    |
| `web`              | Category  | All web apps         |
| `users`            | Category  | User management      |
| `system`           | Category  | System configuration |

## Viewing Available Tags

List all tags in a playbook:

```bash
cd ansible && ansible-playbook playbooks/apps.yml --list-tags
```

**Example output:**

```
playbook: playbooks/apps.yml

  play #1 (vps): Bootstrap
    TAGS: [bootstrap, ssh, ufw]

  play #2 (vps): Hardening
    TAGS: [fail2ban, hardening, kernel_hardening, security]

  play #3 (vps): Infrastructure
    TAGS: [apt, bash, caddy, infrastructure]

  play #4 (vps): Applications
    TAGS: [apps, blocky, calibre, freshrss, navidrome, baikal, webdav, wireguard, yourls]
```

## How Tags Work

### Task-Level Tags

Most tasks have explicit tags:

```yaml
- name: Install Caddy
  ansible.builtin.get_url:
    url: https://...
    dest: /usr/local/bin/caddy
  tags: [infrastructure, caddy, web]
```

**Running `--tags caddy`:** This task executes

**Running `--tags infrastructure`:** This task executes

**Running `--tags apps`:** This task skipped

### Role-Level Tags

Roles are tagged when included:

```yaml
- role: baikal
  tags: [apps, baikal, storage, caldav]
```

**All tasks in the role inherit these tags.**

### Play-Level Tags

Entire plays can be tagged:

```yaml
- name: Bootstrap
  hosts: vps
  tags: [bootstrap]
  roles:
    - ansible_user
    - ssh
```

**All tasks and roles in the play inherit the tag.**

## Best Practices

### Use Tags for Incremental Updates

```bash
# Changed Baikal config → auto-resolves infra + Baikal
auberge ansible run --tags baikal

# App-only (skip infrastructure): specify --playbook explicitly
auberge ansible run --playbook playbooks/apps.yml --tags baikal
```

**Benefit:** Faster feedback loop during development. Use `--playbook` to skip infra when you know only app config changed.

### Skip Bootstrap in Production

Bootstrap is one-time setup. Use `auberge deploy` or `ansible run` with explicit playbooks to avoid re-running bootstrap tasks:

```bash
# Recommended: deploy command handles this automatically
auberge deploy --all

# Power-user: explicit playbook without bootstrap
auberge ansible run --playbook playbooks/apps.yml
```

### Combine with Check Mode

```bash
# Preview what would change
auberge deploy baikal --check

# If safe, apply
auberge deploy baikal
```

### Tag Application Groups

Update related apps together:

```bash
# All media apps
auberge ansible run --tags navidrome,calibre

# All productivity apps
auberge ansible run --tags baikal,freshrss
```

### Use Layer Tags for Major Updates

```bash
# Update all applications
auberge ansible run --tags apps

# Update all infrastructure
auberge ansible run --tags infrastructure
```

## Troubleshooting

### "No tasks matched"

No tasks have the specified tag.

**Fix:** Check tag spelling:

```bash
cd ansible && ansible-playbook playbooks/apps.yml --list-tags
```

### Unexpected Tasks Run

Task has multiple tags and matches your filter.

**Example:**

```yaml
- name: Configure UFW
  tags: [bootstrap, hardening, firewall, ufw]
```

Running `--tags hardening` includes this task (even though it's in bootstrap).

**Solution:** Use `--skip-tags` to exclude:

```bash
auberge ansible run --tags hardening --skip-tags bootstrap
```

### Handlers Not Running

Handlers only run if notifying task executed.

**Example:**

```bash
# Run only specific app
auberge ansible run --tags baikal
```

If Baikal config didn't change, restart handler won't run.

**Solution:** Manually restart if needed:

```bash
ssh ansible@auberge "sudo systemctl restart php*-fpm"
```

## Related Pages

- [Running Playbooks](deployment/running-playbooks.md) - Execution guide
- [Check Mode](deployment/check-mode.md) - Dry-run testing
- [Playbooks](core-concepts/playbooks.md) - Playbook structure
- [Infrastructure Layers](core-concepts/infrastructure-layers.md) - Layer dependencies
