Setting up a complete Subversion, Trac and Web Development Environment

[eluser]Murodese[/eluser]
Disclaimer: I am doing this completely from memory. I've gotten this working over the last <large amount of weeks>, so my memory of it is pretty faded.

However, someone asked me to describe it, so here it is. If you get error messages and the like, just post and I should be able to help out.


Hardware Requirements:

x Client PCs (fairly os-inspecific)
1 Development Server (ours is a box running Debian Lenny)


Software Requirements:

Client PCs:

- An IDE that supports subversion in some way - we use Eclipse with Aptana (setup below), but any client that supports svn should be ok.
- Some way of autosyncing to the development server's working folder. For windows, this is WinSCP. I don't know of any mac program that can do it.

Server:

- A LAMP stack - we use apache2/php5/mysqld5
- FTP/SFTP server - we use MySecureShell
- Subversion
- Trac
- PHPDocumentor



Setting up the server:

Firstly you need to set up a basic lamp stack. There are a bajillion tutorials on this elsewhere, so I'm not going to cover it. Substitute apt for the package manager of your distro, this is just for a general idea of the packages required.

Once you've got apache, mysql and php working together, you need to install subversion and trac.

Code:

apt-get install subversion libapache2-svn trac

Now we set up project folders.

Code:

mkdir -p /var/local/svn/<project name>
mkdir -p /var/local/trac/<project name>

svnadmin create /var/local/svn/<project name>
trac-admin /var/local/trac/<project name> initenv

Next we need to add users, add them to the apache group and set access permissions.

Code:

adduser <username>
addgroup <username> www-data

cd /var/local/svn/<project name>/conf
htpasswd -c passwd <username to allow>
(add a password)
htpasswd passwd <next username>

Next, adding the apache handlers. For this, I have the following urls (obviously domain.tld is your host):

http://<project name>.svn.domain.tld/
http://<project name.trac.domain.tld/

http://domain.tld/<project name>/trunk
http://domain.tld/<project name>/working/<user>
http://domain.tld/<project name>/docs

This means that to use svn or trac, you'd connect to the first two urls. For viewing the current working copies or trunk build on the website itself, you'd use the bottom ones. The documentation is autogenerated each commit and put into docs.

So, we have the following apache config files;

Code:

vim /etc/apache2/sites-enabled/trac.domain.tld.conf

<VirtualHost *>
    ServerName <project name>.trac.domain.tld
    DocumentRoot /var/local/trac/

    <Location />
        SetHandler mod_python
        PythonHandler trac.web.modpython_frontend
        PythonInterpreter main_interpreter
        PythonOption TracEnv /var/local/trac/<project name>/
        PythonOption TracUriRoot /
        AuthType Basic
        AuthName "<project name>.trac.domain.tld"
        AuthUserFile /var/local/svn/<project name>/conf/passwd
        Require valid-user
    </Location>

    CustomLog /var/log/apache2/<project name>/access.log combined
    ErrorLog /var/log/apache2/<project name>/error.log
</VirtualHost>

---

vim /etc/apache2/sites-enabled/svn.domain.tld.conf

<VirtualHost *>
        ServerName <project name>.svn.domain.tld
        <Location />
                DAV svn
                AuthType Basic
                AuthName "<project name>.svn.domain.tld"
                AuthUserFile /var/local/svn/<project name>/conf/passwd
                SVNPath /var/local/svn/<project name>/
                Require valid-user
        </Location>

        CustomLog /var/log/apache2/<project name>/custom.log combined
        ErrorLog /var/log/apache2/<project name>/error.log
</VirtualHost>

---

vim /etc/apache2/sites-enabled/domain.tld.conf

<VirtualHost *>
        DocumentRoot /var/www/
        ServerName domain.tld
        <Directory "/var/www">
                Order allow,deny
                Allow from all
                Options ExecCGI FollowSymLinks +Indexes MultiViews
                AllowOverride all
        </Directory>
</VirtualHost>

Make sure you create the log folders if they don't exist, and then you can restart apache (/etc/init.d/apache2 restart).

Next, we want to set up our post-commit hooks. You also need to install phpdoc, but off the top of my head I don't remember if aptitude has a package for it. Failing that, get it off PEAR (go to their site).

Code:

cp /var/local/svn/<project name>/hooks/post-commit.tmpl /var/local/svn/<project name>/hooks/post-commit
chmod g+x /var/local/svn/<project name>/hooks/post-commit

