[[!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
* Some Python stuff installed on your normal host:
    * cliapp (python3-cliapp from the code.liw.fi/debian APT
      repository)
    * python3-crypto
    * python3-cryptography
    * python3-cryptodome
    * python3-yaml
    * python3-requests
* optionally access to an SMTP server for sending notification mails
  (only needed if you want to send such mails), with username/password
  credentials as needed for SMTP authentication


# Get Ansible playbooks and roles

The actual playbooks for ick are in the `ick2-ansible.git` repository.
They rely on some generic, reusable 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.liw.fi/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
(`your.yml`) 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)
* a JWT token signing key for Qvisqve
* optionally, a self-signed 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`

* `gpg --with-colons --fingerprint ICKAPTKEY | grep "^fpr:" | head -1 | cut -d: -f10`

You need to insert the contents of `apt.key` and `apt.key.pub` as the
values 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
values of `wm_ssh_key` and `wm_ssh_key_pub` variables.

## Generate Qvisqve client secret hash and salt

* `../qvisqve/qvisqve-hash`

This will ask you for the client secret, and then output a few lines
of output. The secret is a shared secret, like a password, which the
admin user, or a worker host, and Qvisqve use to authenticate.

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.


## Generate a Qvisqve token signing key

* `../qvisqve/generate-rsa-key token.key`

This will generate files `token.key` (secret key) and `token.key.pub`
(public key). Put their contents as values for the variables
`qvisqve_token_private_key` (private) and `qvisqve_token_public_key`
(public).

# 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-single hosts -e @your.yml`

  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.

See [[Using icktool|icktool]] for more on how to use icktool.