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.

SCS VPN

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

• Get the latest version of VirtualBox here: https://www.virtualbox.org/wiki/Downloads
• Get the latest version of Vagrant at https://www.vagrantup.com/downloads.html
• Follow the instructions in the Odyssey git repository at odyssey/vagrant/README.md.

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

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:

errlog

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]

Example:

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])."

Examples:

• 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

• Odyssey system documentation (some pages still in progress): https://odyssey.uwaterloo.ca/system/
• Sphinx documentation for Odyssey's Python code: https://odyssey.uwaterloo.ca/system/overview/lang-python/sphinx/

Miscellaneous Notes

Where to find various information:

• Quest terminology: https://uwaterloo.ca/quest/graduate-students/glossary-of-terms
• XIST documentation (Python HTML generator): http://python.livinglogic.de/
• Sphinx documentation: https://www.sphinx-doc.org/en/master/
• For more information on specific tables, you can sometimes take a look at the appropriate .sql file in the odyssey/project/[app_name]/sql/ directory.

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

-- Anna Xing - 2020-11-11

Comments