Changes between Version 2 and Version 3 of TracStandalone


Ignore:
Timestamp:
Jun 9, 2024, 11:14:44 AM (5 months ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracStandalone

    v2 v3  
    44It 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.
    55
    6 == Pros
    7 
    8  * Fewer dependencies: You don't need to install apache or any other web-server.
    9  * Fast: Should be almost as fast as the [wiki:TracModPython mod_python] version (and much faster than the [wiki:TracCgi CGI]), even more so since version 0.12 where the HTTP/1.1 version of the protocol is enabled by default
    10  * 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).
    11 
    12 == Cons
    13 
     6'''Pros'''
     7 * Fewer dependencies: You don't need to install Apache or any other web-server.
     8 * Fast: Should be almost as fast as the [wiki:TracModWSGI mod_wsgi] version (and much faster than the [wiki:TracCgi CGI]), especially since the HTTP/1.1 version of the protocol is enabled by default.
     9 * 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, for example in Trac itself or in a plugin.
     10
     11'''Cons'''
    1412 * Fewer features: Tracd implements a very simple web-server and is not as configurable or as scalable as Apache httpd.
    15  * 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.
    1713
    1814== Usage examples
    1915
    20 A single project on port 8080. (http://localhost:8080/)
     16A single project on port 8080, such as `http://localhost:8080/`:
    2117{{{#!sh
    2218 $ tracd -p 8080 /path/to/project
    2319}}}
    24 Strictly speaking this will make your Trac accessible to everybody from your network rather than ''localhost only''. To truly limit it use the `--hostname` option.
     20Strictly speaking this will make your Trac accessible to everybody from your network rather than `localhost` only. To truly limit it use the `--hostname` option.
    2521{{{#!sh
    2622 $ tracd --hostname=localhost -p 8080 /path/to/project
    2723}}}
    28 With more than one project. (http://localhost:8080/project1/ and http://localhost:8080/project2/)
     24With more than one project, for example `http://localhost:8080/project1/` and `http://localhost:8080/project2/`:
    2925{{{#!sh
    3026 $ tracd -p 8080 /path/to/project1 /path/to/project2
    3127}}}
    3228
    33 You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the
    34 different projects unique. So if you use `/project1/path/to` and `/project2/path/to`, you will only see the second project.
     29You can't have the last portion of the path identical between the projects since Trac uses that name to keep the URLs of the different projects unique. So if you use `/project1/path/to` and `/project2/path/to`, you will only see the second project.
    3530
    3631An 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:
    … …  
    3934}}}
    4035
    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.
     36There is support for the HTTPS protocol (//Since 1.3.4//). Specify the path to the PEM certificate file and keyfile using the `--certfile` and `--keyfile` options. You can specify just the `--certfile` option if you have a [https://docs.python.org/2/library/ssl.html#combined-key-and-certificate combined key and certificate].
     37
     38To exit the server on Windows, be sure to use `CTRL-BREAK`. Using `CTRL-C` will leave a Python process running in the background.
    4239
    4340== Installing as a Windows Service
    4441
    4542=== Option 1
    46 To install as a Windows service, get the [http://www.google.com/search?q=srvany.exe SRVANY] utility and run:
     43
     44To install as a Windows service, get the [https://www.google.com/search?q=srvany.exe SRVANY] utility and run:
    4745{{{#!cmd
    4846 C:\path\to\instsrv.exe tracd C:\path\to\srvany.exe
    49  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>"
     47 reg add HKLM\SYSTEM\CurrentControlSet\Services\tracd\Parameters /v Application /d "\"C:\path\to\python.exe\" \"C:\path\to\python\scripts\tracd.exe\" <your tracd parameters>"
    5048 net start tracd
    5149}}}
    5250
    53 '''DO NOT''' use {{{tracd.exe}}}.  Instead register {{{python.exe}}} directly with {{{tracd-script.py}}} as a parameter.  If you use {{{tracd.exe}}}, it will spawn the python process without SRVANY's knowledge.  This python process will survive a {{{net stop tracd}}}.
     51{{{#!div style="border: 1pt dotted; margin: 1em;"
     52**Attention:** Do not use `tracd.exe` directly. Instead register `python.exe` directly with `tracd.exe` as a parameter. If you use `tracd.exe`, it will spawn the Python process without SRVANY's knowledge. This Python process will survive a `net stop tracd`.
     53}}}
    5454
    5555If you want tracd to start automatically when you boot Windows, do:
    … …  
    6161
    6262{{{#!div
    63 Once the service is installed, it might be simpler to run the Registry Editor rather than use the `reg add` command documented above.  Navigate to:[[BR]]
     63Once the service is installed, it might be simpler to run the Registry Editor rather than use the `reg add` command documented above. Navigate to:[[BR]]
    6464`HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\tracd\Parameters`
    6565
    6666Three (string) parameters are provided:
    67 ||!AppDirectory ||C:\Python26\ ||
     67||!AppDirectory ||C:\Python27\ ||
    6868||Application ||python.exe ||
    69 ||!AppParameters ||scripts\tracd-script.py -p 8080 ... ||
    70 
    71 Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory.  This makes updating Python a little simpler because the change can be limited, here, to a single point.
    72 (This is true for the path to the .htpasswd file, as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.)
    73 }}}
    74 
    75 For 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:
     69||!AppParameters ||scripts\tracd.exe -p 8080 ... ||
     70
     71Note that, if the !AppDirectory is set as above, the paths of the executable ''and'' of the script name and parameter values are relative to the directory. This makes updating Python a little simpler because the change can be limited, here, to a single point.
     72This is true for the path to the .htpasswd file as well, despite the documentation calling out the /full/path/to/htpasswd; however, you may not wish to store that file under the Python directory.
     73}}}
     74
     75For Windows 7 User, srvany.exe may not be an option, so you can use [https://www.google.com/search?q=winserv.exe WINSERV] utility and run:
    7676{{{#!cmd
    77 "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>"
     77"C:\path\to\winserv.exe" install tracd -displayname "tracd" -start auto "C:\path\to\python.exe" c:\path\to\python\scripts\tracd.exe <your tracd parameters>"
    7878net start tracd
    7979}}}
    … …  
    8181=== Option 2
    8282
    83 Use [http://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [http://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
     83Use [https://trac-hacks.org/wiki/WindowsServiceScript WindowsServiceScript], available at [https://trac-hacks.org/ Trac Hacks]. Installs, removes, starts, stops, etc. your Trac service.
    8484
    8585=== Option 3
    … …  
    9393== Using Authentication
    9494
    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)
     95Tracd 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.
    9696
    9797{{{#!div style="border: 1pt dotted; margin: 1em"
    98 **Attention:** 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, or HFS+ on OSX).
     98**Attention:** 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, or HFS+ on OSX.
    9999}}}
    100100
    … …  
    114114 * '''project_path''': path of the project
    115115
    116  * **`--auth`** in the above means use Digest authentication, replace `--auth` with `--basic-auth` if you want to use Basic auth.  Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name.
     116 * **`--auth`** in the above means use Digest authentication, replace `--auth` with `--basic-auth` if you want to use Basic auth. Although Basic authentication does not require a "realm", the command parser does, so the second comma is required, followed directly by the closing quote for an empty realm name.
    117117
    118118Examples:
    … …  
    139139
    140140=== Basic Authorization: Using a htpasswd password file
     141
    141142This section describes how to use `tracd` with Apache .htpasswd files.
    142143
    143   Note: On Windows It is necessary to install the [https://pypi.python.org/pypi/passlib passlib]
    144   package in order to decode some htpasswd formats. Only `SHA-1` passwords (since Trac 1.0)
    145   work without this module.
     144'''Note''': On Windows It is necessary to install the [https://pypi.python.org/pypi/passlib passlib] package in order to decode some htpasswd formats. Only `SHA-1` passwords work without this module (since Trac 1.0).
    146145
    147146To create a .htpasswd file use Apache's `htpasswd` command (see [#GeneratingPasswordsWithoutApache below] for a method to create these files without using Apache):
    … …  
    163162 $ tracd -p 8080 --basic-auth="project,/srv/tracenv/testenv/.htpasswd,My Test Env" /path/to/project
    164163}}}
    165 ''Note:'' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
     164
     165'''Note:''' You might need to pass "-m" as a parameter to htpasswd on some platforms (OpenBSD).
    166166
    167167=== Digest authentication: Using a htdigest password file
    168168
    169 If 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.
     169If you have Apache available, you can use the htdigest command to generate the password file. Type 'htdigest' to get some usage instructions, or read [https://httpd.apache.org/docs/2.0/programs/htdigest.html this page] from the Apache manual to get precise instructions. You will 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.
    170170
    171171Note that you can start tracd without the `--auth` argument, but if you click on the ''Login'' link you will get an error.
    … …  
    173173=== Generating Passwords Without Apache
    174174
    175 Basic 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.
    176 
    177 Trac also provides `htpasswd` and `htdigest` scripts in `contrib`:
     175Basic 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.
     176
     177Trac also provides `htpasswd` and `htdigest` scripts in `contrib` (in the Tar package):
    178178{{{#!sh
    179179$ ./contrib/htpasswd.py -cb htpasswd user1 user1
    … …  
    187187
    188188==== Using `md5sum`
     189
    189190It is possible to use `md5sum` utility to generate digest-password file:
    190191{{{#!sh
    … …  
    198199== Reference
    199200
    200 Here's the online help, as a reminder (`tracd --help`):
     201Here's the online help, as a reminder (`tracd -h` or `tracd --help`):
    201202{{{
    202 Usage: tracd [options] [projenv] ...
    203 
    204 Options:
     203usage: tracd [-h] [--version] [-e PARENTDIR | -s]
     204             [-a DIGESTAUTH | --basic-auth BASICAUTH] [-p PORT] [-b HOSTNAME]
     205             [--protocol {http,https,scgi,ajp,fcgi}] [--certfile CERTFILE]
     206             [--keyfile KEYFILE] [-q] [--base-path BASE_PATH]
     207             [--http10 | --http11] [-r | -d] [--pidfile PIDFILE]
     208             [--umask MASK] [--group GROUP] [--user USER]
     209             [envs [envs ...]]
     210
     211positional arguments:
     212  envs                  path of the project environment(s)
     213
     214optional arguments:
     215  -h, --help            show this help message and exit
    205216  --version             show program's version number and exit
    206   -h, --help            show this help message and exit
    207   -a DIGESTAUTH, --auth=DIGESTAUTH
     217  -e PARENTDIR, --env-parent-dir PARENTDIR
     218                        parent directory of the project environments
     219  -s, --single-env      only serve a single project without the project list
     220  -a DIGESTAUTH, --auth DIGESTAUTH
    208221                        [projectdir],[htdigest_file],[realm]
    209   --basic-auth=BASICAUTH
     222  --basic-auth BASICAUTH
    210223                        [projectdir],[htpasswd_file],[realm]
    211   -p PORT, --port=PORT  the port number to bind to
    212   -b HOSTNAME, --hostname=HOSTNAME
     224  -p PORT, --port PORT  the port number to bind to
     225  -b HOSTNAME, --hostname HOSTNAME
    213226                        the host name or IP address to bind to
    214   --protocol=PROTOCOL   http|scgi|ajp|fcgi
    215   -q, --unquote         unquote PATH_INFO (may be needed when using ajp)
    216   --http10              use HTTP/1.0 protocol version instead of HTTP/1.1
    217   --http11              use HTTP/1.1 protocol version (default)
    218   -e PARENTDIR, --env-parent-dir=PARENTDIR
    219                         parent directory of the project environments
    220   --base-path=BASE_PATH
     227  --protocol {http,https,scgi,ajp,fcgi}
     228                        the server protocol (default: http)
     229  --certfile CERTFILE   PEM certificate file for HTTPS
     230  --keyfile KEYFILE     PEM key file for HTTPS
     231  -q, --unquote         unquote PATH_INFO (may be needed when using the ajp
     232                        protocol)
     233  --base-path BASE_PATH
    221234                        the initial portion of the request URL's "path"
     235  --http10              use HTTP/1.0 protocol instead of HTTP/1.1
     236  --http11              use HTTP/1.1 protocol (default)
    222237  -r, --auto-reload     restart automatically when sources are modified
    223   -s, --single-env      only serve a single project without the project list
    224238  -d, --daemonize       run in the background as a daemon
    225   --pidfile=PIDFILE     when daemonizing, file to which to write pid
    226   --umask=MASK          when daemonizing, file mode creation mask to use, in
    227                         octal notation (default 022)
    228   --group=GROUP         the group to run as
    229   --user=USER           the user to run as
     239  --pidfile PIDFILE     file to write pid when daemonizing
     240  --umask MASK          when daemonizing, file mode creation mask to use, in
     241                        octal notation (default: 022)
     242  --group GROUP         the group to run as
     243  --user USER           the user to run as
    230244}}}
    231245
    … …  
    236250=== Serving static content
    237251
    238 If `tracd` is the only web server used for the project,
    239 it can also be used to distribute static content
    240 (tarballs, Doxygen documentation, etc.)
    241 
    242 This static content should be put in the `$TRAC_ENV/htdocs` folder,
    243 and is accessed by URLs like `<project_URL>/chrome/site/...`.
    244 
    245 Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file,
    246 the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`,
    247 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).
     252If `tracd` is the only web server used for the project, it can also be used to distribute static content, such as tarballs, Doxygen documentation, etc.
     253
     254This static content should be put in the `$TRAC_ENV/htdocs` folder, and is accessed by URLs like `<project_URL>/chrome/site/...`.
     255
     256Example: given a `$TRAC_ENV/htdocs/software-0.1.tar.gz` file, the corresponding relative URL would be `/<project_name>/chrome/site/software-0.1.tar.gz`, 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).
    248257
    249258=== Using tracd behind a proxy
    … …  
    258267
    259268=== Authentication for tracd behind a proxy
    260 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].
     269
     270It is convenient to provide central external authentication to your tracd instances, instead of using `--basic-auth`. See also [trac:#9206].
    261271
    262272Below is example configuration based on Apache 2.2, mod_proxy, mod_authnz_ldap.
    … …  
    284294    implements(IAuthenticator)
    285295
    286     obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false', 
    287                """Whether the 'Remote-User:' HTTP header is to be trusted for user logins 
    288                 (''since ??.??').""") 
     296    obey_remote_user_header = BoolOption('trac', 'obey_remote_user_header', 'false',
     297               """Whether the 'Remote-User:' HTTP header is to be trusted for user logins
     298                (''since ??.??').""")
    289299
    290300    def authenticate(self, req):
    291         if self.obey_remote_user_header and req.get_header('Remote-User'): 
    292             return req.get_header('Remote-User') 
     301        if self.obey_remote_user_header and req.get_header('Remote-User'):
     302            return req.get_header('Remote-User')
    293303        return None
    294304
    … …  
    308318}}}
    309319
    310 Note that if you want to install this plugin for all projects, you have to put it in your [TracPlugins#Plugindiscovery global plugins_dir] and enable it in your global trac.ini.
     320Note that if you want to install this plugin for all projects, you have to put it in your [TracPlugins#Plugindiscovery global plugins_directory] and enable it in your global `trac.ini`.
    311321
    312322Global config (e.g. `/srv/trac/conf/trac.ini`):
    … …  
    327337
    328338=== Serving a different base path than /
    329 Tracd supports serving projects with different base urls than /<project>. The parameter name to change this is
     339
     340Tracd supports serving projects with different base urls than `/<project>` with the `base_path` parameter:
    330341{{{#!sh
    331342 $ tracd --base-path=/some/path