What you need
Get Ansible playbooks and roles
Configure playbook
Run Ansible
Use icktool

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 for more on how to use icktool.