f6d4c4e2186f10a1bc4d53e996831cc584a51980
[tools/hiccup/hiccup-server.git] / README.md
1 # Hiccup Server
2
3 Hiccup is intended to help Fairphone to assess the stability of the Fairphones in the field.
4 The Server side consists of two django projects: crashreports and crashreports_stats.  The former
5 implements the API endpoints for collecting crash reports, while the later implements the
6 front-end and some endpoints to access statics.
7
8 ## Setup
9
10 Python 3.6 is the only supported python version for the server code. Use this
11 version for development. It is the default version in Ubuntu 18.04, if you
12 run another OS, it is still possible to get python 3.6 (see for example
13 https://askubuntu.com/a/865569).
14
15 Make sure you have installed `python3`, `virtualenv` and `libffi-dev`.
16
17     $ sudo apt install python3 virtualenv libffi-dev
18
19 Clone Hiccup server and install it locally:
20
21     $ git clone ssh://$USER@review.fairphone.software:29418/tools/hiccup/hiccup-server
22     $ cd hiccup-server
23     $ virtualenv -p python3.6 .venv/hiccupenv
24     $ source .venv/hiccupenv/bin/activate
25     (hiccupenv) $ pip install -e .
26
27 When using a virtualenv with pyenv (e.g. to get python3.6 on Ubuntu 16.04),
28 the python executable needs to be explicitly named to make tox work (see
29 https://github.com/pyenv/pyenv-virtualenv/issues/202#issuecomment-284728205).
30
31     pyenv virtualenv -p python3.6 <installed-python-version> hiccupenv
32
33 i.e., because I have compiled python 3.6.6:
34
35     pyenv virtualenv -p python3.6 3.6.6 hiccupenv
36
37 #### Setting up PostgreSQL Server
38
39 The Hiccup server relies on a PostgreSQL database.
40
41 To set up a database server, you can install the following package:
42
43     (hiccupenv) $ sudo apt install postgresql
44
45 Then create a user and database:
46
47     (hiccupenv) $ sudo service postgresql start
48     (hiccupenv) $ sudo -u postgres createuser $USER --createdb
49     (hiccupenv) $ sudo -u postgres createdb -O $USER $USER
50
51 The settings for accessing the PostgreSQL server can be found in
52 `hiccup/settings.py` (see the `DATABASES` setting). When both the postgresql
53 server and the Hiccup server are running on the same machine and you are
54 using the same user that you used for creating the database for running the
55 server, the default settings should be fine. For all other cases a
56 `local_settings.py` file can be created in the project root directory to
57 overwrite the default settings.
58
59 Test that the configuration is correct:
60
61     (hiccupenv) $ python manage.py test
62
63 See the end of the next section to add a super-user.
64
65
66 ### Run Hiccup server
67
68 The first time you run the server, the database will be empty and the model migrations have yet to
69 happen:
70
71     (hiccupenv) $ python manage.py migrate
72
73 Then, at any later point, start the local server:
74
75     (hiccupenv) $ python manage.py runserver
76     ...
77     Starting development server at http://127.0.0.1:8000/
78     ...
79
80 The API is available at `localhost:8000/hiccup/` and the web-front-end at
81 `localhost:8000/hiccup_stats/`.
82
83 The Django admin web-front-end is at `localhost:8000/hiccup/admin`.
84
85 If you plan to browse through the Django admin web-front-end (`localhost:8000/hiccup/admin`), you
86 will need a super-user (admin) account:
87
88     (hiccupenv) $ python manage.py createsuperuser
89     ...
90     Superuser created successfully.
91
92 To browse  through the Hiccup front-end (`localhost:8000/hiccup_stats/`), the account you will
93 identify with should belong to the group `FairphoneSoftwareTeam`.
94
95 Run the following command or perform the manual steps below:
96
97     python manage.py shell -c "
98         from django.contrib.auth.models import Group, User
99         admin = User.objects.get(username='admin')
100         stats_group = Group.objects.get(name='FairphoneSoftwareTeam')
101         stats_group.user_set.add(admin)
102         "
103
104 * You need a running server and a super-user account;
105 * Go to the user list at `http://localhost:8000/hiccup/admin/auth/user/` and add your
106   super-user to the 'FairphoneSoftwareTeam' group.
107
108 ## API Documentation
109
110 The Hiccup REST API documentation is created automatically using
111 [drf_yasg](https://github.com/axnsan12/drf-yasg) and
112 [swagger2markup](https://github.com/Swagger2Markup/swagger2markup).
113
114 It can be generated using tox:
115
116     (hiccupenv) $ tox -e docs
117
118 The generated documentation file can be found under
119 `documentation/api-endpoints.md`.
120
121 It is also possible to create an HTML version of the docs. Make sure you
122 have asciidoctor installed:
123
124     (hiccupenv) $ sudo apt install asciidoctor
125
126 Then generate the html docs using tox:
127
128     (hiccupenv) $ tox -e docs-html
129
130 The generated documentation file can be found under
131 `documentation/api-endpoints.html`.
132
133
134 ## Development
135
136 ### Coding Style
137
138 We follow the
139 [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md).
140
141 ### Setup
142
143 We use tox to both test and validate the code quality:
144
145     (hiccupenv) $ pip install -r requirements-dev.txt
146
147 #### Testing
148
149 Simply run `tox` to test your changes in the supported environments:
150
151     (hiccupenv) $ tox
152
153 To get an overview of the test coverage run:
154
155     (hiccupenv) $ tox -e coverage
156
157 To generate HTML coverage reports (saved to `htmlcov/`):
158
159      (hiccupenv) $ tox -e coverage-html
160
161 #### Linters and Formatters
162
163 To run flake8 on only the diff with upstream:
164
165     (hiccupenv) $ git diff origin/master ./**/*py | flake8 --diff
166
167 We use the [black formatter](https://github.com/ambv/black) to check the
168 format of the code. To format a single file in place run:
169
170     (hiccupenv) $ black file.py
171
172 To run the formatter over all python files run:
173
174     (hiccupenv) $ git ls-files '*.py' | xargs black
175
176 Before committing a patchset, you are kindly asked to run the linting tools
177 ([flake8](http://flake8.pycqa.org/en/latest/) and
178 [pylint](https://pylint.readthedocs.io/en/latest/))
179 and format the code. For both linters and formatter, git pre-commit hooks
180 can be set up. To activate, copy the pre-commit script that calls all
181 scripts in `tools/hooks/pre-commit.d` to the `.git/hooks`
182 folder and make it executable:
183
184     (hiccupenv) $ cp tools/hooks/pre-commit .git/hooks/pre-commit
185     (hiccupenv) $ chmod +x .git/hooks/pre-commit
186
187 To prevent commits when the flake8 check fails the *strict* option can be
188 set to true:
189
190     (hiccupenv) $ git config --bool flake8.strict true
191
192 There is also a lint check included with tox (`tox -e linters`) but it is very
193 noisy at the moment since the codebase is not clean yet. Since you are already
194 validating the changes you are making with the git pre-commit hook, you are
195 all set to submit your change.
196
197
198 ### Branching structure
199
200 The `production` branch reflects the codebase currently running on the production server. New
201 changes should be pushed for review to the `master` branch. Every version that is merged into the
202 `master` branch has to be buildable. From there they can be merged into the `production` branch to
203 integrate the changes in the running server.
204
205
206 ## License
207
208 Copyright 2018 Fairphone B.V.
209
210 The project is made available under the terms of the Apache 2.0 license.
211 See [LICENSE](LICENSE) for details.