= Trac on Windows Installation & Upgrade Guide =
What follows are specific instructions for installing, setting up, and upgrading Trac on Windows.
Choose between these options of installing Trac:
* [wiki:TracOnWindowsStandalone Trac running without Apache or IIS] using [source:trunk/README.tracd#latest tracd] and svnserve is the simplest setup. It is stripped for all optional dependencies. It might be taken as a first step to get things running. You should then be able to pick the missing steps from the Apache CGI based setup found on this page as a second step.
* The 'traditional' [wiki:TracOnWindows#InstallationofSubversionandTrac0.8.4servedviaApacheCGI Apache CGI based setup] is described just below.
* Also, after installing the CGI-based setup, you may want to [wiki:TracModPython switch to using mod_python] which speeds up Trac's response times considerably.
If you are trying to upgrade to Trac 0.9, [wiki:TracOnWindows#UpgradingfromTrac0.84to0.9beta1onWindows see the instructions] at the end of this file.
== Installation of Subversion and Trac 0.8.4 served via Apache CGI ==
Versions used in this example (June 2005-06-29):
* Trac 0.8.4
* [http://www.clearsilver.net Clearsilver 0.9.14 binaries]
* [http://www.python.org Python 2.3.5]
* [http://httpd.apache.org/ Apache 2.0.54]
* [http://subversion.tigris.org Subversion 1.2.0]
* [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91&filter=_py.zip Python 2.3 Bindings for subversion 1.2.0]
* [http://sourceforge.net/project/showfiles.php?group_id=38414 docutils 0.3.9]
* [http://www.sqlite.org SQLite 3.2.2]
* [http://initd.org/pub/software/pysqlite/releases/1.1/1.1.6/pysqlite-1.1.6.win32-py2.3.exe PySQLite 1.1.6-py2.3]
* [http://gnuwin32.sourceforge.net/packages/diffutils.htm Diffutils 2.8.7-1] (Optional)
'''Please update this Wiki page if you find it is different from your experience.'''
If you have any problems, I would also suggest posting the solutions there for the common good.
Please reference the version number you are having difficulties with, but assume that readers will be using the latest version (and issues from previous versions can disappear into wiki history)
Contributors: please add your name to the list at the end - Thanks in advance!
''For Subversion issues on Windows see the [http://tortoisesvn.tigris.org TortoiseSVN] site, particularly the server section.''
''Trac running on Microsoft's Internet Information Server (IIS) is __highly__ experimental. See #697.''
=== Learn Subversion ===
1. Get & Read [http://svnbook.red-bean.com/ Version Control with Subversion ]
=== Install Subversion Pre-Requisites ===
2. Install [http://www.python.org/ Python ]
[[br]]Add C:\Python23 to the path
3. Install [http://httpd.apache.org/ Apache ]
4. Install [http://subversion.tigris.org/ Subversion ]
Note: Be sure to have the MSVCP60.DLL in your PATH, otherwise Apache will refuse to start with the SVN module.
5. Install [http://docutils.sourceforge.net/ docutils ]
{{{
expand and run from the expanded docutils-xxx directory
> C:\python23\python setup.py install
}}}
=== Create Repository ===
6. Create repository directory
{{{
C:\> md c:\svn
}}}
7. Create repository
{{{
C:\> svnadmin create --fs-type=fsfs c:\svn\repo1
}}}
''FSFS should be the preferred Subversion Repository filesystem on Windows. The Python bindings are much more reliable in that case -- ChristianBoos''
8. Create skeleton repository structure in c:\temp\project
Example:
{{{
/project
/vendor
/tags
/trunk
files
/projectname
/branches
/tags
/trunk
files
}}}
9. Build repository tree
{{{
C:\> svn import c:\temp\project file:///c:/svn/repo1 -m "Initial Load"
}}}
10. Create local sandbox
{{{
C:\> svn checkout file:///c:/svn/repo1 c:\project
}}}
=== Configure Apache ===
11. Copy files
{{{
C:\> copy c:\progra~1\subver~1\httpd\*.* c:\progra~1\apache~1\apache2\modules
}}}
In my Subversion installation (1.2.1-r15230) the so files are located
{{{
C:\> copy c:\Progra~1\Subver~1\bin\*.so c:\progra~1\apache~1\apache2\modules
}}}
You may also need to manually transfer the DLL files from the Subversion installation directory. If the Apache service will not start, or reports an error loading mod_dav_svn.so, you will need to do this. They contain, among other things, the Berkeley DB. This is all you need to do for the DLLs:
{{{
C:\> copy c:\progra~1\subver~1\bin\*.dll c:\progra~1\apache~1\apache2\modules
}}}
12. Create password file (w/user 'admin')
{{{
C:\> c:\progra~1\apache~1\apache2\bin\htpasswd -cm c:\svn\.htaccess admin
}}}
13. Configure Apache (edit httpd.conf)
13.1. [http://www.webdevelopersjournal.com/software/apache_more_config.html Restrict access/lockdown ] as appropriate
13.2. Add Modules to httpd.conf
13.1.1. Uncomment:
{{{
LoadModule dav_module modules/mod_dav.so
LoadModule dav_fs_module modules/mod_dav_fs.so
}}}
13.1.2. Add (after):
{{{
# Subversion
LoadModule dav_svn_module modules/mod_dav_svn.so
LoadModule authz_svn_module modules/mod_authz_svn.so
}}}
13.1.3. Install Apache as Service (IF NOT WORKING when installed to C:)
{{{
C:\Progr~1\Apache~1\Apache2\bin\Apache -k install -n "Apache2"
}}}
13.3. Add location root for multiple repositories
{{{
# Subversion
DAV svn
# any /svn/foo URL will map to a repository C:/svn/foo
# I've only got it working using SVNPath!!
SVNParentPath C:/svn
AuthType Basic
AuthName "Subversion repository"
AuthUserFile c:/svn/.htaccess
Require valid-user
}}}
13.4. Add cgi handler, Uncomment:
{{{
AddHandler cgi-script .cgi
}}}
14. Restart Apache
15. Test your install of Subversion
http://[hostname]:80/svn/repo1
----
=== Create Users ===
16. Add users to password file
{{{
C:\> c:\progra~1\apache~1\apache2\bin\htpasswd -m c:\svn\.htaccess user
}}}
=== Install Trac Prerequisites ===
(Please note: pay attention to download '''exactly''' the versions mentioned here. Do '''not''' simply download the latest stable versions. Otherwise you will probably run into several issues.)
17. Install Subversion Python Bindings
Download [http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91&filter=_py.zip svn-win32-1.2.X_py.zip] from the Subversion site. [[br]]Extract and copy the libsvn and svn directories to C:\Python23\Lib
18. Install SQLite (optional)
http://www.sqlite.org
[[br]]Copy sqlite.exe to C:\Program Files\SQLite
This is really optional - you only need this if you want to start poking around in the sqlite database because something's gone wrong.
19. Install PySQLite
http://pysqlite.org/
[[br]]Download and install pysqlite-1.1.6.win32-py2.3.exe
NB. Make sure you use v1.x, not 2.x, because the module is renamed from sqlite to pysqlite in v2.x, so the trac installer will fail if you use pysqlite 2.x
20. Install ClearSilver
http://www.clearsilver.net download clearsilver_python-0.9.12-win32.zip
[[br]]Copy neo_cgi.pyd into C:\Python23\Lib\site-packages
Alternatively, grab unofficial installers for ClearSilver 0.9.14 from http://clearsilver.yi.org/.
21. Install Trac
http://projects.edgewall.com/trac/wiki/TracDownload
{{{
python ./setup.py install
}}}
=== Fix a few things ===
22. Copy CGI
{{{
C:\> copy c:\python23\share\trac\cgi-bin\trac.cgi c:\progra~1\apache~1\apache2\cgi-bin
}}}
Use a text editor such as notepad to open trac.cgi and ensure the first line contains the correct path for Apache to find python.
=== Configure Trac DB ===
The trac database can be named to match the subversion repository it is working with, which is especially useful if more than one repository will ever be created. In this example {{{"trac.db"}}} would read as {{{"repo1.db"}}}
25. Run trac-admin
{{{
C:\Python23\Scripts> python trac-admin c:/svn/trac.db
}}}
26. Initialize DB
{{{
Trac [c:/svn/trac.db]> initdb
}}}
or
{{{
Trac [c:/svn/trac.db]> initenv
}}}
{{{
Enter project name
Project
Enter path to repository
c:\svn\repo1
Enter path to templates
c:\Python23\share\trac\templates
}}}
If you get an error here stating that libdb42.dll was not found, copy ''[SVN PATH]''\bin\libdb42.dll to ''[PYTHON PATH]''\lib\libsvn\, then try again.
If you get an error about execute() argument 1 on !CheckWiki.pyo, delete !CheckWiki.pyo from the c:\Python23\share\trac\templates directory. It shouldn't be there, but is when configuring 0.8.2 by hand instead of using the installer.
To get this step done the right way, you have to understand that the trac database is '''not''' the svn repository.
For expample if you have your svn repository located in c:\svn\repo1 (like supposed by this tutorial), you'll probably want to name your trac database c:\trac\repo1. You would then call "python trac-admin c:/trac/repo1" in your scripts directory and enter "c:\svn\repo1" as the "path to (svn) repository".
27. (BUG) Load Wiki See Ticket #1648
(NB. This is fixed in the latest trac, so ignore this step if you installed v0.8.3 or later)
{{{
Trac [c:/svn/trac.db]> wiki load c:/python23/share/trac/wiki-default
}}}
28. Add administrative permissions (the below adds all permissions for 'admin' user)
{{{
Trac [c:/svn/trac.db]>
permission add admin TRAC_ADMIN
}}}
=== Add Trac to Apache ===
29. Edit httpd.conf:
Add: (copy this - there's a typo in Edgewall's version)
{{{
# TRAC
Alias /trac "C:/Python23/share/trac/htdocs"
SetEnv TRAC_ENV "c:/svn/trac.db"
AuthType Basic
AuthName "Project"
AuthUserFile C:/svn/.htaccess
Require valid-user
Options Indexes MultiViews
AllowOverride None
Order allow,deny
Allow from all
}}}
Alternatively you could set up the authorisation to use your NT domain login if you are running an NT Domain. This bit of Apache config replaces the given above.
{{{
#NT Domain auth config
AuthType SSPI
SSPIAuth On
SSPIAuthoritative On
SSPIOfferBasic On
SSPIOmitDomain Off
# following line squishes bug #1168 if IE has troubles editing wiki pages.
SSPIBasicPreferred On
AuthName "Project"
Require valid-user
}}}
You'll also need the sspi_auth_module on your system and loaded like this...
{{{
LoadModule sspi_auth_module modules/mod_auth_sspi.so
}}}
You must download and install this module. It can be found here:
http://www.gknw.net/development/apache/httpd-2.0/win32/modules/mod_auth_sspi-1.0.2-2.0.54.zip
Or compile it into Apache. Note when adding permissions and authenticating against a domain you may need to use the following syntax complete with quotes as seen in #1055.
* permission add "DOMAIN\username" TRAC_ADMIN
''Note'': Internet Explorer may be in trouble with an Apache server running SSPI authentication. See #1343
With example above, you must specify user name like "DOMAIN\username"
If you hate "DOMAIN\username" format, {{{SSPIOmitDomain}}} option is usefull. Set it ON!
{{{
SSPIOmitDomain On
}}}
If this option is ON, the mod_auth_sspi passes authentication name to an Apache server without a domain part.
As result, you can manage user names with simply 'username' instead of 'DOMAIN\username'
in apache password file and {{{trac-admin}}} command, and also, it is used by Trac for reporter name, author and so on.
* permission add username TRAC_ADMIN
But remember that you must specify "DOMAIN\username" format on authentication dialog although this option is ON.
''Note'': Older version of mod_auth_sspi (like http://tortoisesvn.tigris.org/mod_auth_sspi.zip) doesn't
support {{{SSPIOmitDomain}}} and has bug for basic authentication. 1.0.2 introduced above is recommended.
30. Restart Apache.
31. Hold your breath, test Trac install
http://[hostname]:80/cgi-bin/trac.cgi
If it doesn't work, then running Apache from the command-line will give you a few clues.
If your page seems to be lacking stylesheets, please check the alias of '''/trac''' in apache. Otherwise you've probably run into a known Apache bug described (and worked around) [http://www.apache.org/dist/httpd/binaries/win32/#xpbug here].
=== Optional Diffutils ===
32. In order for Trac to display diffs, you must download and install [http://gnuwin32.sourceforge.net/packages/diffutils.htm diffutils]. After installing diffutils, you will need to add the path to the diff executable to the Windows PATH environment variable. '''Note:''' If Apache is running as a service you will need to reboot the machine for it to receive the updated PATH setting.
=== Finally... ===
33. Install Subversion clients as necessary (try [http://rapidsvn.tigris.org RapidSVN] , [http://tortoisesvn.tigris.org/ TortoiseSVN] or [http://subclipse.tigris.org/ Subclipse])
34. Don't forget to lock down the security on the box!
35. If the svn page would not work properly with saying that DLL is missing, then copy the three DLL's - libdb42.dll - libeay32.dll - ssleay32.dll from your [Subversion]\bin directory to your system directory (most likely C:\Windows\system32).
=== In addition... ===
36. In order to use pre- and post-commit hooks with Subversion on Windows, please refer to diff files described in #897, as the changes are not commited into the trunk as of version 0.8-dev.
== Upgrading from Trac 0.84 to 0.9-beta1 on Windows ==
This section builds off the [wiki:TracUpgrade generic Trac upgrade instructions], so you may want to keep that open to use as supplementary reading material.
1. Download Windows Installer file
2. Backup old version of Trac:
{{{
> move C:\Python23\Lib\site-packages\trac C:\Python23\Lib\site-packages\trac-0.8.4
> move C:\Python23\share\trac C:\Python23\share\trac-0.8.4
> move C:\Program Files\Apache Group\Apache2\cgi-bin\trac.cgi C:\Program Files\Apache Group\Apache2\cgi-bin\trac-0.8.4.cgi
> xcopy /x C:\svn\trac.db C:\svn\trac-0.8.4.db\
}}}
3. Run the Trac Windows Installer
4. Run these commands
{{{
> C:\Python23\Scripts\python trac-admin C:\svn\trac.db upgrade
> C:\Python23\Scripts\python trac-admin C:\svn\trac.db wiki upgrade
}}}
5. If using CGI, copy trac.cgi to Apache directory.
{{{
> copy C:\Python23\share\trac\cgi-bin\trac.cgi C:\Program Files\Apache Group\Apache2\cgi-bin\trac.cgi
}}}
6. Open and edit C:\Program Files\Apache Group\Apache2\cgi-bin\trac.cgi. Change the first line from:
{{{
#!C:\Programme\Python23\python.exe
}}}
to
{{{
#!C:\Python23\python.exe
}}}
7. Point your web browser to the Trac site. That should be it!
=== Contributors: ===
* [mailto:Daragh|at|i2i-Tech.com Daragh Fitzpatrick]
* [mailto:alexkw|at|mac.com Alex Wolfe]
* [mailto:tim|at|igethalf.com Tim Browse]
* [mailto:sid|at|seegrid.com Sid Wiesner]
* [mailto:trac-svn-mail|at|elvendesigns.com Muir]
=== Comments ===
==== Really Wonderful ====
This is one of the best docs on how install a system. Thank you very much.
The only thing I don't understand is what should I do "to lock down the security on the box". Excuse me, I'm a begineer in this things, Could somebody explain a little bit? Thanks, a lot!