7 | | |
8 | | '''Note:''' These are generic instructions for installing and setting up Trac and its requirements. You should first look at TracInstallPlatforms for instructions and downloads specific to the system where you are installing Trac. |
9 | | |
10 | | {{{ |
11 | | #!html |
12 | | <h2 style="color: red;">Warning</h2> |
13 | | <p style="color: red; font-variant: italic;">Please read this carefully before installing Trac.</p> |
14 | | }}} |
15 | | |
16 | | Different versions of Trac's dependencies are not necessarily interchangable, so please pay attention to the notes about different versions. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the MailingList or IrcChannel. |
| 6 | What follows are generic instructions for installing and setting up Trac and its requirements. While you can find instructions for installing Trac on specific systems at TracInstallPlatforms, please be sure to first read through these general instructions to get a good understanding of the tasks involved. |
24 | | * Python 2.1 support is going to be dropped for the next (0.9) release of Trac. Minimum required version for trunk is thus Python 2.2.2 (see #1311 and [http://lists.edgewall.com/archive/trac/2005-March/002074.html this mail]). |
25 | | * Please keep in mind that for RPM-based systems you will also need python-devel and python-xml packages. |
26 | | * [http://www.swig.org/ SWIG] language bindings, version 1.3.21 (also see next notes) |
27 | | * Make sure you also build SWIG Runtime support: run ''make'' in SWIG-1.3.21/Runtime. |
| 14 | * Please keep in mind that for RPM-based systems you might also need the `python-devel` and `python-xml` packages. |
| 15 | * [http://www.swig.org/ SWIG], version >= 1.3.21. |
| 16 | * For versions of SWIG prior to 1.3.24, make sure to also build SWIG runtime support (`make runtime && make install-runtime`). |
| 17 | * Also note that the bindings of Subversion <= 1.1.3 have problems with versions of SWIG >= 1.3.22. Use SWIG 1.3.21 in conjunction with Subversion <= 1.1.3. |
30 | | * Trac uses the [http://www.swig.org/ SWIG] bindings included in the Subversion distribution |
31 | | * '''Not PySVN''' http://pysvn.tigris.org/ ''This library is commonly confused with the standard SWIG bindings, however the two are not interchangeable.'' |
32 | | * Also note that the bindings of Subversion <= 1.1.3 have problems with versions of SWIG >= 1.3.22. Use SWIG 1.3.21 in conjunction with Subversion <= 1.1.3. |
33 | | * If Subversion was already installed without the SWIG bindings: re-configure and re-make Subversion, ''make swig-py'', ''make install-swig-py''. |
34 | | * [http://www.sqlite.org/ SQLite], version 2.8.x or 3.0.x |
35 | | * By default, the SQLite installation puts the compiled libraries in ''/usr/local/lib''. Either check your ''LD_LIBRARY_PATH'' or copy the libraries to ''/usr/lib'' |
| 20 | * Trac uses the [http://www.swig.org/ SWIG] bindings included in the Subversion distribution, '''not''' [http://pysvn.tigris.org/ PySVN] (which is sometimes confused with the standard SWIG bindings). |
| 21 | * If Subversion was already installed without the SWIG bindings, you'll need to re-`configure` Subversion and `make swig-py`, `make install-swig-py`. |
| 22 | * [http://www.clearsilver.net/ ClearSilver], version >= 0.9.3 |
| 23 | |
| 24 | === For SQLite === |
| 25 | |
| 26 | * [http://www.sqlite.org/ SQLite], version 2.8.x or 3.x |
45 | | * A CGI-capable web server (tested on [http://httpd.apache.org/ Apache]), or |
| 33 | * [http://www.postgresql.org/ PostgreSQL] |
| 34 | * [http://initd.org/projects/psycopg1 psycopg1], [http://initd.org/projects/psycopg2 psycopg2], or [http://pypgsql.sourceforge.net/ pyPgSQL] |
| 35 | |
| 36 | === Optional Requirements === |
| 37 | |
| 38 | * A CGI-capable web server, or |
| 39 | * a [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi), or |
47 | | * A [http://www.fastcgi.com/ FastCGI]-capable web server (see TracFastCgi) |
48 | | * [http://docutils.sourceforge.net/ docutils], version >= 0.3.3 (??) for WikiRestructuredText. |
49 | | Version 0.3.5 is known to work whereas 0.3.7 is currently |
50 | | not working (see #1302). |
| 41 | * [http://docutils.sourceforge.net/ docutils], version >= 0.3.3 for WikiRestructuredText. |
| 42 | * [http://peak.telecommunity.com/DevCenter/setuptools], version >= 0.6a1 for using plugins |
| 43 | |
| 44 | '''Attention''': The various available versions of these dependencies are not necessarily interchangable, so please pay attention to the version numbers above. If you are having trouble getting Trac to work please double-check all the dependencies before asking for help on the MailingList or IrcChannel. |
83 | | TracEnvironment is the backend storage format where Trac stores |
84 | | information like wiki pages, tickets, reports, settings, etc. |
85 | | An environment consist of a directory containing an SQLite database, |
86 | | human-readable configuration file, log-files and attachments. |
| 78 | A [wiki:TracEnvironment Trac environment] is the backend storage where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment is basically a directory that contains a human-readable configuration file and various other files and directories. |
97 | | '''Note:''' The web server user will require file system write permission to the environment |
98 | | directory and all the files inside. '''Remember to set the appropriate permissions.'' |
99 | | |
100 | | The same applies for the subversion repository files (unless using the [http://svn.collab.net/repos/svn/trunk/notes/fsfs FSFS Subversion backend], something we highly recommend). |
101 | | |
102 | | == Configuring Apache == |
103 | | |
104 | | Make "{{{trac/cgi-bin/trac.cgi}}}" accessible to your web server at {{{/cgi-bin/}}}, either by copying/symlinking or use the "{{{trac/cgi-bin/}}}" directory directly. |
105 | | |
106 | | '''Note:''' If you are symlinking "{{{trac/cgi-bin/trac.cgi}}}" make sure you have the {{{FollowSymLinks}}} option set for CGI directory in the apache config. |
| 87 | ''Note: The user account under which the web server runs will require write permissions to the environment |
| 88 | directory and all the files inside.'' |
112 | | Alias /trac/ /usr/share/trac/htdocs/ |
113 | | #or where you installed the trac htdocs |
114 | | #You have to allow people to read the files in htdocs |
115 | | <Directory "/usr/share/trac/htdocs"> |
116 | | Options Indexes MultiViews |
117 | | AllowOverride None |
118 | | Order allow,deny |
119 | | Allow from all |
120 | | </Directory> |
| 95 | $ tracd --port 8000 /path/to/projectenv |
| 96 | }}} |
| 97 | |
| 98 | Then, fire up a browser and visit `http://localhost:8000/`. You should get a simple listing of all environments that tracd knows about. Follow the link to the environment you just created, and you should see Trac in action. |
137 | | '''Note:''' You can also use Trac via mod_python. Read TracModPython for more information. |
138 | | |
139 | | '''Note:''' If Apache complains about the !SetEnv line make sure you have the !LoadModule for mod_env uncommented (Apache 1.3). |
140 | | |
141 | | '''Note:''' When creating a new environment, {{{trac-admin}}} will print a config snippet customized for your project. |
142 | | |
143 | | |
144 | | '''Note:''' If you are using [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature see [http://projects.edgewall.com/trac/wiki/ApacheSuexec ApacheSuexec] (on the project web site). |
145 | | |
146 | | == Adding Users (optional) == |
147 | | |
148 | | You need to create the password file in the same place you specified it in the apache config file (the line above that reads "/somewhere/trac.htpasswd"). |
149 | | |
150 | | Use the following commands to create the password file (do 'man htpasswd' to see all the options): |
151 | | {{{ |
152 | | # cd /somewhere |
153 | | # htpasswd -c trac.htpasswd admin |
154 | | New password: <type password> |
155 | | Re-type new password: <type password again> |
156 | | Adding password for user admin |
157 | | }}} |
158 | | |
159 | | After the first user, you dont need the "-c" option anymore: |
160 | | {{{ |
161 | | # htpasswd trac.htpasswd john |
162 | | New password: <type password> |
163 | | Re-type new password: <type password again> |
164 | | Adding password for user john |
165 | | }}} |
166 | | |
167 | | After you create the users, you can set their permissions using TracPermissions. |
173 | | !http://<yourhostname>/cgi-bin/trac.cgi |
174 | | |
175 | | You should be able to browse your subversion repository, create tickets, |
176 | | view the timeline and use all the features of Trac. |
177 | | |
178 | | Keep in mind that anonymous users (not logged in) can only access a restricted subset of all Trac features by default. |
179 | | |
180 | | '''Note:''' If you don't want long, and relatively ugly, URLs, you can prettify them by changing your Apache config. See TracPrettyUrls. |
181 | | |
182 | | Please continue to TracPermissions to learn how to grant additional privileges to authenticated users. |
183 | | |
184 | | For user documentation, see TracGuide. |
| 110 | Keep in mind that anonymous (not logged in) users can by default access most but not all of the features. You will need to configure authentication and grant additional [wiki:TracPermissions permissions] to authenticated users to see the full set of features. |