{"id":34322380,"url":"https://github.com/carpentries/amy","last_synced_at":"2025-12-17T14:23:22.261Z","repository":{"id":24003405,"uuid":"27387287","full_name":"carpentries/amy","owner":"carpentries","description":"A web-based workshop administration application built using Django.","archived":false,"fork":false,"pushed_at":"2025-12-10T17:28:46.000Z","size":23599,"stargazers_count":116,"open_issues_count":133,"forks_count":75,"subscribers_count":51,"default_branch":"develop","last_synced_at":"2025-12-11T03:28:56.106Z","etag":null,"topics":["carpentries","django","management-system","python","workshops"],"latest_commit_sha":null,"homepage":"https://amy.carpentries.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carpentries.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["carpentries"],"custom":["https://www.zeffy.com/en-US/donation-form/donate-to-make-a-difference-7497"]}},"created_at":"2014-12-01T16:07:14.000Z","updated_at":"2025-12-10T17:28:30.000Z","dependencies_parsed_at":"2023-12-28T15:26:54.024Z","dependency_job_id":"f62bbf71-b507-4d37-9f58-0481c6c9bd18","html_url":"https://github.com/carpentries/amy","commit_stats":null,"previous_names":[],"tags_count":122,"template":false,"template_full_name":null,"purl":"pkg:github/carpentries/amy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Famy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Famy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Famy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Famy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carpentries","download_url":"https://codeload.github.com/carpentries/amy/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carpentries%2Famy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":27783730,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-17T02:00:08.291Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["carpentries","django","management-system","python","workshops"],"created_at":"2025-12-17T14:23:21.151Z","updated_at":"2025-12-17T14:23:22.255Z","avatar_url":"https://github.com/carpentries.png","language":"Python","funding_links":["https://github.com/sponsors/carpentries","https://www.zeffy.com/en-US/donation-form/donate-to-make-a-difference-7497"],"categories":[],"sub_categories":[],"readme":"![](amy/static/amy-logo.png)\n\n[![](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![](https://img.shields.io/badge/django-4.2+-blue.svg)](https://www.djangoproject.com/)\n[![](https://img.shields.io/badge/license-MIT-lightgrey.svg)](LICENSE.md)\n\nAMY is a web-based workshop administration application for [The Carpentries][tc]\nand related projects.  Its target audience is workshop\ncoordinators, most of whom are non-programmers, who need to keep track\nof what workshops are being arranged, when they're supposed to occur,\nwho's teaching what, and so on.\n\nAMY is built using [Django][django] with Python 3, with a bit of Javascript and\nother things thrown in.  If you would like to help, please read:\n\n* the setup instructions below,\n\n* the [contributor guidelines](.github/CONTRIBUTING.md), and\n\n* our [contributor code of conduct](.github/CODE_OF_CONDUCT.md).\n\nPlease [check with us][contact-address] or open an [issue][issues]\nbefore starting work on new features.\n\n## Prerequisites\n\nYou will need the python3 and libpq development header libraries installed\non your system. For an example with Debian-based (Ubuntu, etc) distributions\nof Linux, you can install them with:\n\n```shell\nsudo apt-get update\nsudo apt-get install python3-dev libpq-dev\n```\n\n## Getting Started\n\n1. Clone the repository:\n\n    ~~~\n    git clone https://github.com/carpentries/amy.git\n    cd amy\n    ~~~\n\n1. Configure git to automatically ignore revisions in the `.git-blame-ignore-revs`:\n\n    ~~~\n    git config blame.ignoreRevsFile .git-blame-ignore-revs\n    ~~~\n\n1. Install [Poetry](https://python-poetry.org/docs/#installation).\n\n1. Install Python dependencies:\n\n    ~~~\n    poetry install\n    ~~~\n\n    **Note:**\n    Poetry will create a new virtual environment for this installation, so you don't\n    have to create one yourself.\n\n1. Install [node][nodejs] for front-end packages management.\n\n1. Install CSS, JS dependencies with (`npm` was installed in previous step when you\n    installed `node`):\n\n    ~~~\n    npm install\n    ~~~\n\n1. Create a local instance of Postgres (in a container). This requires Docker to be installed locally.\n\n    ~~~\n    poetry run make database\n    ~~~\n\n1. Note: if the database container already exists, the above command will error out. Use `docker start amy-database` instead to start the database container.\n\n1. Set up your local database with fake (development-ready) data.  This will create a superuser with \"admin\" as both the username and password.\n\n    ~~~\n    poetry run make dev_database\n    ~~~\n\n1. Start a local Django development server by running:\n\n    ~~~\n    poetry run make serve\n    ~~~\n\n    **Note**:  this also installs front-end dependencies for AMY, including [jQuery][jquery] and [Bootstrap][bootstrap] ([full list here](https://github.com/carpentries/amy/blob/develop/package.json)).\n\n1. Open \u003chttp://127.0.0.1:8000/workshops/\u003e in your browser and start clicking. Use the default \"admin\" as username and password.\n\n1. Shut down the local server by typing `Ctrl-C`.  Shut down the database instance with:\n\n    ~~~\n    docker stop amy-database\n    ~~~\n\n## Running tests\n\n1. Set up the project using instructions above. Keep the database container running.\n\n1. Run this command:\n\n    ~~~\n    poetry run make test\n    ~~~\n\n1. To run tests intended for testing migrations:\n\n    ~~~\n    poetry run make test_migrations\n    ~~~\n\n\n## How to build the docker image?\n\n```shell\nLAST_COMMIT=`git rev-parse --short HEAD`\ndocker build -t amy:latest -t amy:$LAST_COMMIT --label commit=$LAST_COMMIT .\n```\n\nFirst command sets `LAST_COMMIT` environment variable to short commit hash of the\nlast commit in the repository.\n\nSecond command builds `Dockerfile` in `.` as a context (should be your repository\ndirectory) with tags `amy:latest` and `amy:$LAST_COMMIT`.\n\n## Upgrading\n\n1. Update the code:\n\n    1. Get the list of changes:\n\n        ~~~\n        git fetch\n        ~~~\n\n    1. Look for the newest tag:\n\n        ~~~~\n        git tag -n\n        ~~~~\n\n    1. Get the code from the newest tag:\n\n        ~~~~\n        git checkout tags/\u003ctag_name\u003e\n        ~~~~\n\n1. Update back-end dependencies:\n\n    ~~~\n    poetry sync\n    ~~~\n\n1. Update front-end dependencies:\n\n    ~~~\n    npm ci\n    ~~~\n\n1. (Optional) make fresh development-ready database:\n\n    ~~~\n    poetry run make dev_database\n    ~~~\n\n1. Run database migrations (note: this is included in the `make dev_database` step above):\n\n    ~~~~\n    poetry run python manage.py migrate\n    ~~~~\n\n1. Enjoy your new version of AMY:\n\n    ~~~\n    poetry run make serve\n    ~~~\n\n\n## Run accessibility tests locally\n\nAccessibility tests are run with [Pa11y](https://pa11y.org) and optionally [Google Lighthouse](https://github.com/GoogleChrome/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](docs/accessibility_testing.md)\n\nFor both Lighthouse and pa11y tests, Google Chrome or Chromium must be installed. On Ubuntu:\n\n```shell\nsudo apt install google-chrome-stable\n```\n\n### Lighthouse\n\nUses [lighthouse-ci](https://github.com/GoogleChrome/lighthouse-ci) with configuration defined in [lighthouserc.js](./lighthouserc.js).\n\nEnsure Chrome is on the path by setting the `CHROME_PATH` environment variable.\n\n```shell\nnpm install -g @lhci/cli@0.12.x puppeteer\nexport CHROME_PATH=/path/to/chrome\nlhci autorun\n```\n\nLighthouse will exit with a failure code if accessibility failures are found. Reports are stored in the `lighthouse-ci-report/` folder.\n\n### Pa11y\n\nUses [pa11y-ci](https://github.com/pa11y/pa11y-ci) with configuration defined in [.pa11yci](./.pa11yci).\n\nChange `executablePath` in .pa11yci to point to your Chrome installation.\n\n```shell\nnpm install -g pa11y-ci pa11y-ci-reporter-html\npa11y-ci\n```\n\nPa11y will exit with a failure code if accessibility failures are found. Reports are stored in the `pa11y-ci-report/` folder.\n\n## Edit the CSS theme\n\nThe AMY theme is primarily based on Bootstrap 4.\n\nTo update the custom CSS that sits on top of the Bootstrap theme, edit `amy/static/css/amy.css`.\n\nTo override Bootstrap 4 defaults such as colors, edit the [Sass](https://sass-lang.com/) file `amy/static/scss/custom_bootstrap.scss` as required, then compile it to CSS:\n\n```shell\nnpx sass amy/static/scss/custom_bootstrap.scss amy/static/css/custom_bootstrap.min.css --style compressed\n```\n\nSee the [Bootstrap documentation](https://getbootstrap.com/docs/4.0/getting-started/theming/) for more guidance on overriding Bootstrap defaults.\n\n[bootstrap]: https://getbootstrap.com/\n[contact-address]: mailto:team@carpentries.org\n[django]: https://www.djangoproject.com\n[jquery]: https://jquery.com/\n[issues]: https://github.com/carpentries/amy/issues\n[tc]: https://carpentries.org/\n[nodejs]: https://nodejs.org/en/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarpentries%2Famy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarpentries%2Famy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarpentries%2Famy/lists"}