=============================================
 Playbooks for administrating WAeUP servers.
=============================================

This is the fine manual to survive basic setup of vagrant workers.


Setup a box and start it
========================

Become `vhosts` user on ``h8``. Then, create a home for the new VM and create a
first Vagrantfile. For the latter use existing instances as template.::

  vhosts@h8 $ mkdir vhost23
  vhosts@h8 $ cp vhost22/Vagrantfile vhost23/
  vhosts@h8 $ cd vhost23

Edit the new Vagrantfile and set virtual ip and SSH port to some yet unused
value. Also set the hostname to ``v23`` / ``v23.waeup.org`` respectively.
Ensure, that for now all public IPs and port forwardings are commented out (as
SSH on the new box is yet unsecured)::

  vhosts@h8/vhost23 $ vim Vagrantfle

Then, start the new VM::

  vhosts@h8/vhost23 $ vagrant up

and look out for the portnumber on which the new box is reachable from the
remote host. This will normally be 2222.


Enable SSH-key login from remote
================================

First create a new key for you::

    uli@home $ ssh-keygen -t ed25519 -C "uli@home to v23.waeup.org" -f ~/.ssh/idv23

and register the new key in SSH config (`~/.ssh/config`::

    Host v23 v23.waeup.org
        Hostname h8.waeup.org
        User ubuntu
        Port 2323
        IdentityFile /home/uli/.ssh/id_v23
        IdentitiesOnly yes

Again, please use the really used values, especially for the port number (must
be unique for each vhost) and User ("ubuntu" for vhosts running Ubuntu 16.04,
"vagrant" else).

The generated *public* key from `/home/uli/.ssh/id_v23.pub` can now be appended
to the new vagrant box in three steps::

  # 1 - copy to host server
  uli@home $ scp ~/.ssh/id_v23.pub h8:/home/uli
  # 2 - copy to vagrant box
  vhosts@h8 $ cp /home/uli/id_v23.pub ~/vhost23/
  vhosts@h8 $ cd ~/vhost23/
  # 3 - in vagrant box append to authorized_keys
  vhosts@h8 $ vagrant ssh
  ubuntu@v23 $ cat /vagrant/id_v23.pub >> ~/.ssh/authorized_keys

Now you should be able to login from home into the remote vagrant box.

To test this, we try to connect from home to the remove vhost, but, as we yet
have not secured SSH access, only through a tunnel that connects the remote
localhost:2222 to our home localhost:3333.::

  uli@home $ ssh -L 3333:localhost:2222 uli@h8.waeup.org

leave that shell open until we are done and make sure (in another terminal)
that we have something listening on the given port (here: 3333). In the next
step we will have to use that tunnel for first configuration steps.


Run ``vhost-bootstrap.yml``
===========================

In ``hosts`` add the new box in  the ``[yet_untouched]`` section::

  [yet_untouched]
  localhost:3333 ansible_user=ubuntu

and run the playbook::

  uli@home $ ansible-playbook -b -i hosts --private-key ~/.ssh/id_v23 vhost-bootstrap.yml

This should secure the new box. From now on, we can connect via the regular
ways. You can quit the open shell now and remove the ``[yet_untouched]`` entry
in ``hosts``.

Instead make a new entry in ``[bootstrapped]``::

  # hosts
  [yet_untouched]

  [bootstrapped]
  # ...
  v23.waeup.org:2342 ansible_user=ubuntu

  # ....

using the port number and hostname you plan to assign to the new box.


Make New Box Publicly Visible
=============================

As user `vhosts` edit the remote `Vagrantfile` and enable the settings of
``private_network`` and ``forwarded_port``. Then, reload::

  vhosts@h8 $ vagrant reload

Ensure, you can connect to the new box via the official hostname used::

  uli@home $ ssh v23.waeup.org

There will be warnings about changed host keys the first time you try to
reconnect. Edit `known_hosts` accordingly and retry until you can SSH-connect
to the new box without any problems.


Run ``vhost-setup.yml`` on the New Box
======================================

This is easy now:

  uli@home $ ansible-playbook -b -i hosts -l v23.waeup.org setup.yml


Finishing
=========

Finally, please move the hosts entry of the new box from the ``[bootstrapped]``
section over to the ``[[vhosts]`` section.