1. What you need
  2. Get Ansible playbooks and roles
  3. Configure playbook
  4. Run Ansible
  5. 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.