Installation and Activation¶

Inventory Variables¶

To enable Vault, CredentialAPI, and Portal Credential, add the following variables to your Ansible inventory:

# Enable CredentialAPI
CREDENTIAL_ENABLED: true

# IP restriction on the portal (optional)
CREDENTIAL_PORTAL_RESTRICT_IP:
   - name: siteA
     ip: 1.1.1.1
   - name: siteB
     ip: 192.168.1.0/24

# Enable Vault
VAULT_ENABLED: true

# Vault storage mode
# - "file" : single-node (recommended for dev/small infrastructures)
# - "raft" : HA cluster (recommended for prod, requires >=3 manager nodes)
VAULT_MODE: file

# Unseal mode
# - "manual"  : unseal via init.json keys (default)
# - "transit" : auto-unseal via another Vault
# - "awskms"  : auto-unseal via AWS KMS
VAULT_UNSEAL_MODE: manual

# Number of Shamir keys generated at init
VAULT_KEY_SHARES: 5

# Number of keys required to unseal
VAULT_KEY_THRESHOLD: 3

init.json file path¶

The init.json file (generated by Vault on first startup) is stored on the Ansible machine. Its default path is:

VAULT_INIT_FILE: "{{ playbook_dir }}/secrets/{{ INSTANCE_NAME }}/vault/init.json"

You can override this path in your inventory if needed.

First Deployment¶

On a fresh machine, run the full playbook:

ansible-playbook -i inventory.yml playbook/reemo-infra.yml

The playbook will:

Install/configure Docker and Swarm
Generate the Reemo PKI (CA + client/server certificates)
Deploy the Vault containers
Initialize Vault automatically (first run only)
Display the contents of init.json in the console output
Save init.json on the Ansible runner
Automatically unseal replicas
Create the CredentialAPI token in Vault (stored as Docker secret)
Deploy CredentialAPI, Portal Credential, and other services

init.json contents¶

The init.json file contains the critical elements for accessing Vault:

{
  "unseal_keys_b64": ["PUYWLruPMgw...", "OuhJ7B5hXr...", "TiQpJiv...", "8ZJ8sYM...", "Hb5xNyO..."],
  "unseal_keys_hex": ["3d46162ebb8f...", "3ae849ec1e61...", "4e242a262bfc...", "f1927cb1830c...", "1dbe7136e30f..."],
  "unseal_shares": 5,
  "unseal_threshold": 3,
  "root_token": "hvs.xxxxxxxxxxxxxxx"
}

unseal_keys_b64 / unseal_keys_hex: the 5 Shamir keys, in two equivalent formats (base64 and hexadecimal). By default 3 out of 5 are required to unseal Vault after each restart.
root_token: the full Vault admin token. Keep it secure, even though in practice you will no longer need it after the initial bootstrap.

Warning

This file is irreplaceable. Vault CANNOT regenerate it. If you lose it and Vault restarts, you permanently lose access to all your secrets.

Required action after the first run¶

At the end of the first run, you must immediately:

Back up the init.json file to a secure location (password manager, safe, encrypted offline backup).
Encrypt the local file with ansible-vault (see below).

Securing with ansible-vault¶

ansible-vault encrypts files at rest; the playbook decrypts them automatically at runtime.

Initial encryption¶

Immediately after the first run, encrypt the file:

ansible-vault encrypt playbooks/secrets/reemo/vault/init.json

Ansible prompts for a strong passphrase (which should also be saved in your password manager).

Note

The passphrase is different from the contents of init.json. Save both: the contents of init.json AND the ansible-vault passphrase.

Viewing and editing¶

ansible-vault view playbooks/secrets/reemo/vault/init.json
ansible-vault edit playbooks/secrets/reemo/vault/init.json
ansible-vault decrypt playbooks/secrets/reemo/vault/init.json

view: read-only
edit: temporary edit, re-encrypted on save
decrypt: permanent decryption — avoid

Providing the passphrase to the playbook¶

Three options:

Interactive prompt:

ansible-playbook -i inv playbook/reemo-infra.yml --ask-vault-pass

Passphrase file:

echo "my_passphrase" > ~/.ansible-vault-pass
chmod 600 ~/.ansible-vault-pass

Then during the run:

ansible-playbook -i inv playbook/reemo-infra.yml --vault-password-file ~/.ansible-vault-pass

Global config in ansible.cfg:

[defaults]
vault_password_file = ~/.ansible-vault-pass