Source

trac-ticketlinks / INSTALL

Diff from to
 Trac Installation Guide
 =======================
 The Trac web-based project management tool is implemented as a server side
-cgi-program. Trac is written in the Python programming language and store it's
-data in a sqlite database.
+cgi-program. Trac is written in the Python programming language and uses SQLite
+as an embedded database. For HTML rendering, Trac uses the Clearsilver template
+system.
 
-Dependencies
+Requirements
 ------------
-The following dependencies have to be installed:
+To install Trac, the following software packages must be installed:
 
   * Python, version >= 2.1.
+      + Please keep in mind, that for RPM-based systems you will also need
+        python-devel and python-xml packages.
   * Subversion, version >= 0.37. (>=1.0.1 recommended)
   * Subversion Python bindings.
-  * pysqlite, version >= 0.4.3 (>= 0.5 for better performance)
-  * ClearSilver, version >= 0.9.3
-  * A CGI-capable web server (We QA-test on Apache)
+  * PySQLite, version >= 0.4.3 (>= 0.5 for better performance)
+  * Clearsilver, version >= 0.9.3
+  * A CGI-capable web server (we QA-test on Apache2 )
 
 Installing Trac
 ---------------
-        $ python ./setup.py install
+    $ python ./setup.py install
 
 This will byte-compile the python source code and install it in the
-site-packages directory of your python installation. The directories
-cgi-bin, templates, htdocs and wiki-default will all be copied into
-$prefix/share/trac/ .
+site-packages directory of your python installation. The directories cgi-bin,
+templates, htdocs and wiki-default are all copied to $prefix/share/trac/ .
 
-For more install configuration options, run 'python ./setup.py --help'.
+The script will also install the trac-admin command-line tool, used to create
+and maintain project environments. Trac-admin is the command center of Trac.
+
+Note: you'll need root permissions or equivalent for this step.
+
+Advanced Users
+--------------
+To install Trac in a different location, and other advanced installation
+options, run:
+
+    $ python ./setup.py --help
 
 Installing Trac on Windows
 --------------------------
 After running the installer, configuration and installation is the same as
 for other platforms.
 
-Initializing the database
--------------------------
-Trac stores wiki pages, tickets and other information in a sqlite database.
-Sqlite databases are just ordinary files on the hard drive, no database server
-is required.
+Creating a Project Environment
+------------------------------
+Trac Environment is the backend storage format where Trac stores information
+like wiki pages, tickets, reports, settings, etc. A Trac environment consist of
+a directory containing an SQLite database, human-readable configuration file,
+log-files and attachments.
 
-A new trac database can be created like this:
+A new Trac environment is created with trac-admin:
 
-        $ trac-admin /path/to/mydatabase.db initdb
+    $ trac-admin /path/to/projectenv initenv
 
-NOTE: The database file have to be located in a directory where the web server
-user has write permission to both the file and the directory.
+Note: The web server user need write permission to the environment directory
+and all the files inside.
 
 trac-admin will ask you where your subversion repository is located and where
 it can find the trac templates directory (the default value should be fine).
 
 Configuring Apache
 ------------------
-copy (or symlink) "trac/cgi-bin/trac.cgi" to you web servers /cgi-bin/
-directory. Of course you can configure apache to use the "trac/cgi-bin/"
-directory directly if you like.
+Copy (or symlink) "trac/cgi-bin/trac.cgi" to you web servers /cgi-bin/
+directory. You can also configure apache to use the "trac/cgi-bin/" directory
+directly if you like, it's a matter of taste.
 
-Finally adjust the filenames and add this config snippet to your web server:
+Finally edit the apache config and add this config snippet, with filenams
+edited to match your installation:
 
-Alias /trac/ "/where/you/put/trac/htdocs/"
+Alias /trac/ "/usr/share/trac/htdocs/" #or where you installed the trac docs
+#You have to allow people to read the files in htdocs
+<Directory "/usr/share/trac/htdocs/">
+        Options Indexes MultiViews
+        AllowOverride None
+        Order allow,deny
+        Allow from all
+</Directory>
+
+
 # Trac need to know where the database is located
 <Location "/cgi-bin/trac.cgi">
-        SetEnv TRAC_DB "/somewhere/myproject.db"
+        SetEnv TRAC_ENV "/path/to/projectenv"
 </Location>
 
 # You need this to allow users to authenticate
+# trac.htpasswd can be created with 
+# cmd 'htpasswd -c trac.htpasswd' (UNIX)
+# do 'man htpasswd' to see all the options
 <Location "/cgi-bin/trac.cgi/login">
         AuthType Basic
         AuthName "trac"
         Require valid-user
 </location>
 
-What next?
+Note: When creating a new environment, trac-admin will print a config snippet
+customized for your project.
+
+Using Trac
 ----------
 You should now have a working Trac installation at:
 
 http://<yourhostname>/cgi-bin/trac.cgi
 
 There you should be able to browse your subversion repository, create tickets,
-view the timeline etc. Keep in mind that anonymous users (before logging in)
-are only able to see/use a subset of all the features provided by Trac. Please
-read TracPermissions on how to grant additional privileges to authenticated
-users.
+view the timeline etc. Keep in mind that anonymous users (not logged in) can
+only access a restricted subset of all Trac features.
+
+Please continue to TracPermissions to learn how to grant additional privileges
+to authenticated users.
+
+For further user-documentation, see TracGuide.
 
 Enjoy!