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