FAQ on editing the CAIA website
This page is continually under construction, and provides various bits of information for new and old members of CAIA.
Quick start
A really quick guide for people who are already familiar with SVN and Mordor
The website root directory is located at svn+ssh://username@svn.caia.swin.edu.au/home/svn/infrastructure/caiawww/data/, and updates are pushed to the CAIA webserver every 10 minutes.
The CAIA pages include Server Side Includes. To see your page with these rendered correctly, mount your Mordor home directory as a Samba/Windows share, and put your SVN working copy of the website in the ~/public_html/ directory on Mordor. You can then view your working copy at http://mordor/~username/<directory>/
All new HTML files should have the svn:executable bit set. Failure to set this when adding a HTML file to the repository will cause your commit to fail.
It is recommended to use public key authentication when using SVN+SSH.
SVN basics
What is SVN?
Version Control Systems (VCS) are used to track and control changes to a set of documents in a central location. They allow you to see what changes were made when, by who and when, as well as allowing you to see what the content looked like at any point in time previously. When more than one person is working on a project, a VCS will aid collaboration by making sure everyone gets every update that is made and no one accidentally overwrites someone else's changes.
Among other projects, CAIA's website is updated through the use of Subversion, one of the most popular VCS.
Every 10 minutes, CAIA's webserver checks for updates to the website from the SVN server.
Getting a copy of the website
The SVN server hosts a repository. This is where all of the content and its history reside. The repository keeps track of all of the changes, and is where the CAIA webserver fetches its content from.
The repository URL is:
svn+ssh://username@svn.caia.swin.edu.au/home/svn/infrastructure/caiawww/data/ . This directory is not accessible to normal users, but the content in child directories is accessible to the maintainers of the respective areas of the website.
When you download your own copy of the website to work on, this is called checking out. Your SVN client contacts the SVN server, asks for the latest revision of a given directory, and downloads it.
This copy of the website that exists on your workstation is called the working copy. You can make any changes you like to this copy without directly affecting the website.
Editing the website
Before editing a file, you should always update your working copy. This will contact the SVN server and make sure that you have the latest copy of the files you are working on. If someone else has edited the files since the last time you worked on them, it will ensure that your working copy reflects this. If you have edited your files since the last time someone else edited them and you didn't update beforehand, your SVN client will attempt to merge both changes in to the file.
If you edit a file and decide that you don't like the changes you have made, you can tell your SVN client to revert your changes. This process will revert your file back to the latest revision. You can also use the revert process to turn back the clock and make your working copy reflect the state of the website at an arbitrary point in the past.
Once you have edited your files and are happy with the changes, you must commit your changes. Committing your changes pushes them to the SVN server, where it becomes part of the latest revision of the repository.
Checking out/updating and committing in SVN
Previewing changes
Most of the pages that are a part of the CAIA website use Server Side Includes (SSIs), a very basic scripting language used to include files and execute other scripts. If you open one of your own HTML files in a browser, you will see that there is no Swinburne theme - this is because your browser does not know what to do with the SSI directives.
The webserver on Mordor is SSI enabled. Mounting your Mordor home directory, then keeping your working copy in a folder under ~/public_html/ allows you to see the pages as they would appear on the CAIA webserver.
A catch - creating new HTML files
Because the website uses Server Side Includes, each HTML file needs to be marked as executable. To make any HTML files you add executable, you need to modify your configuration file. In windows, %appdata%\subversion\config and in FreeBSD/Linux, ~/.subversion/config.
In this file, uncomment the line enable-auto-props = yes, and add the following two lines to the end of the file:
*.htm = svn:executable
*.html = svn:executable
Failure to do this will cause an error message to appear when you attempt to commit a new HTML file.
Avoid entering your password every time
Because we use SVN+SSH://, we can use public key authentication for the SSH portion of the connection. This means that we do not have to enter a password every time we perform an action with the SVN server. It is not necessary to use public key authentication, but it is a convenience for people who regularly update the website.
Windows
The SVN client
The preferred Windows SVN client is TortoiseSVN. TortoiseSVN integrates with the right click menu in Windows Explorer, and provides a fairly intuitive interface to SVN.
Getting a copy of the website
To check out a copy of the website:
- Create an empty folder.
- Right click on the folder and select "SVN Checkout..."
- Enter the URI of the area of the website you wish to edit
- EG, the FUN page would be svn+ssh://username@svn.caia.swin.edu.au/home/svn/infrastructure/caiawww/data/fun/ , since the FUN page is /fun/ on the CAIA webserver, also replacing username with your Mordor username
- Select OK, and enter your username and password
Your working copy is now up to date and in the folder you selected.
Editing the website
First, update your working copy:
- Right click on the folder containing your working copy and select "SVN Update"
- Select "OK" once it has completed
Your working copy is now up to date, and you are free to edit your files as you see fit.
Once you have finished editing and are ready to submit your changes, you must commit your changes.
- Make sure your files are all saved
- In Windows Explorer, right click on the folder containing your working copy
- Select "SVN Commit"
- Type a brief message describing the changes you have made in the provided text box
- EG, "Added new seminar to list" or "Fixed a typo on the L3DGEWorld page"
- Select OK and wait for it to finish
Within the next 10 minutes, your changes should appear on the CAIA webserver.
Committing in Tortoise SVN
Reverting changes
If you are unhappy with changes you have made, you can revert back to a previous revision from the SVN server.
- Right click on the folder that the working copy is in
- Select the "TortiseSVN" submenu
- Select "Revert"
- On the box that appears, ensure that only the files you wish to revert are selected
- Click OK
A similar method can be used to roll back your working copy to a previous revision.
- Right click on the folder that the working copy is in
- Select the "TortiseSVN" submenu
- Select "Update to revision"
- On the box that appears, select "Show log"
- On the next box that appears, use the list of revisions and their descriptions to find the revision you wish to roll back to (newest is at the top). Select the revision.
- Select "OK"
If you wish to roll back what appears on the CAIA website to a previous revision, follow the steps above to roll back your working copy, then follow the steps to commit your working copy.
Avoid entering your password every time
This is an optional step that is recommended for those who make regular changes to the website
On Windows, this is achieved through using PuTTYgen to create a public key pair, and the Pagaent daemon keeping the key in memory.
- Do these steps once:
- Download and install PuTTY and related tools. All programs will be installed under the 'PuTTY' group in your start menu.
- Mount your mordor home directory
- Open PuTTY, put mordor.caia.swin.edu.au in the hostname and click ok
- Enter your username and password when prompted.
- Run smbpasswd. Enter your password, then exit PuTTY.
- Open My Computer
- Select "Map network drive" (under the tools menu in XP)
- Put "\\mordor\username\" in the path and select M:\ for the drive letter (any letter will do, but M is used in our examples)
- Open PuTTYgen. Select "Generate" to create a new key pair. Move your mouse randomly to increase the randomness of the generated key.
- Ideally, enter a passphrase in the "Key passphrase" box - this will prevent your private key from being used without a password (eg, if you store it on a USB stick and lose it)
- Select "Save Private Key" and save the key somewhere safe
- Select "Save Public Key" and save the file on your mordor home directory (eg, M:\id_rsa.pub )
- Use PuTTY to SSH to mordor. Open PuTTY and put "mordor.caia.swin.edu.au" in the host name box and select OK. When prompted, enter your username and password
- Run this command, replacing username with your username: cat ~/id_rsa.pub | ssh username@svn.caia.swin.edu.au "mkdir -p ~/.ssh && tee >> .ssh/authorized_keys"
- Do these steps every time you need to use SVN and Pagaent has been closed:
- Open Pagaent (installed with PuTTY), and right click the icon in the system tray (It looks like a PC wearing a hat). Select "Add key". Open the .ppk file you saved in the previous step. If you used a passphrase to protect your private key, you will need to enter it here.
- You can now use the SVN+SSH method without having to type your password every time.
Note that as long as Pagaent is open, anyone using your PC will be able to SSH to any service that you are using the same public key on
FreeBSD/Linux
The SVN client
The recommended SVN client for FreeBSD/Linux is Subversion. It is a simple to use CLI tool and is available in both FreeBSD's ports and binary package system and the package manager on your favourite Linux distribution.
All Subversion commands begin with svn
Getting a copy of the website
- Make a directory to store your working copy in:
mkdir caia-website
- Check out the latest revision from the SVN repository. EG, to check out the FUN pages:
svn checkout svn+ssh://username@svn.caia.swin.edu.au/home/svn/infrastructure/caiawww/data/fun/ caia-website/
Editing the website
First, update the working copy: cd caia-website && svn update
Edit the files as needed using your favourite editor.
Once finished, commit your changes:
svn commit -m "Brief comment describing what you changed"
Updating and committing in FreeBSD
Reverting changes
To revert the changes you have made to a file, do:
svn revert
or,
svn revert file1.html file2.html
if you do not wish to revert the entire directory.
To revert files back to an older revision, first revert any changes you have made, as above. Then do:
svn update -r 444
Where 444 is the revision number. To see a log of all changes made and find which revision number you require, do:
svn log | less
Avoid entering your password every time
First, generate a public/private keypair if you have not already:
ssh-keygen -t rsa
Then, copy your public key to the SVN server:
cat ~/.ssh/id_rsa.pub | ssh username@svn.caia.swin.edu.au "mkdir -p ~/.ssh && tee >> .ssh/authorized_keys"
