Browse Source

Merge pull request #240 from algooapy/fix/228/review_readme_md

Tracim 7 years ago
parent
commit
91c6a0510e

+ 10 - 6
.travis.yml View File

@@ -1,6 +1,9 @@
1 1
 sudo: false
2 2
 language: python
3
-python: "3.4"
3
+python:
4
+  - "3.4"
5
+  - "3.5"
6
+  - "3.6"
4 7
 
5 8
 env:
6 9
   - DB=postgres
@@ -13,8 +16,10 @@ addons:
13 16
 
14 17
 install:
15 18
   - cd tracim && python setup.py develop; cd -
19
+  - echo coveralls >> install/requirements.txt; echo
20
+  - cat install/requirements.postgresql.txt >> install/requirements.txt; echo
21
+  - cat install/requirements.mysql.txt >> install/requirements.txt; echo
16 22
   - pip install -r install/requirements.txt; echo
17
-  - pip install coveralls
18 23
 
19 24
 before_script:
20 25
   - cp ${TRAVIS_BUILD_DIR}/tracim/development.ini.base ${TRAVIS_BUILD_DIR}/tracim/development.ini
@@ -25,9 +30,8 @@ before_script:
25 30
   - sh -c "if [ '$DB' = 'postgres' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/\(sqlalchemy.url *= *\).*/\1postgresql:\/\/postgres:dummy@127.0.0.1:5432\/tracim_test?client_encoding=utf8/\" development.ini; fi"
26 31
 
27 32
   - sh -c "if [ '$DB' = 'mysql' ]; then mysql -e 'CREATE DATABASE tracim_test;'; fi"
28
-  - sh -c "if [ '$DB' = 'mysql' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/\(sqlalchemy.url *= *\).*/\mysql+oursql:\/\/root@localhost\/tracim_test/\" test.ini; fi"
29
-  - sh -c "if [ '$DB' = 'mysql' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/<replace_database_uri_here>/mysql+oursql:\/\/root@localhost\/tracim_test/\" development.ini; fi"
30
-  - sh -c "if [ '$DB' = 'mysql' ]; then pip install https://launchpad.net/oursql/py3k/py3k-0.9.4/+download/oursql-0.9.4.zip; fi"
33
+  - sh -c "if [ '$DB' = 'mysql' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/\(sqlalchemy.url *= *\).*/\mysql+pymysql:\/\/root@localhost\/tracim_test/\" test.ini; fi"
34
+  - sh -c "if [ '$DB' = 'mysql' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/<replace_database_uri_here>/mysql+pymysql:\/\/root@localhost\/tracim_test/\" development.ini; fi"
31 35
 
32 36
   - sh -c "if [ '$DB' = 'sqlite' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/\(sqlalchemy.url *= *\).*/\sqlite:\/\/\/tracim_test.sqlite/\" test.ini; fi"
33 37
   - sh -c "if [ '$DB' = 'sqlite' ]; then cd ${TRAVIS_BUILD_DIR}/tracim && sed -i \"s/<replace_database_uri_here>/sqlite:\/\/\/tracim.sqlite/\" development.ini; fi"
@@ -38,4 +42,4 @@ before_script:
38 42
 script: "cd ${TRAVIS_BUILD_DIR}/tracim && nosetests -c ${TRAVIS_BUILD_DIR}/tracim/test.ini -v --with-coverage --cover-package=tracim --cover-erase"
39 43
 
40 44
 after_success:
41
-- coveralls
45
+  - coveralls

+ 53 - 282
README.md View File

