Configuration

Ansible tends to refer to remote servers as hosts. To avoid confusion with the Ansible control host we will refer to remote hosts as servers.

Add your server to inventory

Edit local/hosts.ini and add your server. There is an example server listed, feel free to remove this. Follow the example and give your server a friendly name (probably the same as its hostname) and specify its IP address.

Make sure your new server is part of the [setup] group as well as any other groups you’d like.

Modify group_vars

Group vars are applied to all servers in your inventory.

Edit group_vars/vars.yml and add your specific user account details and set the timezone.

The user account password in the vars file must be SHA-512 ($6$) hashes. To generate a password hash via the linux cli you’ll need the mkpasswd application, usually a part of the debian whois package. With that installed:

mkpasswd -m sha-512

You may add multiple user accounts here if you share administration of the server up to a maximum of 9 accounts (see Addendum note).

Modify host_vars for your server

host_vars is setup as a directory per server with per server vars files inside that. An example template server is provided for you to modify.

Rename examplecom directory to match your server’s name in hosts.ini. Further reference to this directory is as YOURSERVER.

Edit host_vars/YOURSERVER/main.yml to fit your environment - the user Ansible runs as, server name and IP. The template is largely self-documenting.

Your hetzner api token will need to be added to vault.yml. As you add variables you will find several in main.yml referenced using a Jinja2 template variable and prefixed with vault_. The hetzner api token is an example:

hetzner_api_token: "{{ vault_hetzner_api_token }}"

Set the token in host_vars/YOURSERVER/vault.yml and Ansible will read the value from your encrypted vault.

You will need to add an IPV6 address in addition to the IPV4. Or only an IPV6 address. (IPV6 only hosts are not currently possible see issue #40 for discussion.)

You should also generate an htpasswd entry for the Momod (homer) dashboard web site. (Or set dashboard_protect to false.)

Encrypt your vault

Once you’ve finished adding these initial variables to your vault.yml you should encrypt it - make sure you keep a note of your vault password in a safe place!

ansible-vault encrypt host_vars/YOURSERVER/vault.yml

If you need to add a new variable or edit an existing one you can do so by running:

ansible-vault edit host_vars/YOURSERVER/vault.yml

Which will open the vault.yml for editing in whichever editor your shell has defined.

The encrypted vault is safe to commit to a private git repository.

Configure DNS

Momod roles expect you to manage the DNS for the server itself at the VPS host - currently only at Hetzner. For your server’s Domain name set the nameservers to Hetzner and create a zone as described by Hetzner Docs.

The zone name should match “domain” set in host_vars/YOURSERVER/main.yml, ensure hostname, fqdn and wildcard_domain values are also set.

Generate a Hetzner DNS API token and add that in host_vars/YOURSERVER/vault.yml.

Momod will check for and configure A, AAAA and wildcard CNAME records during the main play but will not complain if they are already set.