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 toansible-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.