Changes between Version 6 and Version 7 of TracStandalone


Ignore:
Timestamp:
03/24/15 23:15:03 (3 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracStandalone

    v6 v7  
    1 = Tracd
     1** Note: this page documents the version 1.0 of Trac, see [[0.12/TracStandalone]] if you need the previous version **
     2= Tracd =
    23
    34Tracd is a lightweight standalone Trac web server.
    45It can be used in a variety of situations, from a test or development server to a multiprocess setup behind another web server used as a load balancer.
    56
    6 == Pros
     7== Pros ==
    78
    89 * Fewer dependencies: You don't need to install apache or any other web-server.
     
    1011 * Automatic reloading: For development, Tracd can be used in ''auto_reload'' mode, which will automatically restart the server whenever you make a change to the code (in Trac itself or in a plugin).
    1112
    12 == Cons
     13== Cons ==
    1314
    1415 * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
    1516 * No native HTTPS support: [http://www.rickk.com/sslwrap/ sslwrap] can be used instead,
    16    or [trac:wiki:STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
    17 
    18 == Usage examples
     17   or [http://trac.edgewall.org/wiki/STunnelTracd stunnel -- a tutorial on how to use stunnel with tracd] or Apache with mod_proxy.
     18
     19== Usage examples ==
    1920
    2021A single project on port 8080. (http://localhost:8080/)
    21 {{{#!sh
     22{{{
    2223 $ tracd -p 8080 /path/to/project
    2324}}}
    24 Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option.
    25 {{{#!sh
     25Stricly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use ''--hostname'' option.
     26{{{
    2627 $ tracd --hostname=localhost -p 8080 /path/to/project
    2728}}}
    2829With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
    29 {{{#!sh
     30{{{
    3031 $ tracd -p 8080 /path/to/project1 /path/to/project2
    3132}}}
     
    3536
    3637An alternative way to serve multiple projects is to specify a parent directory in which each subdirectory is a Trac project, using the `-e` option. The example above could be rewritten:
    37 {{{#!sh
     38{{{
    3839 $ tracd -p 8080 -e /path/to
    3940}}}
    4041
    41 To exit the server on Windows, be sure to use `CTRL-BREAK` -- using `CTRL-C` will leave a Python process running in the background.
    42 
    43 == Installing as a Windows Service
    44 
    45 === Option 1
     42To exit the server on Windows, be sure to use {{{CTRL-BREAK}}} -- using {{{CTRL-C}}} will leave a Python process running in the background.
     43
     44== Installing as a Windows Service ==
     45
     46=== Option 1 ===
    4647To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
    47 {{{#!cmd
     48{{{
    4849 C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
    4950 reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd-script.py\" <your tracd parameters>"
     
    5455
    5556If you want tracd to start automatically when you boot Windows, do:
    56 {{{#!cmd
     57{{{
    5758 sc config tracd start= auto
    5859}}}
     
    7475
    7576For Windows 7 User, srvany.exe may not be an option, so you can use [http://www.google.com/search?q=winserv.exe WINSERV] utility and run:
    76 {{{#!cmd
     77{{{
    7778"C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd-script.py <your tracd parameters>"
     79
    7880net start tracd
    7981}}}
    8082
    81 === Option 2
     83=== Option 2 ===
    8284
    8385Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
    8486
    85 === Option 3
     87=== Option 3 ===
    8688
    8789also cygwin's cygrunsrv.exe can be used:
    88 {{{#!sh
     90{{{
    8991$ cygrunsrv --install tracd --path /cygdrive/c/Python27/Scripts/tracd.exe --args '--port 8000 --env-parent-dir E:\IssueTrackers\Trac\Projects'
    9092$ net start tracd
    9193}}}
    9294
    93 == Using Authentication
    94 
    95 Tracd allows you to run Trac without the need for Apache, but you can take advantage of Apache's password tools (htpasswd and htdigest) to easily create a password file in the proper format for tracd to use in authentication. (It is also possible to create the password file without htpasswd or htdigest; see below for alternatives)
    96 
    97 Make sure you place the generated password files on a filesystem which supports sub-second timestamps, as Trac will monitor their modified time and changes happening on a filesystem with too coarse-grained timestamp resolution (like `ext2` or `ext3` on Linux) may go undetected.
     95== Using Authentication ==
    9896
    9997Tracd provides support for both Basic and Digest authentication. Digest is considered more secure. The examples below use Digest; to use Basic authentication, replace `--auth` with `--basic-auth` in the command line.
    10098
    10199The general format for using authentication is:
    102 {{{#!sh
     100{{{
    103101 $ tracd -p port --auth="base_project_dir,password_file_path,realm" project_path
    104102}}}
     
    116114Examples:
    117115
    118 {{{#!sh
     116{{{
    119117 $ tracd -p 8080 \
    120118   --auth="project1,/path/to/passwordfile,mycompany.com" /path/to/project1
     
    122120
    123121Of course, the password file can be be shared so that it is used for more than one project:
    124 {{{#!sh
     122{{{
    125123 $ tracd -p 8080 \
    126124   --auth="project1,/path/to/passwordfile,mycompany.com" \
     
    130128
    131129Another way to share the password file is to specify "*" for the project name:
    132 {{{#!sh
     130{{{
    133131 $ tracd -p 8080 \
    134132   --auth="*,/path/to/users.htdigest,mycompany.com" \
     
    136134}}}
    137135
    138 === Basic Authorization: Using a htpasswd password file
     136=== Basic Authorization: Using a htpasswd password file ===
    139137This section describes how to use `tracd` with Apache .htpasswd files.
    140138
     
    144142
    145143To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
    146 {{{#!sh
     144{{{
    147145 $ sudo htpasswd -c /path/to/env/.htpasswd username
    148146}}}
    149147then for additional users:
    150 {{{#!sh
     148{{{
    151149 $ sudo htpasswd /path/to/env/.htpasswd username2
    152150}}}
    153151
    154152Then to start `tracd` run something like this:
    155 {{{#!sh
     153{{{
    156154 $ tracd -p 8080 --basic-auth="projectdirname,/fullpath/environmentname/.htpasswd,realmname" /fullpath/environmentname
    157155}}}
    158156
    159157For example:
    160 {{{#!sh
     158{{{
    161159 $ tracd -p 8080 --basic-auth="testenv,/srv/tracenv/testenv/.htpasswd,My Test Env" /srv/tracenv/testenv
    162160}}}
    163161''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
    164162
    165 === Digest authentication: Using a htdigest password file
     163=== Digest authentication: Using a htdigest password file ===
    166164
    167165If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [http://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions.  You'll be prompted for a password to enter for each user that you create.  For the name of the password file, you can use whatever you like, but if you use something like `users.htdigest` it will remind you what the file contains. As a suggestion, put it in your <projectname>/conf folder along with the [TracIni trac.ini] file.
     
    169167Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.
    170168
    171 === Generating Passwords Without Apache
     169=== Generating Passwords Without Apache ===
    172170
    173171Basic Authorization can be accomplished via this [http://aspirine.org/htpasswd_en.html online HTTP Password generator] which also supports `SHA-1`.  Copy the generated password-hash line to the .htpasswd file on your system. Note that Windows Python lacks the "crypt" module that is the default hash type for htpasswd ; Windows Python can grok MD5 password hashes just fine and you should use MD5.
     
    175173You can use this simple Python script to generate a '''digest''' password file:
    176174
    177 {{{#!python
     175{{{
     176#!python
    178177from optparse import OptionParser
    179178# The md5 module is deprecated in Python 2.5
     
    208207Note: If you use the above script you must set the realm in the `--auth` argument to '''`trac`'''. Example usage (assuming you saved the script as trac-digest.py):
    209208
    210 {{{#!sh
     209{{{
    211210 $ python trac-digest.py -u username -p password >> c:\digest.txt
    212211 $ tracd --port 8000 --auth=proj_name,c:\digest.txt,trac c:\path\to\proj_name
     
    223222}}}
    224223
    225 == Reference
     224== Reference ==
    226225
    227226Here's the online help, as a reminder (`tracd --help`):
     
    259258Use the -d option so that tracd doesn't hang if you close the terminal window where tracd was started.
    260259
    261 == Tips
    262 
    263 === Serving static content
     260== Tips ==
     261
     262=== Serving static content ===
    264263
    265264If `tracd` is the only web server used for the project,
     
    272271Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
    273272the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`,
    274 which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
     273which in turn can be written as `htdocs:software-0.1.tar.gz` (TracLinks syntax) or `[/<project_name>/chrome/site/software-0.1.tar.gz]` (relative link syntax).
     274
     275 ''Support for `htdocs:` TracLinks syntax was added in version 0.10''
    275276
    276277=== Using tracd behind a proxy
     
    285286
    286287=== Authentication for tracd behind a proxy
    287 It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. There is some discussion about this in [trac:#9206].
     288It is convenient to provide central external authentication to your tracd instances, instead of using {{{--basic-auth}}}. There is some discussion about this in #9206.
    288289
    289290Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.
     
    291292First we bring tracd into Apache's location namespace.
    292293
    293 {{{#!apache
     294{{{
    294295<Location /project/proxified>
    295296        Require ldap-group cn=somegroup, ou=Groups,dc=domain.com
     
    302303
    303304Then we need a single file plugin to recognize HTTP_REMOTE_USER header as valid authentication source. HTTP headers like '''HTTP_FOO_BAR''' will get converted to '''Foo-Bar''' during processing. Name it something like '''remote-user-auth.py''' and drop it into '''proxified/plugins''' directory:
    304 {{{#!python
     305{{{
     306#!python
    305307from trac.core import *
    306308from trac.config import BoolOption
     
    323325
    324326Add this new parameter to your TracIni:
    325 {{{#!ini
     327{{{
     328...
    326329[trac]
    327330...
     
    331334
    332335Run tracd:
    333 {{{#!sh
     336{{{
    334337tracd -p 8101 -r -s proxified --base-path=/project/proxified
    335338}}}
     
    338341
    339342Global config (e.g. `/srv/trac/conf/trac.ini`):
    340 {{{#!ini
     343{{{
    341344[components]
    342345remote-user-auth.* = enabled
     
    348351
    349352Environment config (e.g. `/srv/trac/envs/myenv`):
    350 {{{#!ini
     353{{{
    351354[inherit]
    352355file = /srv/trac/conf/trac.ini
    353356}}}
    354357
    355 === Serving a different base path than /
     358=== Serving a different base path than / ===
    356359Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
    357 {{{#!sh
     360{{{
    358361 $ tracd --base-path=/some/path
    359362}}}