summaryrefslogtreecommitdiff
path: root/install.mdwn
blob: 4e3a21a3916f4bc4b90b3e16b892a4fd64457763 (plain)
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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
[[!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.