Index: main/waeup-ansible/README-vhosts.rst
===================================================================
--- main/waeup-ansible/README-vhosts.rst	(revision 14909)
+++ main/waeup-ansible/README-vhosts.rst	(revision 14909)
@@ -0,0 +1,135 @@
+=============================================
+ 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.
+
+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.
