Skip to content

Development

Jump to bottom
Cameron Hyde edited this page Sep 29, 2024 · 13 revisions

Galaxy Media Site (GMS) is built with the Django framework and uses a lot of conventional Django logic to get things done. Aside from that, there are a lot of HTML templates and CSS for building the frontend - and a sprinkling of Javascript just to make things work.

If you're looking to do some work on the frontend, you can probably dive straight in if you are familiar with HTML and CSS. A lot of the styling is Bootstrap 5 so check that out if you aren't familiar.

For any serious work on the backend, an understanding of the Django framework is essential. If you are literate in Python, you can pick up the basics in a week with this highly-recommended course on YouTube. If you are not familiar with Python, give yourself an additional week and start here.

If you're looking to create a new Lab/Subsite, there are docs just for that

By design, the codebase leans heavily on conventional Django mechanisms. This means that as long as you understand how Django works, you should understand how this application works. If you are not familiar with Django and want to know how a robust web application can be built, it is a great framework to learn and is used for several satellite projects in the Galaxy Community.

Contributing

  • Please format all Python code to PEP8
  • Fork, branch dev and make a pull request to dev
  • The dev branch is merged to main when tested on the dev site
  • Github workflows run test and deploy dev and main branches on commit/PR
  • dev -> dev-site.gvl.org.au
  • main -> site.usegalaxy.org.au
  • If appropriate, add a unit test to <appname>/tests.py

GitPod Preview

If you don't want to go through local development setup, you can try using the GitPod preview.

  • Create a pull-request against the dev branch with your work.
  • After a few moments you should see a "GitHub preview" link in a bot comment.
  • The link will take you to GitPod - you will need to sign up for a GitPod account.
  • When you open the workspace, GitPod will begin automatically setting up. You will see code being run in the terminal.
  • Have a cup of tea while the workspace builds itself. After a minute should see a popup in the bottom right corner with three buttons.
  • Click the "Open browser" button to open the running application in a new tab.
  • Alternatively, you can "Make Public" if you want the website URL to work for anyone (e.g. you want to share it with the team, or in the PR).

Making further changes

After seeing your work live in GitPod, chances are that you want to fix some things.

  • You can make further changes in the GitPod environment, just refresh the website tab to see the changes.
  • When you are happy with some changes, make sure to commit and push the changes. This can be done in the GitPod Editor's Git tab (left bar, third icon down) very easily.

Developer setup

Clone and install

You should first create and activate a virtual environment using Conda or virtualenv (instructions are OS-specific).

git clone https://github.com/usegalaxy-au/galaxy-media-site.git

# This is the project root, place your venv here if using virtualenv
cd galaxy-media-site

# Setup virtualenv with the name `venv` in the project root.
# Install python3.12
python3.12 -m venv venv

# (optional) Deactivate conda here (if active) as we're using virtualenv.
conda deactivate

# Add the following environment variable to the end of the activate script.
# This tells Django to run in dev mode.
echo "export DJANGO_SETTINGS_MODULE=webapp.settings.dev" >> venv/bin/activate

# Activate the virtual environment
. venv/bin/activate

# Install python dependencies
pip install -r requirements.txt

Database

When running in dev mode, GMS will use the sqlite3 backend so you don't have to do anything else here. A db.sqlite3 file should be created when you first run the application. If you get errors when running the app, make sure that the settings module is set to webapp.setting.dev.

Environment

Finally, the application needs a .env file for some credentials. Copy .env.sample to .env and modify to set credentials for your environment:

# For local dev you can just leave this as it is
DJANGO_SECRET_KEY="secret"

# Match the Django dev server:
HOSTNAME=127.0.0.1:8000

# Match the DB you just created:
DB_NAME=gms
DB_USER=gms
DB_PASSWORD="secret"

# Delete these unless you have a need to set them:
RECAPTCHA_SITE_KEY=
RECAPTCHA_SECRET_KEY=

# For error alerts
SLACK_API_KEY=xoxb-XXXXX
SLACK_CHANNEL_ID=XXXXXXXXX
SLACK_MENTION_USER_ID=UXXXXXXXXX

# For tool update notifications (comma separated list):
SLACK_API_URLS=https://hooks.slack.com/services/<XXXXX>/<XXXXX>/<XXXXX>

# I suggest setting these to point to a Mailtrap.io instance if you want to test mail:
MAIL_SMTP_PORT=25
MAIL_HOSTNAME=mail.mysite.com
MAIL_SMTP_USERNAME=admin
MAIL_SMTP_PASSWORD=secret

# Probably leave these
[email protected]
[email protected]
MAIL_USE_TLS=true

For testing mail in dev, a Mailtrap.io account is very useful and takes 5 minutes to set up.

Migrate and run

# Migrate the blank database with the GMS schema
python manage.py migrate

# Run a development server and check it out in a browser
python manage.py runserver

At this point the application should run, but the database will be empty. We would like to create a seeder to populate the DB at some point but the site should be functional without any data. You can create content using the admin panel once you have created and logged in with a superuser account.

Application overview

Django project root: galaxy-media-site/webapp

Like most modern Django projects, the backend has been split into "apps" to separate the logic and make it easier to navigate. App folders can be found in the project root:

  • home - landing pages, notices, about, request forms, arbitrary pages (/page.html)
  • events - list and display events
  • news - list and display news items, news feed web scrapers (e.g. BioCommons)
  • people - the Galaxy team

There is also a utils mofule for general utilities that don't belong to any particular app and are reused throughout the project.

Read more on the Backend page

Pulling changes on the host

If your GMS server has been configured with the Ansible playbook included in the repo, it should have installed an update.sh script in the home directory. This makes upgrading the site easy after updates have been pushed to main:

ssh <my-gms-server>
./update.sh

This script takes care of the following tasks:

  • source venv/bin/activate (activate virtual env)
  • git pull
  • python manage.py migrate
  • python manage.py collectstatic
  • ensure ownership of webapp/logs + webapp/media by www-data user
  • restart systemd service

Running tests

All tests are written with Django.TestCase - see tests.py file in app folders. Writing tests is simple, following unittest convention. Refer to the Django docs.

Running tests is easy:

python manage.py test
Clone this wiki locally