Code:

vim /var/local/svn/<project name>/hooks/post-commit

#!/bin/sh -p

REPOS="$1"
REV="$2"
TRAC_ENV="/var/local/trac/<project name>"

/usr/bin/python /var/local/svn/<project name>/hooks/trac-post-commit-hook.py -p "$TRAC_ENV" -r "$REV"
/usr/bin/svn checkout http://<project name>.svn.domain.tld/trunk /var/www/<project name>/trunk
/usr/bin/phpdoc -c /var/local/svn/<project name>/hooks/phpdoc.ini
exit 0

And create the phpdoc config file as /var/local/svn/<project name>/hooks/phpdoc.ini. To see how to do this, check out the phpdoc documentation. When setting where to output the data to, you want it as /var/www/<project name>/docs

Set up your trac environment (using the trac documentation) and you're pretty much done. Install your ftp server of choice, and (if supported), make the following change to the users' default jail:

ie. MySecureShell

Code:

Home /var/www/<project path>/working/$USER

Obviously once you set up more than a single project, you'll need to organise your directories slightly better.

But I'm super lazy, so onto the client.

[eluser]Murodese[/eluser]
Setting up Aptana

Modify this to suit your client if you don't want to use aptana. At the very least, the IDE will want to have built-in svn support and very preferably some kind of ftp auto-sync option. If you're using windows, you can just use WinSCP - no idea what mac users can use.

To install aptana as a plugin to eclipse (because the standalone is horribly bad), do the following:

1) Install JRE 6 32-bit from the Sun site.

2) Download and install Eclipse 3.5SM3 from http://download.eclipse.org/eclipse/down.../index.php. It could probably work with any version >3.4.

3) Open eclipse and go help -> software updates -> find and install

4) Click search new features, then New Remote Site and add the site http://update.aptana.com/update/studio/3.2/

5) Go through the trees and install your selected packages (I grabbed everything except Aptana Pro because I find that it tends to break things)

6) Wait for everything to download and click install all. Restart eclipse when it asks to.

7) Once it is up and running, close the eclipse welcome screen. You should see an in-window page called My Aptana. Click plugins on the site, and install your preferred plugins (ie. PHP for Aptana).

8) Restart again once requested.

9) Go back into find and install and add another new remote site, this time http://download.eclipse.org/tools/mylyn/update/e3.4.

10) Same deal, install mylyn and restart when requested, then go back into find and install and there should be some new sources - another Mylyn and Mylyn Extras. Check both and install the Trac Bridge plugin when able.

11) Restart eclipse for what should be the last time, and you can go window->show perspective->aptana if you so wish (much recommended).


At some stage, eclipse probably also asked if it could install the Subversion addin. You should allow this, as it's pretty integral to our install.

Also to note: no you can't use the 64-bit version of eclipse, or the 64-bit version of the JRE. Using one or the other will error everything horribly, and using both 64-bit will break xulrunner, a required component of Aptana. Use 32-bit.

Once everything is set up, go Window->Show View->Other->SVN->Svn Repository. A new sub-window should open, which allows you to add repositories. You want to add http://svn.<project name>.domain.tld/.

This means you can now go File->New->Projects->SVN->Checkout Projects from SVN, which allows you to check out an svn copy of a project and build a project out of it. This is what we want to do, but first you'll need some initial data in your repository. I'm not going to cover this because it's pretty opinion-based, but it'll generally have a few folders in it - trunk, branches and tags. Look at the SVN documentation as to how to set this up.

Once your project is created, it should've checked out your repository to your workspace on your computer. For me, this is just C:\Users\<name>\Workspace, which is the default.

You want to open WinSCP and add your FTP server to the saved sites. Once that's done, click Commands->Keep remote directory up to date. In the Watch for Changes textbox, put the path to your project. Remote directory will generally just be /, though this varies based on how you set up your ftp server.

Under options, check Delete files and update subdirectories, and check sync on start. Then go to transfer settings, and click configure. Click add, call it SVN and do the following:

- Transfer mode automatic
- Set Permissions to whatever you wish (mine are generally 775 to avoid irritating web server / ftp server fuckery)
- Automatically select this present when: hostname mask = domain.tld
- Exclude mask */.svn/

