This is the Ansible repository for the FOSSGIS Server Admin Working group.
It contains provisioning playbooks for machines that are administrated by
the group.

Set up Ansible
==============

We require Ansible >= 2.9 and Python3. The latest Ubuntu and Debian
installations should come with appropriate versions. On your host machine
simply run:

    sudo apt install ansible

If the ansible is too old you can also install it with pip. In order to keep
your system-wide Python module installation clean, use a virtual environment:

    virtualenv --python python3 --system-site-packages _venv
    source _venv/bin/activate
    pip install ansible

If installing or running Ansible fails with strange exceptions, the dependencies
are too old. Delete your virtual environment and recreate it without
`--system-site-packages`.

You always need to run `source _venv/bin/activate` before using ansible when
installing with pip this way.

Deploying a new Host
====================

We use Debian 11 on all hosts. Make sure there is a base system on the host.

You first need to add the host in the inventory (`hosts.ini`). The host should
be listed with its short internal name and the full domain name in `ansible_host`.
For example:

    robinson ansible_host=robinson.openstreetmap.de

You also need to add the host (with its short name) to the functional groups.

Next you need to bootstrap the server, bringing the Debian packages up to date
and set up the admin users:

    ansible-playbook -l $SERVER_NAME bootstrap.yml

Now you can run the usual site.yml for deploying the software.

!!! Warning

    Setup of user accounts is not part of the standard setup of servers via
    `site.yml` to avoid accidental lockouts. If you want to change the admin
    accounts on a server, run `bootstrap.yml` again.

More Documentation
==================

Further documentation can be found in the `doc/` directory:

* [Setting up a webserver](doc/webservers.md)


Testing
=======

The repo contains configuration files for [Vagrant](https://www.vagrantup.com/)
that may be used to test playbooks during development. To use it, you need
to install Vagrant and the lib-virt provider:

    apt install vagrant vagrant-libvirt libvirt-daemon

Spin up the test machine:

    vagrant up

This spins up a Debian Bullseye machine and sets up accounts, so that Ansible
can access the machine via the root account.

> You can use the environment variables 
> - `VAGRANT_MEMORY` (default: 2048)
> 
> For Example: `VAGRANT_MEMORY=8192 vagrant up`
>
> If you like to use an `.env` file, you can add the plugin `vagrant-env` via `vagrant plugin install vagrant-env`. Whenever you run a Vagrant command it’ll load `.env` into `ENV`. When creating the `.env` file, you can use the `env_example` file as a guide.
>
> In any case: if no environment variable is created, the default value is used.

Next you need an inventory:

    ./init_vagrant_inventory.sh

This creates a file vagrant.ini with the right connection IP. Edit the file
to put the vagrant test machine into the group you want to test.

Now you can run the global playbook:

     ansible-playbook -i vagrant.ini site.yml

Additional hints:

* You may have to rerun `init-vagrant-inventory.sh` when you destroy and rebuild
  the Vagrant test machine to update the IP.
* If you are not in the admin user group, you can still run the playbook
  under the vagrant user: `ansible-playbook -i vagrant.ini -u vagrant site.yml`

Testing without the Private Data
================================

All playbooks should be written such that they can be run without access to
the private data. You can define drop in replacements for the data in your
`host_vars/vagrant.yml` file if need be. For example, you have to create the file `host_vars/vagrant.yml` and define the variable `acme__distribution_account` here.

Variable naming convention
==========================

Variables in ansible have two maybe unexpected properties, which make this convention necessary:

* Variables are globally visible, which means they need unique names. Otherwise, they will get unexpectedly overwritten.
* Variables are only merged on the top level. That means we use a flat hierachy to have flexiblity in overwriting variables.

Variables should be named as follows:

    <role/group>__<variable_name>

example:

    osrm__basedir: '/srv/osrm/'

License
=======

Playbooks are published under MIT license.