Bladeren bron

Closes #228: simplifies main README.md

Adrien Panay 7 jaren geleden
bovenliggende
commit
c656bb66fe
6 gewijzigde bestanden met toevoegingen van 307 en 340 verwijderingen
  1. 42 319
      README.md
  2. 31 0
      doc/apache.md
  3. 0 18
      doc/apache.wsgi.example.txt
  4. 136 0
      doc/database.md
  5. 92 0
      doc/setting.md
  6. 6 3
      tracim/test.ini

+ 42 - 319
README.md Bestand weergeven

@@ -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 to 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
 
@@ -69,7 +69,7 @@ Tracim is a web application:
69 69
 
70 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,330 +107,81 @@ Following the installation documentation below, you'll be able to run your own i
107 107
 
108 108
 # Installation #
109 109
 
110
-## Dependencies ##
110
+## Debian 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 python3 python-virtualenv python3-dev python-pip build-essential libxml2-dev libxslt1-dev python-lxml zlib1g-dev
115 115
 
116
-    apt-get install git realpath python3 python-virtualenv python3-dev python-pip build-essential libxml2-dev libxslt1-dev python-lxml zlib1g-dev
116
+To keep things simple for now, we'll use `SQLite3` as database engine:
117 117
 
118
-You also need `redis-server` package if you want to send email in async mode.
118
+    sudo apt install sqlite3
119 119
 
120
-## Frontend ##
120
+If you want to send email asynchronously:
121 121
 
