Add: installation instructions

1 files changed, 150 insertions, 0 deletions

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.