Installation for Local Development

NOTE: These instructions are for local development only. Refer to the Installation for Deployment page for installation on a remote server.

Requirements

• UMIL requires Docker Engine with Compose V2. Verify your version with docker compose --version and look for an output such as Docker Compose version v2.19.1. If you do not have the correct version, refer to the Docker Compose Migration Documentation.

Initial Set-up Instructions

After cloning this repository, you will need a local .env file at the root of the directory. Copy the contents or rename the .env.sample file to .env and update it to include uncommented environment variables for the database credentials POSTGRES_USER and POSTGRES_PASSWORD, as well as the DJANGO_SECRET_KEY. The database credentials can be set to anything while the DJANGO_SECRET_KEY will need to be obtained from one of the developers working on the UMIL project. Next you will need to verify the values of the DEVELOPMENT and HOST_NAME variables. For local development ONLY, these should be set to "true" and "localhost", respectively.
In one terminal run the following commands to build the docker images and run the specified services.

docker compose build
docker compose up

If you are not running docker containers in detatched mode (e.g docker compose up -d) open a second terminal and go into the running container shell. Run migrations commands to create/populate tables. The following commands should be executed to complete the aforementioned steps.

docker compose exec -it app bash
cd /vim-app
python manage.py makemigrations
python manage.py migrate
python manage.py import_languages
python manage.py import_instruments
python manage.py download_imgs
python manage.py index_data

Note: You might need to create a superuser first by running python manage.py createsuperuser --username ddmal before running python manage.py import_instruments.

Note: download_imgs might take a while depending on your internet connection. In case the download is interrupted, run the command again inside the container shell.

The Django development server should now be available at localhost:8000. Ensure that the database schema is properly set up and the application can display data as expected by navigating to localhost:8000/instruments/.

NOTE: that it is recommended to bring the containers down with docker compose down after you are done developing, testing, and committing your changes. After executing the previous command, the application will no longer be available localhost:8000. To once again view the running application, run docker compose up -d and ensure all migrations made by you or other developers are up-to-date with docker compose exec -it app bash and python manage.py migrate. For further clarifications on managing migrations refer to this Database Migration & Loading Data & Indexing Data to Solr.

Debugging

When installed with DEVELOPMENT=true in the .env file, some additional modules are included in the application container that provide debugging tools: django-extensions and django-debug-toolbar. The debugging toolbar provided by django-debug-toolbar is shown when viewing the development server in the browser. The development installation runs the runserver_plus (provided by django-extensions) command automatically, which provides an in-browser debug console when errors are raised in the application. django-extensions also provides additional tools potentitally useful for development. Further information can be found at module documentation.