Edgewall Software

Changes between Version 407 and Version 408 of TracInstall


Ignore:
Timestamp:
Apr 26, 2015, 12:02:23 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified

  • TracInstall

    v407 v408  
    11= Trac Installation Guide for 1.0
     2
    23[[TracGuideToc]]
    34[[TranslatedPages]]
    … …  
    1415
    1516== Dependencies
     17
    1618=== Mandatory Dependencies
     19
    1720To install Trac, the following software packages must be installed:
    1821
    … …  
    4548 * [http://sf.net/projects/mysql-python MySQLdb], version 1.2.2 or later
    4649
    47 Given the caveats and known issues surrounding MySQL, read carefully the [trac:MySqlDb] page before creating the database.
     50Given the caveats and known issues surrounding MySQL, read the [trac:MySqlDb] page before creating the database.
     51
     52The drop-in replacements [https://mariadb.org/ MariaDB] and [http://www.percona.com/ Percona] are also known to work instead of MySQL (see [trac:TracDev/ApiChanges/1.1]).
    4853
    4954=== Optional Dependencies
    … …  
    5257
    5358===== Subversion
    54  * [http://subversion.apache.org/ Subversion], 1.5.x or later and the '''''corresponding''''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. may still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page.
     59 * [http://subversion.apache.org/ Subversion], 1.5.x or later and the '''corresponding''' Python bindings. Older versions starting from 1.0, like 1.2.4, 1.3.2 or 1.4.2, etc. may still work. For troubleshooting information, check the [trac:TracSubversion#Troubleshooting TracSubversion] page.
    5560
    5661There are [http://subversion.apache.org/packages.html pre-compiled SWIG bindings] available for various platforms. (Good luck finding precompiled SWIG bindings for any Windows package at that listing. [trac:TracSubversion] points you to [http://alagazam.net Alagazam], which works for me under Python 2.6.)
    … …  
    5863Note that Trac '''doesn't''' use [http://pysvn.tigris.org/ PySVN], neither does it work yet with the newer `ctype`-style bindings.
    5964
    60 '''Please note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
     65'''Note:''' if using Subversion, Trac must be installed on the '''same machine'''. Remote repositories are currently [trac:ticket:493 not supported].
    6166
    6267===== Git
    … …  
    7075
    7176==== Web Server
    72 A web server is optional because Trac is shipped with a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.
     77
     78A web server is optional because Trac has a server included, see the [#RunningtheStandaloneServer Running the Standalone Server] section below.
    7379
    7480Alternatively you can configure Trac to run in any of the following environments:
    … …  
    8187   server (see [trac:TracOnWindowsIisAjp TracOnWindowsIisAjp])
    8288 * a FastCGI and FastCGI-to-WSGI gateway (see [trac:TracOnWindowsIisWfastcgi])
    83  * a CGI-capable web server (see TracCgi), '''but usage of Trac as a cgi script
    84    is highly discouraged''', better use one of the previous options.
     89 * a CGI-capable web server (see TracCgi), but usage of Trac as a cgi script
     90   is highly discouraged, better use one of the previous options.
    8591   
    86 
    8792==== Other Python Packages
    8893
    … …  
    104109}}}
    105110
    106 Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there ''probably concern older versions of Trac than the one you're installing''.
     111Please refer to the documentation of these packages to find out how they are best installed. In addition, most of the [trac:TracInstallPlatforms platform-specific instructions] also describe the installation of the dependencies. Keep in mind however that the information there probably concern older versions of Trac than the one you're installing.
    107112
    108113== Installing Trac
    … …  
    111116
    112117=== Using `easy_install`
    113 Trac can be installed from PyPI or the Subversion repository using [http://pypi.python.org/pypi/setuptools setuptools].
    114 
    115 A few examples:
     118
     119Trac can be installed from [https://pypi.python.org/pypi PyPI] or the Subversion repository using [pypi:setuptools setuptools].
     120
     121A few command-line examples:
    116122
    117123 - Install Trac 1.0:
    … …  
    124130   }}}
    125131   Note that in this case you won't have the possibility to run a localized version of Trac;
    126    either use a released version or install from source 
     132   either use a released version or install from source.
    127133
    128134More information can be found on the [trac:setuptools] page.
    … …  
    133139
    134140=== Using `pip`
    135 'pip' is an easy_install replacement that is very useful to quickly install python packages.
     141
     142'pip' is an easy_install replacement that is very useful to quickly install Python packages.
    136143To get a Trac installation up and running in less than 5 minutes:
    137144
    138 Assuming you want to have your entire pip installation in `/opt/user/trac`
     145Assuming you want to have your entire pip installation in `/opt/user/trac`:
    139146
    140147 -
    … …  
    142149pip install trac psycopg2
    143150}}}
    144 or
     151or:
    145152 -
    146153 {{{#!sh
    … …  
    152159pip will automatically resolve all dependencies (like Genshi, pygments, etc.), download the latest packages from pypi.python.org and create a self contained installation in `/opt/user/trac`.
    153160
    154 All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive)
     161All commands (`tracd`, `trac-admin`) are available in `/opt/user/trac/bin`. This can also be leveraged for `mod_python` (using `PythonHandler` directive) and `mod_wsgi` (using `WSGIDaemonProcess` directive).
    155162
    156163Additionally, you can install several Trac plugins (listed [https://pypi.python.org/pypi?:action=browse&show=all&c=516 here]) through pip.
    157164
    158165=== From source
     166
    159167Using the python-typical setup at the top of the source directory also works. You can obtain the source for a .tar.gz or .zip file corresponding to a release (e.g. `Trac-1.0.tar.gz`) from the [trac:TracDownload] page, or you can get the source directly from the repository. See [trac:TracRepositories#OfficialSubversionrepository TracRepositories] for details.
    160168
    161169{{{#!sh
    162 $ python ./setup.py install
    163 }}}
    164 
    165 ''You will need root permissions or equivalent for this step.''
     170python ./setup.py install
     171}}}
     172
     173You will need root permissions or equivalent for this step.
    166174
    167175This will byte-compile the Python source code and install it as an .egg file or folder in the `site-packages` directory
    … …  
    170178If you install from source and want to make Trac available in other languages, make sure Babel is installed. Only then, perform the `install` (or simply redo the `install` once again afterwards if you realize Babel was not yet installed):
    171179{{{#!sh
    172 $ python ./setup.py install
    173 }}}
     180python ./setup.py install
     181}}}
     182
    174183Alternatively, you can run `bdist_egg` and copy the .egg from `dist/` to the place of your choice, or you can create a Windows installer (`bdist_wininst`).
    175184
    … …  
    195204easy_install --prefix=/path/to/installdir
    196205}}}
     206
    197207or, if installing Trac on a Mac OS X system:
    198208{{{#!sh
    199209easy_install --prefix=/usr/local --install-dir=/Library/Python/2.5/site-packages
    200210}}}
    201 Note: If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.5/site-packages }}} by default.
     211
     212'''Note''': If installing on Mac OS X 10.6 running {{{ easy_install http://svn.edgewall.org/repos/trac/trunk }}} will install into {{{ /usr/local }}} and {{{ /Library/Python/2.5/site-packages }}} by default.
    202213
    203214The above will place your `tracd` and `trac-admin` commands into `/usr/local/bin` and will install the Trac libraries and dependencies into `/Library/Python/2.5/site-packages`, which is Apple's preferred location for third-party Python application installations.
    … …  
    209220A new environment is created using [TracAdmin trac-admin]:
    210221{{{#!sh
    211 $ trac-admin /path/to/myproject initenv
     222trac-admin /path/to/myproject initenv
    212223}}}
    213224
    … …  
    227238Finally, make sure the user account under which the web front-end runs will have '''write permissions''' to the environment directory and all the files inside. This will be the case if you run `trac-admin ... initenv` as this user. If not, you should set the correct user afterwards. For example on Linux, with the web server running as user `apache` and group `apache`, enter:
    228239{{{#!sh
    229 $ chown -R apache.apache /path/to/myproject
    230 }}}
    231 
    232 The actual username and groupname of the apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use).
     240chown -R apache.apache /path/to/myproject
     241}}}
     242
     243The actual username and groupname of the Apache server may not be exactly `apache`, and are specified in the Apache configuration file by the directives `User` and `Group` (if Apache `httpd` is what you use).
    233244
    234245{{{#!div class=important
    … …  
    242253After having created a Trac environment, you can easily try the web interface by running the standalone server [TracStandalone tracd]:
    243254{{{#!sh
    244 $ tracd --port 8000 /path/to/myproject
     255tracd --port 8000 /path/to/myproject
    245256}}}
    246257
    247258Then, 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. If you only plan on managing a single project with Trac you can have the standalone server skip the environment list by starting it like this:
    248259{{{#!sh
    249 $ tracd -s --port 8000 /path/to/myproject
     260tracd -s --port 8000 /path/to/myproject
    250261}}}
    251262
    … …  
    260271Alternatively, the variable can be set in the shell before executing `tracd`:
    261272{{{#!sh
    262 $ PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject
     273PKG_RESOURCES_CACHE_ZIP_MANIFESTS=1 tracd --port 8000 /path/to/myproject
    263274}}}
    264275}}}
    … …  
    270281 - [wiki:TracModWSGI mod_wsgi]
    271282 - [TracModPython mod_python]
    272  - //[TracCgi CGI] (should not be used, as the performance is far from optimal)//
     283 - [TracCgi CGI]: should not be used, as this degrades performance
    273284
    274285Trac also supports [trac:TracOnWindowsIisAjp AJP] which may be your choice if you want to connect to IIS. Other deployment scenarios are possible: [trac:TracNginxRecipe nginx], [http://projects.unbit.it/uwsgi/wiki/Example#Traconapacheinasub-uri uwsgi], [trac:TracOnWindowsIisIsapi Isapi-wsgi] etc.
    … …  
    285296mv /tmp/deploy/* /usr/share/trac
    286297}}}
     298
    287299Don't forget to check that the web server has the execution right on scripts in the `/usr/share/trac/cgi-bin` directory.
    288300
    289301==== Mapping Static Resources
    290302
    291 Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources (for CGI setup, this is '''highly undesirable''' and will cause abysmal performance).
    292 
    293 Web servers such as [http://httpd.apache.org/ Apache] allow you to create “Aliases” to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by Trac itself.
     303Out of the box, Trac will pass static resources such as style sheets or images through itself. For anything but a tracd only based deployment, this is far from optimal as the web server could be set up to directly serve those static resources. For CGI setup, this is '''highly undesirable''' as it causes poor performance.
     304
     305Web servers such as [http://httpd.apache.org/ Apache] allow you to create "Aliases" to resources, giving them a virtual URL that doesn't necessarily reflect the layout of the servers file system. We also can map requests for static resources directly to the directory on the file system, avoiding processing these requests by Trac itself.
    294306
    295307There are two primary URL paths for static resources - `/chrome/common` and `/chrome/site`. Plugins can add their own resources, usually accessible by `/chrome/<plugin>` path, so its important to override only known paths and not try to make universal `/chrome` alias for everything.
    … …  
    307319Assuming the deployment has been done this way:
    308320{{{#!sh
    309 $ trac-admin /var/trac/env deploy /path/to/shared/trac
     321trac-admin /var/trac/env deploy /path/to/shared/trac
    310322}}}
    311323
    … …  
    321333}}}
    322334
    323 If using mod_python, you might want to add this too (otherwise, the alias will be ignored):
     335If using mod_python, you might want to add this too, otherwise the alias will be ignored:
    324336{{{#!apache
    325337<Location "/trac/chrome/common/">
    … …  
    345357htdocs_location = http://static.example.org/trac-common/
    346358}}}
    347 Note that this makes it easy to have a dedicated domain serve those static resources (preferentially [http://code.google.com/speed/page-speed/docs/request.html#ServeFromCookielessDomain cookie-less]).
     359
     360Note that this makes it easy to have a dedicated domain serve those static resources, preferentially [http://code.google.com/speed/page-speed/docs/request.html#ServeFromCookielessDomain cookie-less].
    348361
    349362Of course, you still need to make the Trac `htdocs/common` directory available through the web server at the specified URL, for example by copying (or linking) the directory into the document root of the web server:
    350363{{{#!sh
    351 $ ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common
     364ln -s /path/to/trac/htdocs/common /var/www/static.example.org/trac-common
    352365}}}
    353366
    … …  
    365378 * TracStandalone#UsingAuthentication if you use the standalone server, `tracd`.
    366379 * [wiki:TracModWSGI#ConfiguringAuthentication TracModWSGI#ConfiguringAuthentication] if you use the Apache web server, with any of its front end: `mod_wsgi` of course, but the same instructions applies also for `mod_python`, `mod_fcgi` or `mod_fastcgi`.
    367  * TracFastCgi if you're using another web server with FCGI support (Cherokee, Lighttpd, !LiteSpeed, nginx)
     380 * TracFastCgi if you are using another web server with FCGI support, such as Cherokee, Lighttpd, !LiteSpeed, nginx.
    368381
    369382The following document also contains some useful information for beginners: [trac:TracAuthenticationIntroduction].
    370383
    371384== Granting admin rights to the admin user
     385
    372386Grant admin rights to user admin:
    373387{{{#!sh
    374 $ trac-admin /path/to/myproject permission add admin TRAC_ADMIN
    375 }}}
     388trac-admin /path/to/myproject permission add admin TRAC_ADMIN
     389}}}
     390
    376391This user will have an "Admin" entry menu that will allow you to administrate your Trac project.
    377392
    … …  
    382397Support for version control systems is provided by optional components in Trac and the components are disabled by default //(since 1.0)//. Subversion and Git must be explicitly enabled if you wish to use them. See TracRepositoryAdmin for more details.
    383398
    384 The version control systems are enabled by adding the following to the `[components]` section of your [TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel.
     399The version control systems are enabled by adding the following to the `[components]` section of your [TracIni#components-section trac.ini], or enabling the components in the "Plugins" admin panel:
    385400
    386401{{{#!ini
     402[components]
    387403tracopt.versioncontrol.svn.* = enabled
    388404}}}
    389405
    390406{{{#!ini
     407[components]
    391408tracopt.versioncontrol.git.* = enabled
    392409}}}