Permalink
March 27, 2020 16:01
March 27, 2020 16:01
March 30, 2020 13:44
March 27, 2020 16:01
March 27, 2020 16:01
March 31, 2020 09:43
March 31, 2020 09:43
March 31, 2020 09:52
March 31, 2020 09:43
March 31, 2020 09:43
April 8, 2020 11:10
March 31, 2020 09:43
April 5, 2020 04:58
March 31, 2020 09:43
March 27, 2020 16:01
Newer
100644
245 lines (185 sloc)
7.81 KB
1
<!--
2
COmanage Registry Docker documentation
3
4
Portions licensed to the University Corporation for Advanced Internet
5
Development, Inc. ("UCAID") under one or more contributor license agreements.
6
See the NOTICE file distributed with this work for additional information
7
regarding copyright ownership.
8
9
UCAID licenses this file to you under the Apache License, Version 2.0
10
(the "License"); you may not use this file except in compliance with the
11
License. You may obtain a copy of the License at:
12
13
http://www.apache.org/licenses/LICENSE-2.0
14
15
Unless required by applicable law or agreed to in writing, software
16
distributed under the License is distributed on an "AS IS" BASIS,
17
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18
See the License for the specific language governing permissions and
19
limitations under the License.
20
-->
21
22
# Simple Development Sandbox
23
24
Follow these steps to build and run a simple deployment of COmanage Registry
25
suitable for beginning COmanage Registry development.
26
27
* Complete all of the steps in
28
[Evaluating COmanage Registry using Docker](evaluation.md). Make sure you can
29
log into COmanage Registry but do not save any changes. Be sure to run
30
`docker compose down` so that no containers are left running.
31
32
* Create a directory somewhere to save the state of the COmanage Registry
34
35
```
36
sudo mkdir -p /srv/docker/var/lib/postgresql/data
37
```
38
39
On Mac OS you might instead do something like
40
41
```
42
mkdir -p $HOME/comanage-data/postgresql/data
43
```
44
45
* Clone the COmanage Registry repository somewhere, for example
46
47
```
48
cd $HOME
50
```
51
52
* Change directories into the repository you just
53
cloned and create some necessary files and set appropriate permissions:
54
55
```
56
cd comanage-registry
57
cp -a app/tmp.dist local/tmp
58
chmod -R o+rw local/tmp
59
```
60
61
* Tell git to ignore changes the container makes during startup:
62
63
```
64
git update-index --assume-unchanged app/Config/bootstrap.php
65
```
66
67
* Checkout the develop branch or any other branch you want to work
68
from (you probably do not want to work from master):
69
70
```
71
git checkout develop
72
```
73
74
* Edit the docker-compose.yml file you used previously and add three
75
volume bind mounts:
76
77
1. One volume will mount the directory you created in the above
78
step for saving the database state to the directory
79
`/var/lib/postgresql/data` inside the database container.
80
1. A second volume will mount the `app` directory from the COmanage
81
Registry repository clone you created to the
82
`/srv/comanage-registry/app` directory inside the
83
COmanage Registry container.
84
1. The third volume will mount the `local` directory from the
85
COmanage Registry repository clone to the
86
`/srv/comanage-registry/local` directory inside the COmanage
87
Registry container.
88
89
Below is an example. The details will depend where you create the
90
database state directory and the repository clone. Be sure to
91
adjust the volume mounts for your deployment.
92
93
```
94
version: '3.1'
95
96
services:
97
98
comanage-registry-database:
99
image: comanage-registry-postgres
100
volumes:
101
- /srv/docker/var/lib/postgresql/data:/var/lib/postgresql/data
102
103
comanage-registry:
104
image: "comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth"
105
volumes:
106
- /home/skoranda/comanage-registry/app:/srv/comanage-registry/app
107
- /home/skoranda/comanage-registry/local:/srv/comanage-registry/local
108
109
ports:
110
- "80:80"
111
- "443:443"
112
```
113
114
* Make sure the shell variable `COMANAGE_REGISTRY_VERSION` is still
115
set (see [Evaluating COmanage Registry using Docker](evaluation.md).)
116
117
* Start the services:
118
```
119
docker-compose up -d
120
```
121
122
* Browse to port 443 on the host, for example `https://localhost/`. You will have to
123
click through the warning from your browser about the self-signed certificate used
124
for HTTPS.
125
126
* Click `Login` and when prompted enter `registry.admin` as the username and `password`
127
for the password.
128
129
* Visit the [COmanage Developer Manual](https://spaces.at.internet2.edu/x/FYDVCQ) for
130
tips and suggestions as well as the [COmanage Coding Style](https://spaces.at.internet2.edu/x/l6_KAQ).
131
132
* To stop the services:
133
```
134
docker-compose stop
135
```
136
137
* To remove the containers and networks:
138
```
139
docker-compose down
140
```
141
142
### Adding more test users
143
144
The simple development sandbox uses
145
[standard HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication),
146
and in particular the
147
[Apache HTTP Server implementation of basic authentication](https://httpd.apache.org/docs/2.4/howto/auth.html).
148
The default user is `registry.admin` and the default password is `password`.
149
150
To add more test users begin by copying the default basic authentication file
151
from a running container to your file system, for example
152
153
```
155
```
156
157
Move that file to somewhere on your filesystem where you can use it as another
158
bind-mount volume for the COmanage Registry container, for example
159
160
```
161
mkdir -p /srv/docker/etc/apache2/
162
cp basic-auth /srv/docker/etc/apache2/basic-auth
163
```
164
165
Edit the docker-compose file and add the bind-mount for the `comanage-registry`
166
service, for example
167
168
```
169
volume:
170
- /srv/docker/etc/apache2/basic-auth:/etc/apache2/basic-auth
171
```
172
173
Edit the basic-auth file using the `htpasswd` command. For example
174
to add the user `skoranda` run
175
176
```
177
htpasswd /srv/docker/etc/apache2/basic-auth skoranda
178
```
179
180
Restart the services and you can now authenticate to COmanage Registry
181
using the username and password combination you added to the password
182
file.
183
184
Note that an authentication module used in production, like the
185
Shibboleth Service Provider (SP), often sets the "username" to a
186
more sophisticated value. For example, if the Shibboleth SP is configured
187
to consume eduPersonPrincipalName (ePPN) and populate that into
188
`REMOTE_USER` then the "username" might be a value like
189
`scott.koranda@uwm.edu`.
190
191
You can mock up the same behavior by simply adding the "username"
192
`scott.koranda@uwm.edu` with a password using the above technique.
193
194
### Mocking Apache CGI environment variables
195
196
Some COmanage Registry functionality, such as the
197
[Env Source](https://spaces.at.internet2.edu/x/swr9Bg)
198
Organizational Identity Source, requires that the Apache HTTP Server
199
set Apache CGI environment variables. These environment variables are
200
usually set by more sophisticated authentication modules like the
202
behavior using the
203
[SetEnv](https://httpd.apache.org/docs/2.4/mod/mod_env.html)
204
directive for Apache.
205
206
To mock up an environment variable begin by copying the default Apache
207
configuration file from a running container to your file system, for example
208
209
```
210
docker cp comanage-registry:/etc/apache2/sites-available/000-comanage.conf ./000-comanage.conf
211
```
212
213
Move that file to somewhere on your filesystem where you can use it as another
214
bind-mount volume for the COmanage Registry container, for example
215
216
```
217
mkdir -p /srv/docker/etc/apache2/
218
cp basic-auth /srv/docker/etc/apache2/sites-available/000-comanage.conf
219
```
220
221
Edit the docker-compose file and add the bind-mount for the `comanage-registry`
222
service, for example
223
224
```
225
volume:
226
- /srv/docker/etc/apache2/sites-available/000-comanage.conf:/etc/apache2/sites-available/000-comanage.conf
227
```
228
229
Edit the `000-comanage.conf` file and add a `SetEnv` directive, for example
230
231
```
232
SetEnv ENV_OIS_NAME_GIVEN Scott
233
SetEnv ENV_OIS_NAME_FAMILY Koranda
234
SetEnv ENV_OIS_MAIL skoranda@gmail.com
235
SetEnv ENV_OIS_EPPN scott.koranda@sphericalcowgroup.com
236
```
237
238
Restart the services and authenticate to COmanage Registry.
239
After authenticating COmanage Registry should "see" those
240
environment variables defined for the authenticated user.
241
242
243
### Important Notes
244
The instructions above are *not suitable for a production deployment*
245
since the deployed services use default and easily guessed passwords.