1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
[[!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.
See [[Using icktool]] for more on how to use icktool.
|