@@ -1,4 +1,4 @@
1
-[![Build Status](https://travis-ci.org/tracim/tracim.svg?branch=master)](https://travis-ci.org/tracim/tracim) [![Coverage Status](https://img.shields.io/coveralls/tracim/tracim.svg)](https://coveralls.io/r/tracim/tracim) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/tracim/tracim/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/tracim/tracim/?branch=master)
1
+[![Build Status](https://travis-ci.org/tracim/tracim.svg?branch=master)](https://travis-ci.org/tracim/tracim) [![Coverage Status](https://img.shields.io/coveralls/tracim/tracim.svg)](https://coveralls.io/r/tracim/tracim) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/tracim/tracim/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/tracim/tracim/?branch=master) [![PyPI](https://img.shields.io/pypi/pyversions/tracim.svg)](https://pypi.python.org/pypi/tracim)
2 2
 
3 3
 # Tracim - Introduction #
4 4
 
@@ -9,14 +9,14 @@ If you hesitate to install a wiki, a forum or a file management software, stop h
9 9
 With Tracim, you manage in the same place:
10 10
 
11 11
 - forum-like threads,
12
-- files and automatic versionning,
12
+- files and automatic versioning,
13 13
 - wiki-like pages for online information,
14 14
 
15 15
 All data offers:
16 16
 
17 17
 - information status: open / resolved / cancelled / deprecated
18
-- native versionning
19
-- comment threads making tracim knowledge-growth ready.
18
+- native versioning
19
+- comment threads making Tracim knowledge-growth ready.
20 20
 
21 21
 Join Tracim community : http://tracim.org
22 22
 
@@ -48,9 +48,9 @@ With Tracim, you centralize information, you can stay in touch by configuring yo
48 48
 
49 49
 ### Manage documents and files ###
50 50
 
51
-Traceability and versionning are very important for high-quality processes. Unfortunately, specialized software are hard to setup and to use.
51
+Traceability and versioning are very important for high-quality processes. Unfortunately, specialized software are hard to setup and use.
52 52
 
53
-Let's try Tracim ! You define access-control for each workspace and store documents and file there. Users can't delete information: everything is versionned and never deleted.
53
+Let's try Tracim ! You define access-control for each workspace and store documents and file there. Users can't delete information: everything is versioned and never deleted.
54 54
 
55 55
 The user interface is easy to use: it's based on the well-known folders and files explorer paradigm.
56 56
 
@@ -67,9 +67,9 @@ Tracim is licensed under the terms of the
67 67
 
68 68
 Tracim is a web application:
69 69
 
70
-* developed with python >=3.4.
70
+* developed with python 3.4, 3.5, 3.6
71 71
 * based on the [TurboGears](http://www.turbogears.org/) web framework.
72
-* relying on [PostgreSQL](http://www.postgresql.org/) or [MySQL](https://www.mysql.fr/) or [sqlite](https://www.sqlite.org/) as the storage engine.
72
+* relying on [PostgreSQL](http://www.postgresql.org/) or [MySQL](https://www.mysql.fr/) or [SQLite](https://www.sqlite.org/) as the storage engine.
73 73
 
74 74
 The user interface is based on the following resources and technologies:
75 75
 
@@ -107,292 +107,83 @@ Following the installation documentation below, you'll be able to run your own i
107 107
 
108 108
 # Installation #
109 109
 
110
-## Dependencies ##
110
+## Distribution dependencies ##
111 111
 
112
-_Note: the following information is for Debian. For other OS, adapt the package names._
112
+You'll need to install the following packages :
113 113
 
114
-You'll need to install the following packages on your Operating System:
114
+    sudo apt install git realpath redis-server \
115
+                     python3 python-virtualenv python3-dev python-pip  python-lxml \
116
+                     build-essential libxml2-dev libxslt1-dev zlib1g-dev
115 117
 
116
-    apt-get install git realpath python3 python-virtualenv python3-dev python-pip build-essential libxml2-dev libxslt1-dev python-lxml
118
+## Get the source ##
117 119
 
118
-You also need `redis-server` package if you want to send email in async mode.
120
+Get the sources from GitHub:
119 121
 
120
-## Database ##
122
+    git clone https://github.com/tracim/tracim.git
123
+    cd tracim/
121 124
 
122
-If you want use PostgreSQL as database engine:
125
+*Note: Now everything is documented to be executed from the tracim directory newly created.*
123 126
 
124
-    apt-get install postgresql-server-dev-all postgresql postgresql-client
127
+## Frontend dependencies ##
125 128
 
126
-Or if you want to use MySQL as database engine
129
+[//]: # ( from https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)
127 130
 
128
-    apt-get install mysql-server mysql-client libmysqlclient-dev
131
+Install `nodejs` by typing:
129 132
 
130
-Or if you want to use SQLite as database engine
133
+    curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
134
+    sudo apt install -y nodejs
131 135
 
132
-    apt-get install sqlite3
136
+Check that this went well by getting `npm` version:
133 137
 
134
-## Installation ##
138
+    npm -v
135 139
 
136
-### Get the source ###
140
+Then install frontend dependencies listed in the file `package.json`:
137 141
 
138
-Get the sources from github with git:
142
+    npm install
139 143
 
140
-    git clone https://github.com/tracim/tracim.git
141
-    cd tracim/
142
-
143
-*Note: Now everything is documented to be executed from the tracim directory newly created.*
144
+At last, compile frontend files:
144 145
 
145
-### Setting-up python virtualenv ###
146
+    npm run gulp-dev # for a development environment
147
+    # npm run gulp-prod # for a production environment
146 148
 
147
-_Reminder : Tracim is developed and tested using python3.4._
149
+## Tracim virtual environment ##
148 150
 
149
-We strongly recommend to use virtualenv as deployment environment. This ensure that there will be no conflict between system-wide python installation and Tracim required ones. To Create the virtual environment:
151
+Create a python virtual environment:
150 152
 
151 153
     virtualenv -p /usr/bin/python3.4 tg2env
152 154
 
153
-And to activate it in your terminal session (**all tracim command execution must be executed under this virtual environment**)):
155
+Activate it in your terminal session (**all tracim command execution must be executed under this virtual environment**):
154 156
 
155 157
     source tg2env/bin/activate
156 158
 
157
-To install tracim and it's dependencies:
159
+Install Tracim and its dependencies:
158 160
 
159 161
     cd tracim && python setup.py develop && cd -
160 162
     pip install -r install/requirements.txt
161 163
 
162
-**Note**: If you want to use MySQL database, please refer to Configuration/database schema note to install required package.
163
-
164
-## Database Setup ##
165
-
166
-### Minimalist introduction to PostgreSQL ###
167
-
168
-If you already use/know PostgreSQL, you can directly go to *Test the database access*.
169
-
170
-#### Allowing local connections on PostgreSQL ####
171
-
172
-PostgreSQL stores connections ahtorization in *pg\_hba.conf*
173
-
174
-Edit the pg_hba.conf file and check that connectionx from 127.0.0.1 are allowed using user/password. You should find the following line in the file:
175
-
176
-    # IPv4 local connections:
177
-    host    all             all             127.0.0.1/32            md5
178
-
179
-Note: on Debian, the *pg\_hba.conf* file is found at */etc/postgresql/9.1/main/pg\_hba.conf*
180
-
181
-If you changed the file, reload PostgreSQL:
182
-
183
-    service postgresql reload
184
-
185
-#### Creating a user and associated database ####
186
-
187
-You need a database and associated user/password.
188
-
189
-Tracim comes with a tool that will make this step easy : pgtool.
190
-
191
-    ~/tracim$ ./bin/pgtool help
192
-
193
-login as *postgres* user and run the follwoing commands (which are self explanatory)
194
-
195
-    ./bin/pgtool create_user tracimuser tracimpassword
196
-    ./bin/pgtool create_database tracimdb
197
-    ./bin/pgtool grant_all_privileges tracimdb tracimuser
198
-
199
-Notes :
200
-
201
-* in order to login as postgres user, su as root (with your password) then su postgres.
202
-* pgtool also offers options to delete users / databases. Run *./bin/pgtool help* for more information
203
-
204
-#### Test the database access ####
205
-
206
-So, now you have a database and an associated user/password.
207
-
208
-A good habit is to test things before to use them, that's why we want to test the database access now. This is easily done with tracim pgtool :
209
-
210
-    ./bin/pgtool test_connection tracimdb tracimuser tracimpassword 127.0.0.1
211
-
212
-The result is similar to the following :
213
-
214
-    PG # CONNECT TO DATABASE
215
-    ------------------------
216
-    server:     127.0.0.1
217
-    database:   tracimdb
218
-    username:   bibi
219
-
220
-                  now
221
-    -------------------------------
222
-     2014-11-10 09:40:23.306199+01
223
-    (1 row)
224
-
225
-In case of failure, you would get something like this:
226
-
227
-    PG # CONNECT TO DATABASE
228
-    ------------------------
229
-    server:     127.0.0.1
230
-    database:   tracimdb
231
-    username:   bibi
232
-
233
-    psql: FATAL:  password authentication failed for user "bibi"
234
-    FATAL:  password authentication failed for user "bibi"
235
-    ERRROR
236
-
237
-In this case, delete the user and database you previously created (using pgtool) and do it again. Do not forget to run the grant_all_rights command!
238
-
239
-### Minimalist introduction to MySQL ###
240
-
241
-## Create database ##
242
-
243
-Connect to mysql with root user (password has been set at "Installation" -> "Dependencies" chapter, when installing package)
244
-
245
-    mysql -u root -p
246
-
247
-Create a database with following command:
248
-
249
-    CREATE DATABASE tracimdb;
250
-
251
-Create a user with following command:
252
-
253
-    CREATE USER 'tracimuser'@'localhost' IDENTIFIED BY 'tracimpassword';
254
-
255
-And allow him to manipulate created database with following command:
256
-
257
-    GRANT ALL PRIVILEGES ON tracimdb . * TO 'tracimuser'@'localhost';
258
-
259
-Then flush privileges:
260
-
261
-    FLUSH PRIVILEGES;
262
-
263
-You can now quit mysql prompt:
264
-
265
-    \q
266
-
267
-## Configuration ##
268
-
269
-At this point, you have :
164
+## Configuration files ##
270 165
 
271
-* an installation of Tracim with its dedicated python3-ready virtualenv
272
-* a PostgreSQL/MySQL server and dedicated database (if you don't use sqlite)
273
-
274
-What you have to do now is to configure the application and to initialize the database content.
275
-
276
-### Create configuration ###
166
+Create configuration files for a development environment and for `WsgiDAV`:
277 167
 
278 168
     cp tracim/development.ini.base tracim/development.ini
169
+    cp tracim/wsgidav.conf.sample tracim/wsgidav.conf
279 170
 
280
-You can now edit the file and setup required files. Here are the main ones:
281
-
282
-#### Database access ####
283
-
284
-Configure database in the development.ini file. This is defined as sqlalchemy.url. There is an example value for PostgreSQL below:
285
-
286
-    sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb?client_encoding=utf8
287
-
288
-There is an example value for MySQL below (please refer to Configuration/database schema note to install required package):
289
-
290
-    sqlalchemy.url = mysql+oursql://tracimuser:tracimpassword@127.0.0.1/tracimdb
291
-
292
-There is an example value for SQLite below :
293
-
294
-    sqlalchemy.url = sqlite:///tracimdb.sqlite
295
-
296
-#### Listening port
297
-
298
-Default configuration is to listen on port 8080. If you want to adapt this to your environment, edit the .ini file and setup the port you want:
299
-
300
-    port = 8080
301
-
302
-#### Interface language
303
-
304
-The default language is English. You can change it to French by uncommenting the following line in the .ini file:
305
-
306
-    lang = fr
307
-
308
-#### SMTP parameters for resetpassword and notifications
309
-
310
-for technical reason, you have to configure SMTP parameters for rest password process and SMTP parameters for notifications in separate places.
311
-
312
-The reset password related parameters are the follwoing ones :
313
-
314
-    resetpassword.email_sender = tracim@mycompany.com
315
-    resetpassword.smtp_host = smtp.mycompany.com
316
-    resetpassword.smtp_port = 25
317
-    resetpassword.smtp_login = username
318
-    resetpassword.smtp_passwd = password
319
-
320
-The main parameters for notifications are the following ones:
321
-
322
-    email.notification.activated = true
323
-    email.notification.from.email = noreply@trac.im
324
-    email.notification.from.default_label = Tracim Notification
325
-    email.notification.smtp.server = smtp.mycompany.com
326
-    email.notification.smtp.port = 25
327
-    email.notification.smtp.user = username
328
-    email.notification.smtp.password = password
329
-
330
-#### Website ####
331
-
332
-You must define general parameters like the base_url and the website title which are required for home page and email notification links
333
-
334
-    website.title = My Company Intranet
335
-    website.base_url = http://intranet.mycompany.com:8080
336
-
337
-#### LDAP ####
338
-
339
-To use LDAP authentication, set ``auth_type`` parameter to "ldap":
171
+## Database schema ##
340 172
 
341
-    auth_type = ldap
173
+The last step before running the application is to initialize the database
174
+schema. This is done through the following command:
342 175
 
343
-Then add LDAP parameters
344
-
345
-    # LDAP server address
346
-    ldap_url = ldap://localhost:389
347
-
348
-    # Base dn to make queries
349
-    ldap_base_dn = dc=directory,dc=fsf,dc=org
350
-
351
-    # Bind dn to identify the search
352
-    ldap_bind_dn = cn=admin,dc=directory,dc=fsf,dc=org
353
-
354
-    # The bind password
355
-    ldap_bind_pass = toor
356
-
357
-    # Attribute name of user record who contain user login (email)
358
-    ldap_ldap_naming_attribute = uid
359
-
360
-    # Matching between ldap attribute and ldap user field (ldap_attr1=user_field1,ldap_attr2=user_field2,...)
361
-    ldap_user_attributes = mail=email
362
-
363
-    # TLS usage to communicate with your LDAP server
364
-    ldap_tls = False
365
-
366
-    # If True, LDAP own tracim group managment (not available for now!)
367
-    ldap_group_enabled = False
368
-
369
-You may need an administrator account to manage Tracim. Use the following command (from ``/install/dir/of/tracim/tracim``):
370
-
371
-    gearbox user create -l admin@admin.admin -p admin@admin.admin -g managers -g administrators
372
-
373
-Keep in mind ``admin-email@domain.com`` must match with LDAP user.
374
-
375
-#### Other parameters  ####
376
-
377
-There are other parameters which may be of some interest for you. For example, you can:
378
-
379
-* include a JS tracker like Piwik or Google Analytics,
380
-* define your own notification email subject
381
-* personalize notification email
382
-* personalize home page (background image, title color...)
383
-* ...
384
-
385
-### database schema ###
176
+    cd tracim && gearbox setup-app && cd -
386 177
 
387
-The last step before to run the application is to initialize the database schema. This is done through the following command:
178
+## Running the paste http server ##
388 179
 
389
-**Note**: If you want to use MySQL database, please install this pip package: ```pip install https://launchpad.net/oursql/py3k/py3k-0.9.4/+download/oursql-0.9.4.zip```
180
+    gearbox serve
390 181
 
391
-    cd tracim && gearbox setup-app && cd -
182
+While developing, the following command may be more convenient:
392 183
 
393
-## Running the server ##
184
+    gearbox serve --reload --debug
394 185
 
395
-### Running Tracim in standalone mode ###
186
+## Running the standalone server ##
396 187
 
397 188
 Now you can run the standalone server:
398 189
 
@@ -407,7 +198,8 @@ Which should result in something like this:
407 198
     13:53:50,862 INFO  [gearbox] Starting server in PID 11174.
408 199
     Starting HTTP server on http://0.0.0.0:8080
409 200
 
410
-You can now enter the application at [http://localhost:8080](http://localhost:8080) and login with admin user.
201
+You can now enter the application at
202
+[http://localhost:8080](http://localhost:8080) and login with admin user.
411 203
 
412 204
  * user : admin@admin.admin
413 205
  * password : admin@admin.admin
@@ -418,34 +210,13 @@ If admin user not created yet, execute following command:
418 210
 
419 211
 Enjoy :)
420 212
 
421
-### Running Tracim through Apache WSGI ###
422
-
423
-#### Dependencies ####
424
-
425
-Install dependencies:
426
-
427
-    apt-get install apache2 libapache2-mod-wsgi-py3
428
-
429
-#### WSGI configuration ####
430
-
431
-Example of Apache WSGI configuration. This configuration refers to productionapp.wsgi which is a copy of the file *app.wsgi* available in the repo. (this file has to be updated to match with your environment and installation)
432
-
433
-    <VirtualHost *:80>
434
-        ServerAdmin webmaster@tracim.mycompany.com
435
-        ServerName tracim.mycompany.com
436
-
437
-        WSGIProcessGroup tracim
438
-        WSGIDaemonProcess tracim user=www-data group=adm threads=4 python-path=/opt/traciminstall/tg2env/lib/python3.2/site-packages
439
-        WSGIScriptAlias / /opt/traciminstall/tracim/productionapp.wsgi
213
+# Going further #
440 214
 
441
-        #Serve static files directly without TurboGears
442
-        Alias /assets     /opt/traciminstall/tracim/tracim/public/assets
443
-        Alias /favicon.ico /opt/traciminstall/tracim/tracim/public/favicon.ico
215
+Here is additional documentation about configuring:
444 216
 
445
-        CustomLog /var/log/apache2/demotracim-access.log combined
446
-        ErrorLog /var/log/apache2/demotracim-error.log
447
-        LogLevel debug
448
-    </VirtualHost>
217
+ * [Apache](doc/apache.md)
218
+ * [PostgreSQL, MySQL and SQLAlchemy](doc/database.md)
219
+ * [Tracim](doc/setting.md)
449 220
 
450 221
 # Support and Community #
451 222
 

+ 31 - 0
doc/apache.md View File

@@ -0,0 +1,31 @@
1
+# Running Tracim through Apache WSGI #
2
+
3
+## Installation ##
4
+
5
+Install `Apache` `HTTP` server and its `WSGI` module:
6
+
7
+    sudo apt install apache2 libapache2-mod-wsgi-py3
8
+
9
+## Configuration ##
10
+
11
+Example of `Apache` `WSGI` configuration. This configuration refers to
12
+`productionapp.wsgi` which is a copy of the file `app.wsgi` available in the
13
+repo. (this file has to be updated to match with your environment and
14
+installation)
15
+
16
+    <VirtualHost *:80>
17
+        ServerAdmin webmaster@tracim.mycompany.com
18
+        ServerName tracim.mycompany.com
19
+
20
+        WSGIProcessGroup tracim
21
+        WSGIDaemonProcess tracim user=www-data group=adm threads=4 python-path=/opt/traciminstall/tg2env/lib/python3.2/site-packages
22
+        WSGIScriptAlias / /opt/traciminstall/tracim/productionapp.wsgi
23
+
24
+        #Serve static files directly without TurboGears
25
+        Alias /assets     /opt/traciminstall/tracim/tracim/public/assets
26
+        Alias /favicon.ico /opt/traciminstall/tracim/tracim/public/favicon.ico
27
+
28
+        CustomLog /var/log/apache2/demotracim-access.log combined
29
+        ErrorLog /var/log/apache2/demotracim-error.log
30
+        LogLevel debug
31
+    </VirtualHost>

+ 0 - 18
doc/apache.wsgi.example.txt View File

@@ -1,18 +0,0 @@
1
-<VirtualHost *:8888>
2
-    ServerName pod
3
-
4
-    WSGIProcessGroup pod
5
-    WSGIDaemonProcess pod user=www-data group=www-data threads=4 python-path=/home/daccorsi/sources/protos/pod/tg2env/lib/python3.2/site-packages
6
-    WSGIScriptAlias / /home/daccorsi/sources/protos/pod/pod/app.wsgi
7
-
8
-    #Serve static files directly without TurboGears
9
-    Alias /images     /home/daccorsi/sources/protos/pod/pod/pod/public/images
10
-    Alias /favicon.ico     /home/daccorsi/sources/protos/pod/pod/pod/public/favicon.ico
11
-    Alias /css        /home/daccorsi/sources/protos/pod/pod/pod/public/css
12
-    Alias /javascript /home/daccorsi/sources/protos/pod/pod/pod/public/javascript
13
-
14
-    CustomLog /var/log/apache2/pod-access.log combined
15
-    ErrorLog /var/log/apache2/pod-error.log
16
-    LogLevel info
17
-</VirtualHost>
18
-

+ 144 - 0
doc/database.md View File

@@ -0,0 +1,144 @@
1
+
2
+# Database #
3
+
4
+*Note: This page helps you setting up a **development** environment for `Tracim` and its ORM `SQLAlchemy` with `PostgreSQL` and `MySQL`. To set up a **production** environment, changing default database name, database user name and moreover its password is mandatory.*
5
+
6
+## PostgreSQL ##
7
+
8
+If you want to use `PostgreSQL` as database engine:
9
+
10
+    sudo apt install postgresql-server-dev-all postgresql postgresql-client
11
+
12
+### Minimalist introduction to PostgreSQL ###
13
+
14
+If you already use/know `PostgreSQL`, you can directly go to *Test the database access*.
15
+
16
+#### Driver ####
17
+
18
+Tracim uses the `psycopg2` driver between the `SQLAlchemy` ORM and the `PostgreSQL` RDBMS. Run the following command to install the right version:
19
+
20
+    pip install -r install/requirements.postgresql.txt
21
+
22
+#### Allowing local connections on PostgreSQL ####
23
+
24
+Debian `PostgreSQL` stores connections authorization in `/etc/postgresql/9.1/main/pg_hba.conf`. Edit this file and check that connection from `127.0.0.1` are allowed using user/password. You should find the following line in the file:
25
+
26
+    # IPv4 local connections:
27
+    host    all             all             127.0.0.1/32            md5
28
+
29
+If you changed the file, reload `PostgreSQL`:
30
+
31
+    service postgresql reload
32
+
33
+#### Creating a user and associated database ####
34
+
35
+You need a database and associated user/password. Tracim comes with `pgtool`, tool that will make this step easy:
36
+
37
+    ./bin/pgtool help
38
+
39
+Run the following self explanatory commands:
40
+
41
+    sudo su postgres
42
+    ./bin/pgtool create_user tracimuser tracimpassword
43
+    ./bin/pgtool create_database tracimdb
44
+    ./bin/pgtool grant_all_privileges tracimdb tracimuser
45
+    exit
46
+
47
+#### Test the database access ####
48
+
49
+So, now you have a database and an associated user/password. A good habit is to test things before to use them, that's why we want to test the database access. This is easily done with Tracim `pgtool`:
50
+
51
+    ./bin/pgtool test_connection tracimdb tracimuser tracimpassword 127.0.0.1
52
+
53
+The result is similar to the following :
54
+
55
+    PG # CONNECT TO DATABASE
56
+    ------------------------
57
+    server:     127.0.0.1
58
+    database:   tracimdb
59
+    username:   bibi
60
+
61
+                  now
62
+    -------------------------------
63
+     2014-11-10 09:40:23.306199+01
64
+    (1 row)
65
+
66
+In case of failure, you would get something like this:
67
+
68
+    PG # CONNECT TO DATABASE
69
+    ------------------------
70
+    server:     127.0.0.1
71
+    database:   tracimdb
72
+    username:   bibi
73
+
74
+    psql: FATAL:  password authentication failed for user "bibi"
75
+    FATAL:  password authentication failed for user "bibi"
76
+    ERRROR
77
+
78
+In this case, delete the user and database you previously created, using `pgtool`, and do it again. Do not forget to run the `grant_all_rights` command!
79
+
80
+## MySQL ##
81
+
82
+Or if you want to use `MySQL` as database engine
83
+
84
+    sudo apt install mysql-server
85
+
86
+### Minimalist introduction to MySQL ###
87
+
88
+#### Driver ####
89
+
90
+Tracim uses the `PyMySQL` driver between the `SQLAlchemy` ORM and the `MySQL` RDBMS. Run the following command to install the right version:
91
+
92
+    pip install -r install/requirements.mysql.txt
93
+
94
+#### Create database ####
95
+
96
+Connect to `MySQL` with root user (password has been set at "Installation" -> "Dependencies" chapter, when installing package)
97
+
98
+    mysql -u root -p
99
+
100
+Create a database with following command:
101
+
102
+    CREATE DATABASE tracimdb;
103
+
104
+Create a user with following command:
105
+
106
+    CREATE USER 'tracimuser'@'localhost' IDENTIFIED BY 'tracimpassword';
107
+
108
+And allow him to manipulate created database with following command:
109
+
110
+    GRANT ALL PRIVILEGES ON tracimdb . * TO 'tracimuser'@'localhost';
111
+
112
+Then flush privileges:
113
+
114
+    FLUSH PRIVILEGES;
115
+
116
+You can now quit `MySQL` prompt:
117
+
118
+    \q
119
+
120
+## SQLAlchemy settings ##
121
+
122
+In the file `tracim/development.ini`, search the lines corresponding to the `SQLAlchemy` database url parameter `sqlalchemy.url`. `SQLite` is the default active database and others should be commented.
123
+
124
+If you're willing to choose `PostgreSQL` or `MySQL`, comment the `sqlalchemy.url` line corresponding to `SQLite` and uncomment the one of your choice.
125
+
126
+For example with `PostgreSQL`, this should gives you:
127
+
128
+    sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb?client_encoding=utf8
129
+    # sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb
130
+    # sqlalchemy.url = sqlite:///tracimdb.sqlite
131
+
132
+Proceed as above for the file `tracim/tests.ini`, except that you need to reproduce these steps three times for each of the following entries:
133
+
134
+- [app:main]
135
+- [app:ldap]
136
+- [app:radicale]
137
+
138
+Again with `PostgreSQL`, this should gives you:
139
+
140
+    sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb_test?client_encoding=utf8
141
+    # sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb_test
142
+    # sqlalchemy.url = sqlite:///tracimdb_test.sqlite
143
+
144
+*Note: Do not copy the lines from the file `tracim/development.ini` to the file `tracim/tests.ini`, the database names aren't the same.*

+ 92 - 0
doc/setting.md View File

@@ -0,0 +1,92 @@
1
+# Setting #
2
+
3
+Here is a short description of settings available in the file `tracim/development.ini`.
4
+
5
+## Listening port ##
6
+
7
+Default configuration is to listen on port 8080. If you want to adapt this to your environment, edit the `.ini` file and setup the port you want:
8
+
9
+    port = 8080
10
+
11
+## Interface language ##
12
+
13
+The default language is English. You can change it to French by uncommenting the following line in the `.ini` file:
14
+
15
+    lang = fr
16
+
17
+## SMTP parameters for resetpassword and notifications ##
18
+
19
+For technical reason, you have to configure `SMTP` parameters for rest password process and `SMTP` parameters for notifications in separate places.
20
+
21
+The reset password related parameters are the following ones :
22
+
23
+    resetpassword.email_sender = tracim@mycompany.com
24
+    resetpassword.smtp_host = smtp.mycompany.com
25
+    resetpassword.smtp_port = 25
26
+    resetpassword.smtp_login = username
27
+    resetpassword.smtp_passwd = password
28
+
29
+The main parameters for notifications are the following ones:
30
+
31
+    email.notification.activated = true
32
+    email.notification.from.email = noreply@trac.im
33
+    email.notification.from.default_label = Tracim Notification
34
+    email.notification.smtp.server = smtp.mycompany.com
35
+    email.notification.smtp.port = 25
36
+    email.notification.smtp.user = username
37
+    email.notification.smtp.password = password
38
+
39
+## Website ##
40
+
41
+You must define general parameters like the `base_url` and the website title which are required for home page and email notification links
42
+
43
+    website.title = My Company Intranet
44
+    website.base_url = http://intranet.mycompany.com:8080
45
+
46
+## LDAP ##
47
+
48
+To use LDAP authentication, set `auth_type` parameter to `ldap`:
49
+
50
+    auth_type = ldap
51
+
52
+Then add LDAP parameters
53
+
54
+    # LDAP server address
55
+    ldap_url = ldap://localhost:389
56
+
57
+    # Base dn to make queries
58
+    ldap_base_dn = dc=directory,dc=fsf,dc=org
59
+
60
+    # Bind dn to identify the search
61
+    ldap_bind_dn = cn=admin,dc=directory,dc=fsf,dc=org
62
+
63
+    # The bind password
64
+    ldap_bind_pass = toor
65
+
66
+    # Attribute name of user record who contain user login (email)
67
+    ldap_ldap_naming_attribute = uid
68
+
69
+    # Matching between ldap attribute and ldap user field (ldap_attr1=user_field1,ldap_attr2=user_field2,...)
70
+    ldap_user_attributes = mail=email
71
+
72
+    # TLS usage to communicate with your LDAP server
73
+    ldap_tls = False
74
+
75
+    # If True, LDAP own tracim group managment (not available for now!)
76
+    ldap_group_enabled = False
77
+
78
+You may need an administrator account to manage Tracim. Use the following command (from ``/install/dir/of/tracim/tracim``):
79
+
80
+    gearbox user create -l admin@admin.admin -p admin@admin.admin -g managers -g administrators
81
+
82
+Keep in mind `admin-email@domain.com` must match with LDAP user.
83
+
84
+## Other parameters  ##
85
+
86
+There are other parameters which may be of interest to you. For example, you can:
87
+
88
+* include a JS tracker like Piwik or Google Analytics,
89
+* define your own notification email subject
90
+* personalize notification email
91
+* personalize home page (background image, title color...)
92
+* ...

+ 1 - 0
install/requirements.mysql.txt View File

@@ -0,0 +1 @@
1
+PyMySQL==0.7.11

+ 1 - 0
install/requirements.postgresql.txt View File

@@ -0,0 +1 @@
1
+psycopg2==2.5.4

+ 5 - 6
install/requirements.txt View File

@@ -17,11 +17,11 @@ WebTest==1.4.2
17 17
 alembic==0.8.4
18 18
 argparse==1.2.1
19 19
 backlash==0.0.7
20
-beautifulsoup4==4.3.2
20
+beautifulsoup4==4.4.0
21 21
 caldav==0.4.0
22 22
 cliff==1.8.0
23
-cmd2==0.6.7
24
-coverage==4.0b1
23
+cmd2==0.6.9
24
+coverage==4.4.1
25 25
 crank==0.7.3
26 26
 decorator==3.4.0
27 27
 gearbox==0.0.7
@@ -32,7 +32,6 @@ lxml==3.6.0
32 32
 nose==1.3.4
33 33
 pbr==0.10.0
34 34
 prettytable==0.7.2
35
-psycopg2==2.5.4
36 35
 py4j==0.10.1
37 36
 pyasn1==0.1.9
38 37
 pyparsing==2.0.3
@@ -40,7 +39,7 @@ python-dateutil==2.5.3
40 39
 python-editor==1.0.1
41 40
 python-ldap-test==0.2.1
42 41
 repoze.lru==0.6
43
-repoze.who==2.2
42
+repoze.who==2.3
44 43
 requests==2.10.0
45 44
 six==1.8.0
46 45
 speaklater==1.3
@@ -57,7 +56,7 @@ tw2.forms==2.2.2.1
57 56
 unicode-slugify==0.1.3
58 57
 vobject==0.9.2
59 58
 waitress==0.8.9
60
-who-ldap==3.1.0
59
+who_ldap==3.2.2
61 60
 -e git+https://github.com/algoo/wsgidav.git@py3#egg=wsgidav
62 61
 zope.interface==4.1.3
63 62
 zope.sqlalchemy==0.7.6

+ 3 - 1
package.json View File

@@ -4,7 +4,9 @@
4 4
   "description": "",
5 5
   "main": "",
6 6
   "scripts": {
7
-    "test": "echo \"Error: no test specified\" && exit 1"
7
+    "test": "echo \"Error: no test specified\" && exit 1",
8
+    "gulp-dev": "gulp dev",
9
+    "gulp-prod": "gulp prod"
8 10
   },
9 11
   "repository": {
10 12
     "type": "git",

+ 0 - 24
tracim/README.txt View File

@@ -1,24 +0,0 @@
1
-This file is for you to describe the pod application. Typically
2
-you would include information such as the information below:
3
-
4
-Installation and Setup
5
-======================
6
-
7
-Install ``pod`` using the setup.py script::
8
-
9
-    $ cd pod
10
-    $ python setup.py develop
11
-
12
-Create the project database for any model classes defined::
13
-
14
-    $ gearbox setup-app
15
-
16
-Start the paste http server::
17
-
18
-    $ gearbox serve
19
-
20
-While developing you may want the server to reload after changes in package files (or its dependencies) are saved. This can be achieved easily by adding the --reload option::
21
-
22
-    $ gearbox serve --reload --debug
23
-
24
-Then you are ready to go.

+ 3 - 2
tracim/development.ini.base View File

@@ -94,8 +94,9 @@ beaker.session.validate_key = 3283411b-1904-4554-b0e1-883863b53080
94 94
 # invalidate the URI when specifying a SQLite db via path name
95 95
 # sqlalchemy.url=postgresql://username:password@hostname:port/databasename
96 96
 # sqlalchemy.url=mysql://username:password@hostname:port/databasename
97
-# sqlalchemy.url = postgresql://tracim_user:tracim_user_password@127.0.0.1:5432/tracim?client_encoding=utf8
98
-sqlalchemy.url = <replace_database_uri_here>
97
+# sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb?client_encoding=utf8
98
+# sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb
99
+sqlalchemy.url = sqlite:///tracimdb.sqlite
99 100
 
100 101
 #echo shouldn't be used together with the logging module.
101 102
 sqlalchemy.echo = false

+ 9 - 1
tracim/setup.py View File

@@ -25,6 +25,14 @@ except ImportError:
25 25
     use_setuptools()
26 26
     from setuptools import setup, find_packages
27 27
 
28
+classifiers = [
29
+    "License :: OSI Approved :: GNU Affero General Public License v3",
30
+    "Programming Language :: Python",
31
+    "Programming Language :: Python :: 3.4",
32
+    "Programming Language :: Python :: 3.5",
33
+    "Programming Language :: Python :: 3.6",
34
+]
35
+
28 36
 testpkgs=['WebTest >= 1.2.3',
29 37
                'nose',
30 38
                'coverage',
@@ -39,7 +47,7 @@ install_requires=[
39 47
     "sqlalchemy",
40 48
     "alembic",
41 49
     "repoze.who",
42
-    "who-ldap==3.1.0",
50
+    "who_ldap>=3.2.1",
43 51
     "python-ldap-test==0.2.1",
44 52
     "unicode-slugify==0.1.3",
45 53
     "pytz==2014.7",

+ 9 - 3
tracim/test.ini View File

@@ -22,7 +22,9 @@ host = 127.0.0.1
22 22
 port = 8080
23 23
 
24 24
 [app:main]
25
-sqlalchemy.url =  postgresql://postgres:dummy@127.0.0.1:5432/tracim_test?client_encoding=utf8
25
+# sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb_test?client_encoding=utf8
26
+# sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb_test
27
+sqlalchemy.url = sqlite:///tracimdb_test.sqlite
26 28
 use = config:development.ini
27 29
 
28 30
 [app:main_without_authn]
@@ -30,7 +32,9 @@ use = main
30 32
 skip_authentication = True
31 33
 
32 34
 [app:ldap]
33
-sqlalchemy.url =  postgresql://postgres:dummy@127.0.0.1:5432/tracim_test?client_encoding=utf8
35
+# sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb_test?client_encoding=utf8
36
+# sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb_test
37
+sqlalchemy.url = sqlite:///tracimdb_test.sqlite
34 38
 auth_type = ldap
35 39
 ldap_url = ldap://localhost:3333
36 40
 ldap_base_dn = dc=directory,dc=fsf,dc=org
@@ -49,7 +53,9 @@ resetpassword.smtp_passwd =  fake
49 53
 use = config:development.ini
50 54
 
51 55
 [app:radicale]
52
-sqlalchemy.url =  postgresql://postgres:dummy@127.0.0.1:5432/tracim_test?client_encoding=utf8
56
+# sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb_test?client_encoding=utf8
57
+# sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb_test
58
+sqlalchemy.url = sqlite:///tracimdb_test.sqlite
53 59
 
54 60
 use = config:development.ini
55 61