Then you can click start, and assuming there was data in your project, it'll do an initial sync. Minimise this window because it'll stay open and autosync your local folder to your working folder on the web server for you to test with.

Develop! If you haven't used svn before, remember to team->update often and only commit working code or other teammates will send demons to kill you :x

The rest of svn I leave up to you to work out or learn through the docs.

--

Extras

Configs

Because CodeIgniter config files change per user (the url changes, the database may or may not change depending on how you want it), you can do the following:

- Rename config.php and database.php to config.php-recommended and database.php-recommended.
- Add those two files to source control (right click in project view -> team -> add to version control)
- Add config.php and database.php to svn:ignore (right click in project view -> team -> add to svn:ignore)

Now after people check out their local copies, they can copy the config.php-recommended and database.php-recommended files back to their proper names and change to suit their requirements - and when they commit, the normal config files won't get committed with them.

Trac Commit Comments

The trac commit hook grabs comments during commits and parses them for various trigger commands. Look up the documentation for trac for full details, but generally you'll use the following two;

fix/fixed/fixes/close/closes/closed #<ticket number>: extra comments

You can use any of the trigger words, and that will automatically close that ticket and append the commit message to the content of the ticket. You can also use ref/refs if you want the commit message to be saved in the ticket, but not to close or modify the ticket at all.

Mylyn

Mylyn is an eclipse plugin that hooks into trac. I'm not going into it because I'm hungry and want to go get food, but it's pretty awesome. It lets you see and create tickets directly through eclipse, and there's some context-based code ticketing stuff that happens too but again, look at the docs. I mainly just wanted to let you know of the existence of it :v


--

Oh yeah, and there is a phpdoc converter called ExtJS that is horribly awesome.

[eluser]Murodese[/eluser]
MASSIVE WALL OF TEXT.

Hopefully someone finds it useful.

[eluser]maesk[/eluser]
Great, very useful, thanks a lot!!!

[quote author="Murodese" date="1226602047"]
To install aptana as a plugin to eclipse (because the standalone is horribly bad)
[/quote]

I tried Aptana a while back and didn't like it that much (clunky, slow, too many features I don't use) but I keep reading here that it's great. Could you explain in what way the eclipse plugin differs from the standalone version and why it's better?

[eluser]Murodese[/eluser]
[quote author="maesk" date="1226605425"]Great, very useful, thanks a lot!!!

[quote author="Murodese" date="1226602047"]
To install aptana as a plugin to eclipse (because the standalone is horribly bad)
[/quote]

I tried Aptana a while back and didn't like it that much (clunky, slow, too many features I don't use) but I keep reading here that it's great. Could you explain in what way the eclipse plugin differs from the standalone version and why it's better?[/quote]

Standalone Aptana is based on eclipse 3.2, which is getting pretty dated now. On top of that, a lot of things like Subclipse (a eclipse subversion plugin) breaks quite often on 3.2.

Basically, lots of fixes in base eclipse + fixes in eclipse plugins make for a much more stable and speedy ide than standalone aptana.

[eluser]maesk[/eluser]
By "Standalone eclipse" you mean "Standalone Aptana", I suppose. Ok, makes sense, I will try it again then, sometime.

[eluser]Murodese[/eluser]
[quote author="maesk" date="1226610446"]By "Standalone eclipse" you mean "Standalone Aptana", I suppose. Ok, makes sense, I will try it again then, sometime.[/quote]

Whoops, yeah. Getting late.

[eluser]nanda[/eluser]
Thanks for the great howto!

My vote goes for PTD over Aptana.

[eluser]maria clara[/eluser]
@murodese,,

hi.. do you have an instruction for setting it up with eclipse + pdt or in netbeans??? can you please post it??

thanks in advance,
kahtrina

[eluser]kurucu[/eluser]
WinSCP for mac = scp! Remember it's based (to some extent) on unix, so it will be nicely compatible with your Linux server. Also, you might like to consider rsync for the mac/linux exchange instead.

Finally, I use Coda on the Mac, which is has SVN client built-in and provides a very stable, fast and uncluttered interface, with autocomplete and a variety of other nice little touches. Coda also allows you to set up a local working (SVN-linked, if liked) folder and a remote folder, which could be over an SCP or other destination. Then you just hit 'publish' and the files are copied. For the setup you're describing though, I'd stick to Local, SVN and allow rsync/scp to keep the remote version up to date.

Hope that plugs some of the Mac holes!