122
-[//]: # ( from https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)
123
-
124
-Install nodejs by typing:
125
-
126
-    curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
127
-    sudo apt-get install -y nodejs
128
-
129
-Check that this went well by getting npm version:
130
-
131
-    npm -v
132
-
133
-## Database ##
134
-
135
-If you want use PostgreSQL as database engine:
122
+    sudo apt install redis-server
136 123
 
137
-    apt-get install postgresql-server-dev-all postgresql postgresql-client
124
+## Get the source ##
138 125
 
139
-Or if you want to use MySQL as database engine
126
+Get the sources from GitHub:
140 127
 
141
-    apt-get install mysql-server
128
+    git clone https://github.com/tracim/tracim.git
129
+    cd tracim/
142 130
 
143
-Or if you want to use SQLite as database engine
131
+*Note: Now everything is documented to be executed from the tracim directory newly created.*
144 132
 
145
-    apt-get install sqlite3
133
+## Frontend dependencies ##
146 134
 
147
-## Installation ##
135
+[//]: # ( from https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions)
148 136
 
149
-### Get the source ###
137
+Install `nodejs` by typing:
150 138
 
151
-Get the sources from github with git:
139
+    curl -sL https://deb.nodesource.com/setup_7.x | sudo -E bash -
140
+    sudo apt install -y nodejs
152 141
 
153
-    git clone https://github.com/tracim/tracim.git
154
-    cd tracim/
142
+Check that this went well by getting `npm` version:
155 143
 
156
-*Note: Now everything is documented to be executed from the tracim directory newly created.*
157
-
158
-### Frontend dependencies ###
144
+    npm -v
159 145
 
160
-To install frontend dependencies listed in the file package.json, proceed as follow:
146
+Then install frontend dependencies listed in the file `package.json`:
161 147
 
162 148
     npm install
163 149
 
164
-### Setting-up python virtualenv ###
150
+At last, compile frontend files:
165 151
 
166
-_Reminder : Tracim is developed and tested using python3.4, python3.5, python3.6._
152
+    npm run gulp-dev # for a development environment
153
+    # npm run gulp-prod # for a production environment
167 154
 
168
-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:
155
+## Tracim virtual environment ##
156
+
157
+Create a python virtual environment:
169 158
 
170 159
     virtualenv -p /usr/bin/python3.4 tg2env
171 160
 
172
-And to activate it in your terminal session (**all tracim command execution must be executed under this virtual environment**)):
161
+Activate it in your terminal session (**all tracim command execution must be executed under this virtual environment**):
173 162
 
174 163
     source tg2env/bin/activate
175 164
 
176
-To install tracim and it's dependencies:
165
+Install Tracim and its dependencies:
177 166
 
178 167
     cd tracim && python setup.py develop && cd -
179 168
     pip install -r install/requirements.txt
180 169
 
181
-## Database Setup ##
182
-
183
-### Minimalist introduction to PostgreSQL ###
184
-
185
-If you already use/know PostgreSQL, you can directly go to *Test the database access*.
186
-
187
-#### Allowing local connections on PostgreSQL ####
188
-
189
-PostgreSQL stores connections ahtorization in *pg\_hba.conf*
190
-
191
-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:
192
-
193
-    # IPv4 local connections:
194
-    host    all             all             127.0.0.1/32            md5
195
-
196
-Note: on Debian, the *pg\_hba.conf* file is found at */etc/postgresql/9.1/main/pg\_hba.conf*
197
-
198
-If you changed the file, reload PostgreSQL:
199
-
200
-    service postgresql reload
201
-
202
-#### Creating a user and associated database ####
203
-
204
-You need a database and associated user/password.
205
-
206
-Tracim comes with a tool that will make this step easy : pgtool.
207
-
208
-    ~/tracim$ ./bin/pgtool help
209
-
210
-login as *postgres* user and run the follwoing commands (which are self explanatory)
211
-
212
-    ./bin/pgtool create_user tracimuser tracimpassword
213
-    ./bin/pgtool create_database tracimdb
214
-    ./bin/pgtool grant_all_privileges tracimdb tracimuser
215
-
216
-Notes :
217
-
218
-* in order to login as postgres user, su as root (with your password) then su postgres.
219
-* pgtool also offers options to delete users / databases. Run *./bin/pgtool help* for more information
220
-
221
-#### Test the database access ####
222
-
223
-So, now you have a database and an associated user/password.
224
-
225
-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 :
226
-
227
-    ./bin/pgtool test_connection tracimdb tracimuser tracimpassword 127.0.0.1
228
-
229
-The result is similar to the following :
230
-
231
-    PG # CONNECT TO DATABASE
232
-    ------------------------
233
-    server:     127.0.0.1
234
-    database:   tracimdb
235
-    username:   bibi
236
-
237
-                  now
238
-    -------------------------------
239
-     2014-11-10 09:40:23.306199+01
240
-    (1 row)
241
-
242
-In case of failure, you would get something like this:
243
-
244
-    PG # CONNECT TO DATABASE
245
-    ------------------------
246
-    server:     127.0.0.1
247
-    database:   tracimdb
248
-    username:   bibi
249
-
250
-    psql: FATAL:  password authentication failed for user "bibi"
251
-    FATAL:  password authentication failed for user "bibi"
252
-    ERRROR
253
-
254
-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!
255
-
256
-### Minimalist introduction to MySQL ###
257
-
258
-#### Driver ####
259
-
260
-Tracim uses the PyMySQL driver between the SQLAlchemy ORM and the MySQL RDBMS.
261
-The only requirement is a pip installable package:
262
-
263
-    pip install PyMySQL
264
-
265
-#### Create database ####
266
-
267
-Connect to mysql with root user (password has been set at "Installation" -> "Dependencies" chapter, when installing package)
268
-
269
-    mysql -u root -p
270
-
271
-Create a database with following command:
272
-
273
-    CREATE DATABASE tracimdb;
274
-
275
-Create a user with following command:
276
-
277
-    CREATE USER 'tracimuser'@'localhost' IDENTIFIED BY 'tracimpassword';
278
-
279
-And allow him to manipulate created database with following command:
280
-
281
-    GRANT ALL PRIVILEGES ON tracimdb . * TO 'tracimuser'@'localhost';
282
-
283
-Then flush privileges:
284
-
285
-    FLUSH PRIVILEGES;
286
-
287
-You can now quit mysql prompt:
288
-
289
-    \q
170
+## Configuration files ##
290 171
 
291
-## Configuration ##
292
-
293
-At this point, you have :
294
-
295
-* an installation of Tracim with its dedicated python3-ready virtualenv
296
-* a PostgreSQL/MySQL server and dedicated database (if you don't use sqlite)
297
-
298
-What you have to do now is to configure the application and to initialize the database content.
299
-
300
-### Create configuration ###
172
+Create configuration files for a development environment and for `WsgiDAV`:
301 173
 
302 174
     cp tracim/development.ini.base tracim/development.ini
303
-
304
-You can now edit the file and setup required files. Here are the main ones:
305
-
306
-#### Database access ####
307
-
308
-Configure database in the development.ini file. This is defined as sqlalchemy.url. There is an example value for PostgreSQL below:
309
-
310
-    sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb?client_encoding=utf8
311
-
312
-There is an example value for MySQL below:
313
-
314
-    sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb
315
-
316
-There is an example value for SQLite below :
317
-
318
-    sqlalchemy.url = sqlite:///tracimdb.sqlite
319
-
320
-#### Listening port
321
-
322
-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:
323
-
324
-    port = 8080
325
-
326
-#### Interface language
327
-
328
-The default language is English. You can change it to French by uncommenting the following line in the .ini file:
329
-
330
-    lang = fr
331
-
332
-#### SMTP parameters for resetpassword and notifications
333
-
334
-for technical reason, you have to configure SMTP parameters for rest password process and SMTP parameters for notifications in separate places.
335
-
336
-The reset password related parameters are the follwoing ones :
337
-
338
-    resetpassword.email_sender = tracim@mycompany.com
339
-    resetpassword.smtp_host = smtp.mycompany.com
340
-    resetpassword.smtp_port = 25
341
-    resetpassword.smtp_login = username
342
-    resetpassword.smtp_passwd = password
343
-
344
-The main parameters for notifications are the following ones:
345
-
346
-    email.notification.activated = true
347
-    email.notification.from.email = noreply@trac.im
348
-    email.notification.from.default_label = Tracim Notification
349
-    email.notification.smtp.server = smtp.mycompany.com
350
-    email.notification.smtp.port = 25
351
-    email.notification.smtp.user = username
352
-    email.notification.smtp.password = password
353
-
354
-#### Website ####
355
-
356
-You must define general parameters like the base_url and the website title which are required for home page and email notification links
357
-
358
-    website.title = My Company Intranet
359
-    website.base_url = http://intranet.mycompany.com:8080
360
-
361
-#### LDAP ####
362
-
363
-To use LDAP authentication, set ``auth_type`` parameter to "ldap":
364
-
365
-    auth_type = ldap
366
-
367
-Then add LDAP parameters
368
-
369
-    # LDAP server address
370
-    ldap_url = ldap://localhost:389
371
-
372
-    # Base dn to make queries
373
-    ldap_base_dn = dc=directory,dc=fsf,dc=org
374
-
375
-    # Bind dn to identify the search
376
-    ldap_bind_dn = cn=admin,dc=directory,dc=fsf,dc=org
377
-
378
-    # The bind password
379
-    ldap_bind_pass = toor
380
-
381
-    # Attribute name of user record who contain user login (email)
382
-    ldap_ldap_naming_attribute = uid
383
-
384
-    # Matching between ldap attribute and ldap user field (ldap_attr1=user_field1,ldap_attr2=user_field2,...)
385
-    ldap_user_attributes = mail=email
386
-
387
-    # TLS usage to communicate with your LDAP server
388
-    ldap_tls = False
389
-
390
-    # If True, LDAP own tracim group managment (not available for now!)
391
-    ldap_group_enabled = False
392
-
393
-You may need an administrator account to manage Tracim. Use the following command (from ``/install/dir/of/tracim/tracim``):
394
-
395
-    gearbox user create -l admin@admin.admin -p admin@admin.admin -g managers -g administrators
396
-
397
-Keep in mind ``admin-email@domain.com`` must match with LDAP user.
398
-
399
-#### Other parameters  ####
400
-
401
-There are other parameters which may be of some interest for you. For example, you can:
402
-
403
-* include a JS tracker like Piwik or Google Analytics,
404
-* define your own notification email subject
405
-* personalize notification email
406
-* personalize home page (background image, title color...)
407
-* ...
408
-
409
-### WebDAV ###
410
-
411
-Create WsgiDAV configuration from the sample file:
412
-
413 175
     cp tracim/wsgidav.conf.sample tracim/wsgidav.conf
414 176
 
415
-### frontend files compilation ###
177
+## database schema ##
416 178
 
417
-Considering your environment, run:
418
-
419
-    npm run gulp-dev
420
-
421
-or
422
-
423
-    npm run gulp-prod
424
-
425
-### database schema ###
426
-
427
-The last step before to run the application is to initialize the database schema. This is done through the following command:
179
+The last step before running the application is to initialize the database
180
+schema. This is done through the following command:
428 181
 
429 182
     cd tracim && gearbox setup-app && cd -
430 183
 
431
-## Running the server ##
432
-
433
-### Running Tracim in standalone mode ###
184
+## Running the standalone server ##
434 185
 
435 186
 Now you can run the standalone server:
436 187
 
@@ -445,7 +196,8 @@ Which should result in something like this:
445 196
     13:53:50,862 INFO  [gearbox] Starting server in PID 11174.
446 197
     Starting HTTP server on http://0.0.0.0:8080
447 198
 
448
-You can now enter the application at [http://localhost:8080](http://localhost:8080) and login with admin user.
199
+You can now enter the application at
200
+[http://localhost:8080](http://localhost:8080) and login with admin user.
449 201
 
450 202
  * user : admin@admin.admin
451 203
  * password : admin@admin.admin
@@ -456,35 +208,6 @@ If admin user not created yet, execute following command:
456 208
 
457 209
 Enjoy :)
458 210
 
459
-### Running Tracim through Apache WSGI ###
460
-
461
-#### Dependencies ####
462
-
463
-Install dependencies:
464
-
465
-    apt-get install apache2 libapache2-mod-wsgi-py3
466
-
467
-#### WSGI configuration ####
468
-
469
-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)
470
-
471
-    <VirtualHost *:80>
472
-        ServerAdmin webmaster@tracim.mycompany.com
473
-        ServerName tracim.mycompany.com
474
-
475
-        WSGIProcessGroup tracim
476
-        WSGIDaemonProcess tracim user=www-data group=adm threads=4 python-path=/opt/traciminstall/tg2env/lib/python3.2/site-packages
477
-        WSGIScriptAlias / /opt/traciminstall/tracim/productionapp.wsgi
478
-
479
-        #Serve static files directly without TurboGears
480
-        Alias /assets     /opt/traciminstall/tracim/tracim/public/assets
481
-        Alias /favicon.ico /opt/traciminstall/tracim/tracim/public/favicon.ico
482
-
483
-        CustomLog /var/log/apache2/demotracim-access.log combined
484
-        ErrorLog /var/log/apache2/demotracim-error.log
485
-        LogLevel debug
486
-    </VirtualHost>
487
-
488 211
 # Support and Community #
489 212
 
490 213
 Building the community is a work in progress.

+ 31 - 0
doc/apache.md Bestand weergeven

@@ -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 Bestand weergeven

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

+ 136 - 0
doc/database.md Bestand weergeven

@@ -0,0 +1,136 @@
1
+
2
+# Database #
3
+
4
+## PostgreSQL ##
5
+
6
+If you want use `PostgreSQL` as database engine:
7
+
8
+    sudo apt install postgresql-server-dev-all postgresql postgresql-client
9
+
10
+### Minimalist introduction to PostgreSQL ###
11
+
12
+If you already use/know `PostgreSQL`, you can directly go to *Test the database access*.
13
+
14
+#### Allowing local connections on PostgreSQL ####
15
+
16
+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:
17
+
18
+    # IPv4 local connections:
19
+    host    all             all             127.0.0.1/32            md5
20
+
21
+If you changed the file, reload `PostgreSQL`:
22
+
23
+    service postgresql reload
24
+
25
+#### Creating a user and associated database ####
26
+
27
+You need a database and associated user/password. Tracim comes with `pgtool`, tool that will make this step easy:
28
+
29
+    ./bin/pgtool help
30
+
31
+Run the following self explanatory commands:
32
+
33
+    sudo su postgres
34
+    ./bin/pgtool create_user tracimuser tracimpassword
35
+    ./bin/pgtool create_database tracimdb
36
+    ./bin/pgtool grant_all_privileges tracimdb tracimuser
37
+    exit
38
+
39
+#### Test the database access ####
40
+
41
+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`:
42
+
43
+    ./bin/pgtool test_connection tracimdb tracimuser tracimpassword 127.0.0.1
44
+
45
+The result is similar to the following :
46
+
47
+    PG # CONNECT TO DATABASE
48
+    ------------------------
49
+    server:     127.0.0.1
50
+    database:   tracimdb
51
+    username:   bibi
52
+
53
+                  now
54
+    -------------------------------
55
+     2014-11-10 09:40:23.306199+01
56
+    (1 row)
57
+
58
+In case of failure, you would get something like this:
59
+
60
+    PG # CONNECT TO DATABASE
61
+    ------------------------
62
+    server:     127.0.0.1
63
+    database:   tracimdb
64
+    username:   bibi
65
+
66
+    psql: FATAL:  password authentication failed for user "bibi"
67
+    FATAL:  password authentication failed for user "bibi"
68
+    ERRROR
69
+
70
+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!
71
+
72
+## MySQL ##
73
+
74
+Or if you want to use `MySQL` as database engine
75
+
76
+    sudo apt install mysql-server
77
+
78
+### Minimalist introduction to MySQL ###
79
+
80
+#### Driver ####
81
+
82
+Tracim uses the `PyMySQL` driver between the `SQLAlchemy` ORM and the `MySQL` RDBMS. The only requirement is a pip installable package:
83
+
84
+    pip install PyMySQL
85
+
86
+#### Create database ####
87
+
88
+Connect to `MySQL` with root user (password has been set at "Installation" -> "Dependencies" chapter, when installing package)
89
+
90
+    mysql -u root -p
91
+
92
+Create a database with following command:
93
+
94
+    CREATE DATABASE tracimdb;
95
+
96
+Create a user with following command:
97
+
98
+    CREATE USER 'tracimuser'@'localhost' IDENTIFIED BY 'tracimpassword';
99
+
100
+And allow him to manipulate created database with following command:
101
+
102
+    GRANT ALL PRIVILEGES ON tracimdb . * TO 'tracimuser'@'localhost';
103
+
104
+Then flush privileges:
105
+
106
+    FLUSH PRIVILEGES;
107
+
108
+You can now quit `MySQL` prompt:
109
+
110
+    \q
111
+
112
+## SQLAlchemy settings ##
113
+
114
+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.
115
+
116
+If you're willing to choose `PostgreSQL` or `MySQL`, comment the `sqlalchemy.url` line corresponding to `SQLite` and uncomment the one of your choice.
117
+
118
+For example with `PostgreSQL`, this should gives you:
119
+
120
+    sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb?client_encoding=utf8
121
+    # sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb
122
+    # sqlalchemy.url = sqlite:///tracimdb.sqlite
123
+
124
+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:
125
+
126
+- [app:main]
127
+- [app:ldap]
128
+- [app:radicale]
129
+
130
+Again with `PostgreSQL`, this should gives you:
131
+
132
+    sqlalchemy.url = postgresql://tracimuser:tracimpassword@127.0.0.1:5432/tracimdb_test?client_encoding=utf8
133
+    # sqlalchemy.url = mysql+pymysql://tracimuser:tracimpassword@127.0.0.1/tracimdb_test
134
+    # sqlalchemy.url = sqlite:///tracimdb_test.sqlite
135
+
136
+*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 Bestand weergeven

@@ -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 some interest for 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
+* ...

+ 6 - 3
tracim/test.ini Bestand weergeven

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