From 50885b34a80e37608acbd7cb3918cfceb2538afa Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 16 Jun 2018 09:52:06 +0300 Subject: Add: installation instructions --- install.mdwn | 150 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 install.mdwn (limited to 'install.mdwn') diff --git a/install.mdwn b/install.mdwn new file mode 100644 index 0000000..e873599 --- /dev/null +++ b/install.mdwn @@ -0,0 +1,150 @@ +[[!meta title="Installing ick"]] + +[[!toc ]] + + +# What you need + +To install ick, you need: + +* a dedicated host (physical server or virtual machine) +* Debian 9 (stretch) installed on that host +* Python installed on that host +* root access on that host over ssh +* Ansible installed on a second machine, from which you can ssh in as + root to the ick host + + +# Get Ansible playbooks and roles + +The actual playbooks for ick are in the `ick2-ansible.git` repository. +They rely on some generic, reuseable roles in the `debian-ansible.git` +repository, so you need a copy of that as well. You'll also need the +Qvisqve source code to create encrypted client secrets for +authentication. + +* `git clone git://git.qvarnlabs.net/debian-ansible` +* `export ANSIBLE_ROLES_PATH="$(pwd)/debian-ansible-roles"` +* `git clone git://git.liw.fi/ick2-ansible` +* `git clone git://git.qvarnlabs.net/qvisqve` +* `git clone git://git.qvarnlabs.net/ick2` +* `cd ick2-ansible` + + +# Configure playbook + +The `ick-ansible2` Ansible playbooks use Ansible variables for +anything that you will likely want to configure for your site. The +`liw.yml` file has a commented example. Make a copy of that and change +anything you need to change. + +The example uses the `pass` command to extract secrets from a +PGP-encrypted repository of secrets. Unless you have that set up +already, you can just give the un-encrypted secret in the variables +file to try out ick, although you may want to find a better way for +the future. + +You will need to generate some of the secrets: + +* an APT repository signing key, using PGP +* a worker SSH key (shared between all workers) +* at least one Qvisqve client secret hash and salt (ideally for each + worker) +* optionally, a self-signe TLS certificate, unless you use Let's + Encrypt (instructions for generating that would be nice, please + help) + +## Generate an APT repository signing key + +* `gpg --full-gen-key` and answer the questions. RSA is a good key + format for this. Any key length will do. Give the key a name that is + easily distinguishable. Don't give it a passphrase. + +* `gpg --armor --export ICKAPTKEY > apt.key.pub` + +* `gpg --armor --export-secret-key ICKAPTKEY > apt.key` + +* `cat apt.key.pub | gpg --with-colons | grep "^fpr:" | cut -d: -f10') }}` + +You need to insert the contents of `apt.key` and `apt.key.pub` as the +valuess of `apt_signing_key` and `apt_signing_key_pub` variables, and +the key fingerprint as the value of `apt_signing_key_fingerprint`. + +## Generate SSH key for workers + +* `ssh-keygen -N '' -f worker.key` + +You need to insert the contents of `worker.key` and `worker.key.pub` as the +valuess of `wm_ssh_key` and `wm_ssh_key_pub` variables. + +## Generate Qvisqve client secret hash and salt + +* `./qvisqve-hash` + +This will ask you for the client secret, and output a few lines of +output. From that output extract `hash` and `salt` and insert them as +the values of `qvisqve_worker1_hash` and `qvisqve_worker1_salt`. Also +insert the cleartext of the secret you gave to `qvisqve_hash` as +`worker_secret`. + +If you have more workers (up to 4, for now), set the corresponding +`qvisqve_workerN_hash` and `qvisqve_workerN_salt` to the same values +as for worker1. + +You also need to set the variables `qvisqve_admin_hash` and +`qvisqve_admin_salt` and you should run `qvisqve-hash` separately for +that, giving it a different secret than for the workers. You will be +using this secret to interact with ick yourself. + + +# Run Ansible + +* Create a file called `hosts` with contents like the following: + + ick ansible_ssh_host=addr.ess + + Change `addr.ess` to be the actual address. It can be a numeric + address, or a domain name. If you enable Let's Encrypt certificates, + you'll need to use a domain name. + + Note that this hosts file MUST have exactly the form above. Don't + add anything else. It will be processed by the `run-single.sh` + script before given to `ansible-playbook`. + +* `./run-aingle hosts` + + This will take a long while to run, but you will, at the end, have a + working ick instance. + +## Configure icktool + +* Create `~/.config/icktool/icktool.yaml`: + + config: + controller: https://addr.ess + + The address should be the same as in your `hosts` file above. + +* Create `~/.config/icktool/credentials.conf`: + + [https://addr.ess/token] + client_id = admin + client_secret = ADMINSECRET + + You need to give the admin secret here. + + +# Use icktool + +* `cd ick2` +* `./icktool status` + +This should give output like the following: + + project | build_status | log_id + ------- | ------------ | ------ + +If you did not use Let's Encrypt, you may need to give `icktool` the +`--no-verify-tls` option. + +If there's an error, something went wrong. -- cgit v1.2.1