Trac

Warning:
So far, Unit doesn’t support handling the REMOTE_USER headers directly, so authentication should be implemented via external means. For example, consider using trac-oidc or OAuth2Plugin.

To run the Trac issue tracking system using Unit:

1. Install Unit with a Python 2 language module.

   As of now, Trac doesn’t fully support Python 3. Mind that Python 2 is officially deprecated.

2. Prepare and activate a virtual environment to contain your installation (assuming virtualenv is installed):

   console

   Copy

   mkdir -p /path/to/app/  # Path to the application directory; use a real path in your configuration
   

   mkdir -p /path/to/app/  # Path to the application directory; use a real path in your configuration
   

   console

   Copy

   cd /path/to/app/  # Path to the application directory; use a real path in your configuration
   

   cd /path/to/app/  # Path to the application directory; use a real path in your configuration
   

   console

   Copy

   virtualenv venv
   

   virtualenv venv
   

   console

   Copy

   source venv/bin/activate
   

   source venv/bin/activate
   

3. Next, install Trac and its optional dependencies, then initialize a Trac environment and deploy static files:

   console

   Copy

   pip install Trac
   

   pip install Trac
   

   console

   Copy

   pip install babel docutils genshi \
                 pygments pytz textile             # optional dependencies
   

   pip install babel docutils genshi \
                 pygments pytz textile             # optional dependencies
   

   console

   Copy

   mkdir static/  # Arbitrary directory name, will store Trac's /chrome/ tree
   

   mkdir static/  # Arbitrary directory name, will store Trac's /chrome/ tree
   

   console

   Copy

   mkdir trac_env/ # Arbitrary directory name
   

   mkdir trac_env/ # Arbitrary directory name
   

   console

   Copy

   trac-admin trac_env/ initenv                  # initialize Trac environment
   

   trac-admin trac_env/ initenv                  # initialize Trac environment
   

   console

   Copy

   trac-admin trac_env/ deploy static/           # extract Trac's static files
   

   trac-admin trac_env/ deploy static/           # extract Trac's static files
   

   console

   Copy

   mv static/htdocs static/chrome                # align static file paths
   

   mv static/htdocs static/chrome                # align static file paths
   

   console

   Copy

   rm -rf static/cgi-bin/                        # remove unneeded files
   

   rm -rf static/cgi-bin/                        # remove unneeded files
   

   console

   Copy

   deactivate
   

   deactivate
   

4. Unit uses WSGI to run Python apps, so a wrapper script is required to run Trac as a Unit app; let’s save it as /path/to/app/trac_wsgi.py. Here, the application callable serves as the entry point for the app:

   python

   Copy

   import trac.web.main
   
   def application(environ, start_response):
      environ["trac.locale"] = "en_US.UTF8"
      return trac.web.main.dispatch_request(environ, start_response)

   import trac.web.main
   
   def application(environ, start_response):
      environ["trac.locale"] = "en_US.UTF8"
      return trac.web.main.dispatch_request(environ, start_response)

5. Change ownership:

   Run the following command (as root) so Unit can access the application directory (If the application uses several directories, run the command for each one):

   console

   Copy

   # chown -R unit:unit /path/to/app/  # User and group that Unit's router runs as by default
      

   # chown -R unit:unit /path/to/app/  # User and group that Unit's router runs as by default
      

   The unit:unit user-group pair is available only with official packages , Docker images, and some third-party repos. Otherwise, account names may differ; run the ps aux | grep unitd command to be sure.

   For further details, including permissions, see the security checklist.

6. Next, prepare the Trac configuration for Unit (use real values for share, path, home, module, TRAC_ENV, and PYTHON_EGG_CACHE):

   json

   Copy

   {
      "listeners": {
         "*:80": {
               "pass": "routes"
         }
      },
   
      "routes": [
         {
               "match": {
                  "uri": "/chrome/*"
               },
               "action": {
                  "share": "/path/to/app/static$uri"
               },
               "_comment_action": "Serves matching static files | Path to the static files; use a real path in your configuration"
         },
         {
               "action": {
                  "pass": "applications/trac"
               }
         }
      ],
   
      "applications": {
         "trac": {
               "type": "python 2",
               "path": "/path/to/app/",
               "_comment_path": "Path to the application directory; use a real path in your configuration",
               "home": "/path/to/app/venv/",
               "_comment_home": "Path to the application directory; use a real path in your configuration",
               "module": "trac_wsgi",
               "_comment_module": "WSGI module basename from Step 4 with extension omitted",
               "environment": {
                  "TRAC_ENV": "/path/to/app/trac_env/",
                  "_comment_TRAC_ENV": "Path to the Trac environment; use a real path in your configuration",
                  "PYTHON_EGG_CACHE": "/path/to/app/trac_env/eggs/"
               },
               "_comment_PYTHON_EGG_CACHE": "Path to the Python egg cache for Trac; use a real path in your configuration"
         }
      }
   }

   {
      "listeners": {
         "*:80": {
               "pass": "routes"
         }
      },
   
      "routes": [
         {
               "match": {
                  "uri": "/chrome/*"
               },
               "action": {
                  "share": "/path/to/app/static$uri"
               },
               "_comment_action": "Serves matching static files | Path to the static files; use a real path in your configuration"
         },
         {
               "action": {
                  "pass": "applications/trac"
               }
         }
      ],
   
      "applications": {
         "trac": {
               "type": "python 2",
               "path": "/path/to/app/",
               "_comment_path": "Path to the application directory; use a real path in your configuration",
               "home": "/path/to/app/venv/",
               "_comment_home": "Path to the application directory; use a real path in your configuration",
               "module": "trac_wsgi",
               "_comment_module": "WSGI module basename from Step 4 with extension omitted",
               "environment": {
                  "TRAC_ENV": "/path/to/app/trac_env/",
                  "_comment_TRAC_ENV": "Path to the Trac environment; use a real path in your configuration",
                  "PYTHON_EGG_CACHE": "/path/to/app/trac_env/eggs/"
               },
               "_comment_PYTHON_EGG_CACHE": "Path to the Python egg cache for Trac; use a real path in your configuration"
         }
      }
   }

   The route serves requests for static files in Trac’s /chrome/ hierarchy from the static/ directory.

7. Upload the updated configuration.

   Assuming the JSON above was added to config.json. Run the following command as root:

   console

   Copy

   # curl -X PUT --data-binary @config.json --unix-socket \
         /path/to/control.unit.sock \  # Path to Unit's control socket in your installation
         http://localhost/config/      # Path to the config section in Unit's control API
      

   # curl -X PUT --data-binary @config.json --unix-socket \
         /path/to/control.unit.sock \  # Path to Unit's control socket in your installation
         http://localhost/config/      # Path to the config section in Unit's control API
      

   The control socket path may vary; run unitd -h or see Startup and shutdown for details.

   After a successful update, Trac should be available on the listener’s IP address and port: