# Encrypted secrets in this project

Ansible Vault is the standard way to store and share secrets with this repo. Plain `.env` files are gitignored and meant only as a **temporary** import path on your machine.

## Recommended workflow

1. **Never commit** `.env`, API keys, or passwords.
2. Store secrets in `inventories/production/group_vars/all/vault.yml` (encrypted).
3. Edit with `make edit-group-vault` (uses `~/.ansible-vault-pass` on your workstation).
4. Teammates need the same vault password file out-of-band (password manager, not git).

## One-time import from `.env`

```bash
cp .env.example .env
# fill MAILCOW_API_KEY, ALERTS_PASSWORD, etc.
make vault-import-env
rm .env   # optional after import
```

`make vault-import-env` merges supported keys into the vault and re-encrypts the file.

## Mailcow mailboxes (dynamic)

| File | Purpose |
|------|---------|
| `group_vars/all/mailcow.yml` | Mailbox names, local parts, quotas (no secrets) |
| `vault.yml` | `vault_mailcow_api_key`, `vault_mailcow_mailbox_passwords` |

```bash
make mailcow-mailbox MAILBOX=alerts
```

Add a new mailbox:

1. In `mailcow.yml` under `mailcow_mailboxes:` add e.g. `notify: { local_part: notify, name: Notify, quota: 512, vault_password_key: notify }`
2. In vault: `vault_mailcow_mailbox_passwords.notify: "..."` (via `make edit-group-vault`)
3. `make mailcow-mailbox MAILBOX=notify`

## Can `.env` itself be encrypted?

Yes, but Ansible projects usually skip that pattern:

| Approach | Use when |
|----------|----------|
| **Ansible Vault** (`vault.yml`) | Default for this repo — works with playbooks and `make` targets |
| **`ansible-vault encrypt .env`** | Produces `.env` vault blob; you must `ansible-vault view .env` or decrypt to a temp file before tools read it — awkward for shell scripts |
| **Password manager / 1Password CLI** | Personal machine only, not for CI/ansible runs |
| **SOPS / Mozilla SOPS** | Teams that want encrypted YAML/JSON in git with KMS/PGP — heavier setup |

**Sharing encrypted secrets with others:** share the **vault password** (or per-host vault pass) securely once; they clone the repo and use the same encrypted `vault.yml`. Do not email `.env` files.

## Encrypting a single value (without opening the whole file)

```bash
ansible-vault encrypt_string 'secret-value' --name 'vault_my_secret' \
  --vault-password-file ~/.ansible-vault-pass
```

Paste the output into `vault.yml` inside the encrypted file, or into a vars file that is entirely vault-encrypted.