Skip to content

Latest commit

 

History

History
242 lines (158 loc) · 6.71 KB

README.md

File metadata and controls

242 lines (158 loc) · 6.71 KB

AMY is a web-based workshop administration application for The Carpentries and related projects. Its target audience is workshop coordinators, most of whom are non-programmers, who need to keep track of what workshops are being arranged, when they're supposed to occur, who's teaching what, and so on.

AMY is built using Django with Python 3, with a bit of Javascript and other things thrown in. If you would like to help, please read:

Please check with us or open an issue before starting work on new features.

Prerequisites

You will need the python3 and libpq development header libraries installed on your system. For an example with Debian-based (Ubuntu, etc) distributions of Linux, you can install them with:

sudo apt-get update
sudo apt-get install python3-dev libpq-dev

Getting Started

  1. Clone the repository:

    git clone https://github.com/carpentries/amy.git
cd amy

  2. Configure git to automatically ignore revisions in the .git-blame-ignore-revs:

    git config blame.ignoreRevsFile .git-blame-ignore-revs

  3. Install Poetry.

  4. Install Python dependencies:

    poetry install

    Note: Poetry will create a new virtual environment for this installation, so you don't have to create one yourself.

  5. Install node for front-end packages management.

  6. Install CSS, JS dependencies with (npm was installed in previous step when you installed node):

    npm install

  7. Create a local instance of Postgres (in a container). This requires Docker to be installed locally.

    poetry run make database

  8. Note: if the database container already exists, the above command will error out. Use docker start amy-database instead to start the database container.

  9. Set up your local database with fake (development-ready) data. This will create a superuser with "admin" as both the username and password.

    poetry run make dev_database

  10. Start a local Django development server by running:

    poetry run make serve

    Note: this also installs front-end dependencies for AMY, including jQuery and Bootstrap (full list here).

  11. Open http://127.0.0.1:8000/workshops/ in your browser and start clicking. Use the default "admin" as username and password.

  12. Shut down the local server by typing Ctrl-C. Shut down the database instance with:

    docker stop amy-database

Running tests

  1. Set up the project using instructions above. Keep the database container running.

  2. Run this command:

    poetry run make test

  3. To run tests intended for testing migrations:

    poetry run make test_migrations

How to build the docker image?

LAST_COMMIT=`git rev-parse --short HEAD`
docker build -t amy:latest -t amy:$LAST_COMMIT --label commit=$LAST_COMMIT .

First command sets LAST_COMMIT environment variable to short commit hash of the last commit in the repository.

Second command builds Dockerfile in . as a context (should be your repository directory) with tags amy:latest and amy:$LAST_COMMIT.

Upgrading

  1. Update the code:

    1. Get the list of changes:

      git fetch

    2. Look for the newest tag:

      git tag -n

    3. Get the code from the newest tag:

      git checkout tags/<tag_name>

  2. Update back-end dependencies:

    poetry sync

  3. Update front-end dependencies:

    npm ci

  4. (Optional) make fresh development-ready database:

    poetry run make dev_database

  5. Run database migrations (note: this is included in the make dev_database step above):

    poetry run python manage.py migrate

  6. Enjoy your new version of AMY:

    poetry run make serve

Run accessibility tests locally

Accessibility tests are run with Pa11y and optionally Google Lighthouse as part of the CI process. It's sometimes helpful to run these programs locally to debug or test changes. For more information on the tests, see the accessibility tests documentation

For both Lighthouse and pa11y tests, Google Chrome or Chromium must be installed. On Ubuntu:

sudo apt install google-chrome-stable

Lighthouse

Uses lighthouse-ci with configuration defined in lighthouserc.js.

Ensure Chrome is on the path by setting the CHROME_PATH environment variable.

npm install -g @lhci/[email protected] puppeteer
export CHROME_PATH=/path/to/chrome
lhci autorun

Lighthouse will exit with a failure code if accessibility failures are found. Reports are stored in the lighthouse-ci-report/ folder.

Pa11y

Uses pa11y-ci with configuration defined in .pa11yci.

Change executablePath in .pa11yci to point to your Chrome installation.

npm install -g pa11y-ci pa11y-ci-reporter-html
pa11y-ci

Pa11y will exit with a failure code if accessibility failures are found. Reports are stored in the pa11y-ci-report/ folder.

Edit the CSS theme

The AMY theme is primarily based on Bootstrap 4.

To update the custom CSS that sits on top of the Bootstrap theme, edit amy/static/css/amy.css.

To override Bootstrap 4 defaults such as colors, edit the Sass file amy/static/scss/custom_bootstrap.scss as required, then compile it to CSS:

npx sass amy/static/scss/custom_bootstrap.scss amy/static/css/custom_bootstrap.min.css --style compressed

See the Bootstrap documentation for more guidance on overriding Bootstrap defaults.