Odyssey Web Development Co-op Guide

These notes provide an introductory guide for Web Developer co-op students working on the Odyssey application. They are currently a work in progress, and will be up-to-date as of the Fall 2020 term.

More information can be found on the NewProgrammerGuide page.


Connecting to the SCS VPN allows you to SSH into the testing server and view its deployments in the browser.

  • Setup instructions can be found here: https://vpn.cs.uwaterloo.ca/
  • If your SSH connection request or browser connection to odyssey-test.uwaterloo.ca is timing out, check that you're connected to the VPN.

Vagrant and VirtualBox

TODO: Add more detail + possibly update readme in repository

Note for Linux users:

  • If an error message concerning AMD-V being disabled in the BIOS is appearing after running "vagrant up" in the command line, verify that virtualization is enabled in the BIOS.

The Testing Server

The odyssey-test server mirrors the actual production server, so any page that you can find on odyssey.uwaterloo.ca should be found at the same URL hierarchy on odyssey-test.uwaterloo.ca/username/ (username allows you to impersonate any user).

To SSH into the testing server:

ssh odyssey@odyssey-test.uwaterloo.ca

The Odyssey git repository is located at ~/git/odyssey.


Deployment scripts are stored in the odyssey/project/deploy/bin/ directory.

The following commands (among others) allow you to deploy your changes to the testing server (you can run them from anywhere within odyssey-test):

  • deploy-static Deploy changes in static (HTML/CSS/JS) files.
  • deploy-python Deploy changes in Python files.
  • deploy-python-test Run Python unit tests and build Sphinx documentation.

If the WCMS templates aren't loading properly after you deploy (something looks wrong with the CSS/JS, or you're getting a blank webpage), use this command:

  • wcms-download Re-download and process WCMS templates.

Server Logs

Server logs are stored in the /var/log/httpd24 directory.

In particular, if you encounter a 500 Internal Server Error after deploying, examine the error log in the /var/log/httpd24/ssl_error_log file. You can run the following aliased command to view the latest error log contents while the test server is active:


As usual, you can view the full command and set up your own aliases in the ~/.bashrc file.

Accessing the Database

To connect to the Odyssey database from within odyssey-test as a specific role:

psql -U [role_name]

Relevant roles:

  • _quest_ui Quest-related data.
  • _instruct_ui Instruct-related data.

Using Git

The Odyssey repository is located here, with branch naming conventions and a link to system documentation in README.md: https://git.uwaterloo.ca/cscf/odyssey

You can use git worktree to work on branches. To create a new git worktree, run the following command from the directory to which you want to link the worktree (usually odyssey, the prod branch):

git worktree add -b RT[actual RT number]-branch-description ../RT[actual RT number]


git worktree add -b RT1073654-create-degree-pages ../RT1073654

See here for more information on worktrees: https://git-scm.com/docs/git-worktree

Git Hooks

To configure the git hooks path (so that the repository uses the hooks from the "hooks" tracked directory instead of .git/hooks):

git config core.hooksPath hooks

We have a hook to link git commits to their respective RT tickets, which helps track our work. To use this hook, always format your commit messages as follows:

git commit -m "[Relevant Odyssey section]: [Description of change] (RT#[actual RT number])."


  • git commit -m "Instruct: Authorized new access role _instruct_reg_select (RT#1071198, RT#1065590)"
  • git commit -m "Quest: Added plans, programs, and subjects to search feature on main page (RT#1074097)"

Other Useful Git Commands

  • git commit --fixup=[SHA of the commit to fix] Fixup a commit, i.e. commit a small fix of a previous commit.
  • git log View past commits and SHAs.

Official Documentation

Miscellaneous Notes

Where to find various information:

Some of the notes above were adapted from previous notes here.

-- Anna Xing - 2020-11-11


Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r4 - 2021-01-04 - DanielAllen
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback