Merge branch 'finish_move' into 'master'
[motion.git] / README.md
1 # Installation
2 Requires Python 3 and a running PostgreSQL installation.
3
4 For a productive environment use a nginx webserver.
5
6 To install:
7 ```
8 virtualenv -p python3 .
9 . bin/activate
10 pip install -r requirements.txt
11 ```
12 Then edit config.py.example into config.py with your database connection and web site settings
13
14 ## Development and debug
15
16 To debug-run linux:
17 ```
18 LANG=C.UTF-8 FLASK_DEBUG=1 FLASK_APP=motion.py flask run
19 ```
20
21 To debug-run windows:
22 ```
23 set LANG=C.UTF-8
24 set FLASK_DEBUG=1
25 set FLASK_APP=motion.py
26 flask run
27 ```
28
29 For unit testing use config values from config.py.example:
30 ```
31 python -m unittest tests/test_motion.py
32 ```
33
34 The database schema is automatically installed when the table "schema_version" does not exist and the application is started.
35
36 The following user rights can be granted:
37 - create: user is able to create a new motion
38 - vote: user is able to vote running motions
39 - cancel: user is able to cancel a running motion
40 - finish: user is able to close a running motion
41 - audit: user is able to see given votes of a finished motion
42 - proxyadmin: user is able to grant proxy rights for users
43
44 To grant right use the following (here with vote right as example):
45 - on all groups add "vote:*"
46 - on one given group add "vote:group1"
47 - on two given groups add "vote:group1 vote:group2"
48
49 # Usage
50
51 Within the motion content markdown can be used for formatting e.g. 
52 * To add a line break add two lines
53 * to enter a link use `[text](https://domain.tld/link)`
54
55 ## Settings for nginx
56
57 To control the access this map is used:
58
59 ```
60 map "$host:$ssl_client_serial:$ssl_client_i_dn" $motion_user_role {
61 "host.domain.tld:serialnumber:/issuername" 'username/create:* vote:* cancel:* audit:*';
62 ...
63 default "<invalid>/";
64 }
65 ```
66
67 example taken from motions.board.wpia.club:
68 ```
69 map "$host:$ssl_client_serial:$ssl_client_i_dn" $motion_user_role {
70 "motions.board.wpia.club:0a0000000a1234567890abcdef1234567890abcde:/CN=Orga 2019-2/O=TC InterimCA/OU=TC InterimCAs/C=AT" 'president/create:* vote:* cancel:* audit:*';
71 ...
72 default "<invalid>/";
73 }
74 ```
75
76
77 ## configuration
78 ```
79 listen 0.0.0.0:443 ssl;
80 listen [::]:443 ssl;
81 server_name host.domain.tld;
82 gzip on;
83 ssl_certificate /etc/ssl/private/host.domain.tld.crt;
84 ssl_certificate_key /etc/ssl/private/host.domain.tld.key;
85
86 ssl_client_certificate /etc/ssl/host.domain.tld.pem;
87 ssl_verify_client on;
88 ssl_verify_depth 4;
89 access_log /tmp/host.domain.tld.log motion-cert;
90
91 location / {
92 fastcgi_param QUERY_STRING $query_string;
93 fastcgi_param REQUEST_METHOD $request_method;
94 fastcgi_param CONTENT_TYPE $content_type;
95 fastcgi_param CONTENT_LENGTH $content_length;
96 fastcgi_param REQUEST_URI $request_uri;
97 fastcgi_param PATH_INFO $document_uri;
98 fastcgi_param REMOTE_ADDR $remote_addr;
99 fastcgi_param REMOTE_PORT $remote_port;
100 fastcgi_param SERVER_NAME $host;
101 fastcgi_param SERVER_PORT '443';
102 fastcgi_param SERVER_PROTOCOL 'https';
103 fastcgi_param USER_ROLES $motion_user_role;
104 fastcgi_pass unix:/motion-socket/motion.fcgi;
105 }
106 ```
107
108 # Configuration for a Jenkins Freestyle Project
109
110 ## Preconditions for Jenkins system
111
112 * Python 3 installed with:
113
114   python3 virtualenv python3-pip
115
116 * PostgreSQL server installed with motion database and database user
117
118
119 ## Add freestyle project
120
121 ### Source-Code-Management
122
123 Adjust Git settings
124
125 ### Build Environment
126
127 Add Bindings
128
129 Add Username and password (separated)
130
131 Enter username (DB_USER) and password (DB_PW) according to database credentials
132
133 ### Build
134
135 Add build step shell
136
137 Add the command
138
139 ```
140 rm -rf env
141 virtualenv -p python3 env
142 . env/bin/activate
143 pip3 install -r requirements.txt
144
145
146 cat > config.py << EOF
147 DATABASE="pq://IP-ADDRESS/motion"
148 USER="${DB_USER}"
149 PASSWORD="${DB_PW}"
150 EOF
151
152 python3 jenkins_job.py
153 ```
154
155 If an IPv6 address is used the following needs to be added to the script to fix a bug of the IPv6 literal translation:
156 (https://github.com/python-postgres/fe/issues/104)
157
158 ```
159 patch env/lib/python3*/site-packages/postgresql/versionstring.py <<EOF
160 diff --git a/postgresql/versionstring.py b/postgresql/versionstring.py
161 index ccb3953..2503013 100644
162 --- a/postgresql/versionstring.py
163 +++ b/postgresql/versionstring.py
164 @@ -15,7 +15,7 @@ def split(vstr : str) -> (
165     Split a PostgreSQL version string into a tuple
166     (major,minor,patch,...,state_class,state_level)
167     """
168 -   v = vstr.strip().split('.')
169 +   v = vstr.strip().split(' ')[0].split('.')
170  
171     # Get rid of the numbers around the state_class (beta,a,dev,alpha, etc)
172     state_class = v[-1].strip('0123456789')
173 EOF
174 ```
175
176 ### Post build actions
177
178 Add Publish JUnit test result report - test report XMLs
179
180 ```
181 python_tests_xml/*
182 ```
183
184 ## Add user via command line
185
186 For linux start with
187 ```
188 FLASK_APP=motion.py
189 ```
190
191 For windows start with
192 ```
193 set FLASK_APP=motion.py
194
195 ```
196
197 To add a user use this command
198 ```
199 flask create-user "email address" "host"
200
201 ```
202
203 The application will return a message for success.
204
205 To mask motions use this command
206 ```
207 flask motion_masking motionidentifier motionurl host"
208
209 ```
210
211 where:
212
213 * motionidentifier - the motion identifier or left part of it which should be cleaned
214 * motionurl - an url to a motion that is the reason for the cleanup
215 * host - host where the motions are located
216
217 The application will return a message for success.