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
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
|
git-refinery web interface
==========================
This is a small Django-based web application that is intended to help in
the preparation of software release notes. It enables you to browse through
commits in a git repository, add short notes on each commit and then gather
up those notes. You can also easily search and categorise commits.
There are two main methods of setting up this application - within
a set of Docker containers, or standalone. The Docker-based setup
is more suited for production whereas standalone is a bit easier
for development. This document will consider only the Docker-based
setup; for standalone please see README.devel.
Docker Setup
------------
The dockersetup.py script will set up and configure a cluster of 3
docker containers:
- gitrefineryapp: the application
- gitrefinerydb: the database
- gitrefineryweb: NGINX web server (as a proxy and for serving static content)
The script will edit all necessary configuration files, build and launch all
containers, and do the initial database setup.
1) Install docker and docker-compose per instructions:
https://docs.docker.com/compose/install/
** Note: for latest docker-compose version follow the directions above,
rather than using a perhaps outdated one provided by your distribution.
2) Run the setup script (dockersetup.py). You can optionally supply your
hostname, proxy settings, a sql database file of layer mappings to import,
and a host to container port mapping. For more information, run:
./dockersetup.py -h
Example command to run containers with a proxy:
./dockersetup.py -p http://<proxyserver>:<port>
NOTE: If you want email sending to work (required for user registration and
password resets), you should use the -e/--email-host option to specify your
outgoing email server.
3) Once the script completes, open a web browser and navigate to the URL
printed out by the script. By default that would be: https://localhost:8081
4) If you need to rerun this script for any reason a second time, you'll need
to choose between two modes:
A) Updating (-u/--update) - updates the code and runs any database upgrades
if applicable, or
B) Reinstalling (-r/--reinstall) - deletes the containers and reinstalls
from scratch. Be warned that this will throw away all data in the
database.
Note that updating with -u/--update will only work if the configuration
changes originally made by dockersetup.py upon installation (e.g. passwords,
hostname, etc.) are still present in the source tree.
TROUBLESHOOTING:
- Network issues behind a proxy when building container: On some systems
(particularly where dnsmasq is installed), /etc/resolv.conf is set to
127.0.0.x, rather than your local DNS server. Docker will look there for
your DNS server, and when it fails to find it it will default to using a
public one (frequently 8.8.8.8). Many corporate proxies blocks public DNS
servers, so you will need to manually supply the DNS server to docker using
/etc/docker/daemon.json:
{"dns": ["xx.xx.xx.xx] }
Usage
-----
1. Open the application (at http://127.0.0.1:8000/gitrefinery/ when running
a local test) and log in with the button at the top right if you haven't
already
2. Click "Add repository", enter the details and click "Save"
3. Click "Add release", enter the details and click "Save"
4. Click "Import release" and wait for the repository to be fetched - you
can see progress on the console if you're running the test server
5. You can click on individual shortlog links to expand to see the full
commit message. If you define some categories (using the admin interface),
then you can click on a category to add the commit to that category and
add notes specific to the category - these will appear in the final
release notes output under the category. If no notes are entered, the
commit shortlog will be used.
6. Enter notes for commits as desired. You can use the search functionality
to find commits, and label commits for easy searching later.
7. When finished, you can see the entire list of commit notes by clicking
on the "Review notes" button at the bottom of the page. If these are to
your satisfaction, just copy and paste to your release notes document,
and you're done!
Security Considerations
-----------------------
Some things to be aware of from a security perspective:
* By default, anyone can register themselves an account. If you wish to
disable new user registration and manage users manually through the admin
interface instead, then add the following line to docker/settings.py:
REGISTRATION_OPEN = False
Then, assuming you have already run dockersetup.py to install the
application, run the following command to update it:
./dockersetup.py -u
* By default, dockersetup.py enables connection to the web server via
HTTPS using a self-signed certificate; connections via HTTP are
re-directed to HTTPS. However, the self-signed certificate is only
intended to provide a minimum level of security, but will result in
browser warnings and is not recommended for production - instead,
obtain and use your own certificate/key pair corresponding to the
domain which will be used to access the application in production,
or alternatively if the application is accessible to the internet you
can use Let's Encrypt.
* Django supports several databases. By default, dockersetup.py sets up mariadb
for database and uses default settings from upstream. For production setup,
you might consider applying different rules or use your preferred
database.
https://docs.djangoproject.com/en/3.2/ref/databases/
* If you provide your own certificates for HTTPS, you should probably
also enable HSTS in your configuration. Refer to the Django Security
guide for details on how to do that:
https://docs.djangoproject.com/en/3.2/topics/security/#ssl-https
* To reset a forgotten account password, you can either use the password
reset function ( /accounts/password_reset/ ) or alternatively from the
backend you can run the following command:
docker-compose exec layersapp /opt/layerindex/manage.py changepassword <username>
* The web-based password reset function will ask the user answers to
security questions they selected and answered when they created the
account. Admins can configure the selectable security questions in
the admin interface under "Security questions"; however, be cautious
about deleting or substantially changing a question if you already
have user accounts that have given answers to that question, as doing
so will invalidate the user-set answers. You can check this if you go
to delete the security question in the admin interface - any user
answers will show up as "Security question answers" listed to be
deleted along with the question.
Note: the superuser created during setup will not have answers to
security questions set, so if you think you might need to use the
password reset function later you will need to set these by logging
into the application and then going to Edit Profile on the top-right
user drop-down menu.
* Security question answers are stored using the same mechanism as
for passwords, i.e. a secure one-way hash; thus answers cannot be
retrieved from the database once set. Additionally, if a user wants
to change one of their answers via the Edit Profile function, they
will be required to re-specify all of them.
* Account lockout: this application will lock out the user in two ways:
- By IP address (using django-axes) after too many invalid login attempts.
(default 3). The lockout can be removed using the following command:
docker-compose exec layersapp /opt/layerindex/manage.py axes_reset
If you wish to disable this, remove or comment out "axes" in
INSTALLED_APPS. For more information on configuring axes, see:
https://django-axes.readthedocs.io/en/latest/
- By account for too many incorrect password reset attempts. To remove
this lockout, log into the admin interface, go to Users, click on the
the user, tick the Active checkbox and then save.
Maintenance
-----------
The code for this application is maintained by the Yocto Project.
The latest version of the code can always be found here:
http://git.yoctoproject.org/cgit/cgit.cgi/git-refinery-web/
Contributions are welcome. Please send patches / pull requests to
yocto@yoctoproject.org with '[git-refinery-web]' in the subject.
License
-------
This application is based upon the Django project template, whose files
are covered by the BSD license and are copyright (c) Django Software
Foundation and individual contributors.
Bundled Bootstrap 3 (including Glyphicons) is redistributed under the
MIT license.
Bundled jQuery is redistributed under the MIT license.
Bundled JavaScript Cookie is redistributed under the MIT license.
All other content is copyright (C) 2014-2018 Intel Corporation and
licensed under the MIT license (unless otherwise noted) - see
COPYING.MIT for details.
Trademarks
----------
* Other names and brands may be claimed as the property of others.
|