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 ```