README.md 7.95 KB
Newer Older
1
# snet-asclepios-deployment
James's avatar
James committed
2

3
4
5
6
Encrypted sleep research platform. This repositiory contains tools and definitions for provisioning and deploying the ASCLEPIOS project sleep healthcare demonstrator.

The deployed stack includes [XNAT](https://xnat.org/) with [snet-asclepios-plugin](https://gitlab.com/indie-sleep-demo/snet-asclepios-plugin), [snet-asclepios-editor](https://gitlab.com/indie-sleep-demo/snet-asclepios-editor) and [snet-asclepios-search](https://gitlab.com/indie-sleep-demo/snet-asclepios-search) along with a number of services from the ASCLEPIOS framework.

p.jbowden's avatar
p.jbowden committed
7
8
### Development and Deployment Dependencies

p.jbowden's avatar
p.jbowden committed
9
These dependencies (and others) can be installed by the `configure` script (see next section):
10

11
- `docker` and `docker-compose`
p.jbowden's avatar
p.jbowden committed
12
- optional: You may want skip the host depenency installation stage of the config script, and install any requirements using an alternative method. To do this, run this before proceeding to the next section: 
13
14

```
p.jbowden's avatar
p.jbowden committed
15
touch .configure.nohostdeps
16
```
p.jbowden's avatar
p.jbowden committed
17
- avoiding host dependency installation should allow you run run the `./configure` script as a non-root user 
Manish Kumar's avatar
Manish Kumar committed
18

19
### Running everything on a single node (for development)
p.jbowden's avatar
p.jbowden committed
20
1. Add the following to your local `/etc/hosts` file:
p.jbowden's avatar
p.jbowden committed
21

p.jbowden's avatar
p.jbowden committed
22
23
24
25
26
27
28
```
127.0.0.1 snet-apps.local
127.0.0.1 keycloak.snet-apps.local
127.0.0.1 registration-authority.snet-apps.local
127.0.0.1 keytray.snet-apps.local
127.0.0.1 zuul.snet-apps.local
127.0.0.1 xnat.snet-apps.local
29
30

127.0.0.1 minio
p.jbowden's avatar
p.jbowden committed
31
```
p.jbowden's avatar
p.jbowden committed
32

p.jbowden's avatar
p.jbowden committed
33
34
1. Run `export APP_HOST_NAME="snet-apps.local"`.
Note: export this to the root user's environment because the script in the next step requires root privileges. Alternatively, you can create the directory `.env.d` and put the value into the file `.env.d/APP_HOST_NAME`.
p.jbowden's avatar
p.jbowden committed
35
1. Run `sudo ./configure` and follow output until you get a green success message.
36
1. Run `docker network create snet-asclepios`
p.jbowden's avatar
p.jbowden committed
37
38
39
1. Run `./bin/dcall up -d` to bring up the whole stack.

### Running one of the modularized sets of services
p.jbowden's avatar
p.jbowden committed
40

p.jbowden's avatar
p.jbowden committed
41
1. Run `./bin/dcf docker-compose/<file>.yml up -d`
p.jbowden's avatar
p.jbowden committed
42
43
44
45
46
47

### SSL

1. optional: may want to enable TLS and get a SSL certificates for any applications that you are running on a public host

For this to work you will need to be running on a host which has port 80 and port 443 available on the public internet (for certbot)
48

p.jbowden's avatar
p.jbowden committed
49
50
51
52
```
mv docker-compose/notls-gateway.yml docker-compose/notls-gateway.yml.off
mv docker-compose/tls-gateway.yml.off mv docker-compose/tls-gateway.yml
docker network create snet-asclepios
p.jbowden's avatar
p.jbowden committed
53
54
./bin/dcf docker-compose/<file>.yml up -d
./bin/dcf docker-compose/docker-compose/tls-gateway up -d
p.jbowden's avatar
p.jbowden committed
55
```
56

jmz-b's avatar
jmz-b committed
57
58
### Set up Keycloak

59
60
61
You need to import `conf/realm-export.json` in order to provision the keycloak realm, but before you can do that you need to make a minor change the keycloak database schema, specifically, you need to modify the `USER_ATTRIBUTE.text` column to allow the storage of strings greater than 255 characters.

The change is necessary to faciliate the storage of cpabe keys as user attributes, as a cpabe key is usually more than 1000 characters in length.
jmz-b's avatar
jmz-b committed
62

63
- Execute the following command as root:
jmz-b's avatar
jmz-b committed
64
65

```sh
66
docker exec --env-file .env keycloak-db mysql --user="root" --password="$(cat .env.d/KEYCLOAK_DB_ROOT_PASSWORD)" --database=keycloak --execute='ALTER TABLE USER_ATTRIBUTE MODIFY value varchar(2000) CHARACTER SET utf8 COLLATE utf8_general_ci;
jmz-b's avatar
jmz-b committed
67
68
```

69
70
71
Now you can import the realm manually using the keycloak admin UI

* Open the Keycloak admin interface in a web browser.
72
- Log in with the credential output by `grep KEYCLOAK_ADMIN .env` to show the credentials for keycloak.
73
74
- Click `Add Realm` at the top left under `Master`
- Click `Import -> Select File` and select the file at `./conf/realm-export.json` in this repository
jmz-b's avatar
jmz-b committed
75

p.jbowden's avatar
p.jbowden committed
76
Next you will need to create a realm admin user so that you can use the Registration Authority
jmz-b's avatar
jmz-b committed
77

ilka.schulz's avatar
ilka.schulz committed
78
79
80
81
82
- Identify the admin user name as the value of `KEYCLOAK_REALM_ADMIN_USER` in `.env`
- Go to `Users->Add User` and create a new user with that exact name. You can click `Save` already.
- Run `cat .env.d/KEYCLOAK_REALM_ADMIN_PASSWORD` to retrieve the user's password.
- On the user screen go to `Credentials` and set the password to the value by output the previous command. Click `Save Password` now.
- On the user screen go to `Role Mappings` and assign the `admin` realm role by selected `Admin` from the `Available Roles` and clicking `Add selected`.
83
84
85
86
87
88
89
90

Optionally, you can provision the realm admin with a CPABE key using the following script:

```
python3 -m utils.init_realm_admin
usage: init_realm_admin.py [-h] username project
init_realm_admin.py: error: the following arguments are required: username, project
```
jmz-b's avatar
jmz-b committed
91

p.jbowden's avatar
p.jbowden committed
92
Finally, if you want to run the automated end-to-end tests, you need to set a password for the test runner.
James's avatar
James committed
93

94
95
- Run `grep TEST_KEYCLOAK .env` to view the user name and password for the test runner user.
- Go to `Users->View All Users` in the sidebar, and then for test runner user go to the `Credentials` tab and set the password to the value output by the previous command.
96

James's avatar
James committed
97

jmz-b's avatar
jmz-b committed
98
99
### Set up XNAT

p.jbowden's avatar
p.jbowden committed
100
XNAT's database is provisioned using a SQL dump. This SQL dump contains the default XNAT admin user, with the password 'admin' (just like on a default xnat installation).
101

102
103
104
105
* Open the XNAT admin interface in a web browser.
* Login with the credentials `username=admin,password=admin`
- Run `cat .env.d/XNAT_ADMIN_PASSWORD`
* Go to `Adminster -> Users -> admin -> Change Password` and set the password to value output by the previous command.
106

p.jbowden's avatar
p.jbowden committed
107
108
109
110
111
112
You can now use the admin user to create new projects and activtate new user accounts.

When creating a new project, you must add an ASCLEPIOS `keyid` field for subjects in the project. See `Manage Custom Variables` in the `asclepiostestproject` fixture for an example of how to do this.

### Adding new users

113
New users can be added to keycloak via the Registration Authority using the following utlity script. `role` should be one of `owner`, `member` or `collaborator`
p.jbowden's avatar
p.jbowden committed
114
115

```
116
117
$ python3 -m utils.init_realm_admin
usage: init_realm_admin.py [-h] username firstName lastName email project
p.jbowden's avatar
p.jbowden committed
118
119
120
121
```

* Once a user has been created, set there password to a tempory password in the keycloak admin interface.
* They can now attempt to log into XNAT using the `login with keycloak` button, they should get a registration successful message.
122
* An administrator must use the XNAT admin user to manually activate their account, and add them to the correct project.
p.jbowden's avatar
p.jbowden committed
123
124
125
126
127
128
129
130
131
132
133

### Adding a new data subject

* Provision a new set of subject keys and add a new subject to XNAT using the following utility script

```
python3 -m utils.create_subject
usage: create_subject.py [-h] label project
create_subject.py: error: the following arguments are required: label, project
```

134
### Browser Applications
135

jmz-b's avatar
jmz-b committed
136
You should now be able to access the following applications and login with keycloak:
jmz-b's avatar
jmz-b committed
137

p.jbowden's avatar
p.jbowden committed
138
139
* `snet-asclepios-editor` at `xnat.snet-apps.local/sn-editor
* `snet-asclepios-search` at `xnat.snet-apps.local/asclepios-search`
140
141
142

### Run tests

p.jbowden's avatar
p.jbowden committed
143
144
* There are some end-to-end style API tests in the `utils/e2e_tests` directory.
* Make sure you have set a password for the test runner (see "Set up Keycloak" above)
145
* You can run them with the following command:
146
147

```
p.jbowden's avatar
p.jbowden committed
148
./configure
p.jbowden's avatar
p.jbowden committed
149
python3 -m unittest utils.e2e_tests
150
```
ilka.schulz's avatar
ilka.schulz committed
151
152
153
154
155
156
157
158
159
160
161

### Continuous Deployment
- use GitLab
- enable CI/CD
- generate an RSA(!) SSH keypair locally
- under Project -> ``Settings -> CI/CD -> General Pipelines`:
  - use `git clone`
  - set shallow clone depth to `0`
  - add the SSH private key as `SSH_PRIVATE_KEY` to CI variables
- on target machine:
  - add the SSH public key to the user's `~/.ssh/authorized_keys`
162
  - allow passwordless sudo
163
  - create remote directory
ilka.schulz's avatar
ilka.schulz committed
164
165
166
  - run `git init` and `git config receive.denyCurrentBranch updateInstead
` from that directory
- in the `.gitlab-ci.yml`
167
168
  - add a job that `extends` `.deploy-template`
  - add all the necessary environment variables to the job, e.g. `SSH_UPLOAD_DIR`. The variables are listed in the template job's description.
ilka.schulz's avatar
ilka.schulz committed
169
  - consider adding an `only` keyword to restrict deployments, e.g. to the `master` branch
p.jbowden's avatar
p.jbowden committed
170
- make sure the runner can contact the target machine on TCP port 22