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:

• the setup instructions below,

• the contributor guidelines, and

• our contributor code of conduct.

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

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 Pipenv:

   $ python -m pip install --user pipenv
   

4. Install Python dependencies:

   $ pipenv sync --dev
   

   Note: Pipenv will create a new virtual environment for this installation, so you don't have to create one yourself. The --dev flag installs development dependencies, required e.g. for testing.

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. Start running a local instance of Postgres and Redis. This requires Docker to be installed locally. Redis is required to have certain features (like creating a new person and viewing a workshop request) work correctly.

   $ docker compose -f docker/docker-compose.yml -p amy up -d database redis
   

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

   $ pipenv run make dev_database
   

9. Start a local Django development server by running:

   $ pipenv run make serve
   

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

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

11. Shut down the local server by typing Ctrl-C. Shut down the Docker Redis instance with:

    $ docker compose -f docker/docker-compose.yml -p amy down
    

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} -f docker/Dockerfile .

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

Second command builds docker/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 dependencies front-end and back-end dependencies:

   $ pipenv run make upgrade
   

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

   $ pipenv run make dev_database
   

   Note: this command requires removing (by hand) the old database file.

4. Run database migrations:

   $ pipenv run python manage.py migrate
   

5. Enjoy your new version of AMY:

   $ pipenv run make serve
   

Start hacking on email automation

1. Make sure you have Redis running. See instructions above.

2. Create dev database (it will add a super user and predefined database entries, too!):

   $ pipenv run make dev_database

3. Run the server:

   $ pipenv run python manage.py runserver

4. Run the RQ worker and scheduler (use separate terminals or processes for each command):

   $ pipenv run python manage.py rqworker
   $ pipenv run python manage.py rqscheduler