Skip to content

README.md

Latest commit

 

History

History
123 lines (90 loc) · 5.43 KB

README.md

File metadata and controls

123 lines (90 loc) · 5.43 KB

Docker Development Environment

Note that these steps must be run from the root directory of the repo.

  1. Build Docker images.

    sh bootstrap/development/docker/scripts/build_images.sh

    Notes:

    • An optional argument may be specified to build the images with a specific tag. This may be useful for testing updated images (e.g., from different branches) without overriding existing images.

  2. Retrieve a cilogon.yml file containing CILogon credentials that will be provided for you. Place it in the Docker configuration directory.

    mv /path/to/cilogon.yml bootstrap/development/docker/config

  3. Generate secrets, such as passwords for PostgreSQL and Redis.

    sh bootstrap/development/docker/scripts/docker_generate_secrets.sh

    Notes:

    • This step should only be performed once. Running it again will overwrite existing passwords that may already have been used to configure services.

  4. Generate a .env file using values defined in the Docker configuration directory. You must provide a deployment name ("BRC" or "LRC"), as well as a port where the web service will be available ("8880", "8881", "8882", or "8883").

    export DEPLOYMENT=BRC
export WEB_PORT=8880
sh bootstrap/development/docker/scripts/docker_generate_django_env.sh $DEPLOYMENT $WEB_PORT

    Notes:

    • This step may be performed multiple times.
    • The main.yml file does not need to be modified in any way, despite indications within it. Its pre-defined values will be overridden and added to based on the other YML files in the directory.
    • The port must be one of the above because the CILogon application client is only configured for one of those four ports.
    • The port may be customized so that multiple instances may run at the same time, without port clashes.
    • Settings may be added or overridden by specifying them in an overrides.yml file in the directory.
      • The following features may require additional configuration. Refer to the documentation for more information.
        • Allowance renewal surveys
        • MOU generation and storage on BRC deployments
        • Vector-related requests on BRC deployments
    • The generated .env file will be created in coldfront/config/ and is used by the Django application directly.

  5. Generate a .env file with environment variables that will be passed to docker-compose.yml. You must provide the same deployment name and web port as in the previous step.

    sh bootstrap/development/docker/scripts/create_docker_compose_env_file.sh $DEPLOYMENT $WEB_PORT

    Notes:

    • docker-compose.yml looks for a .env file in the same directory it resides in. This script creates .env there.
    • There is an optional third argument that configures whether the application expects env_settings.py or a legacy pre-generated Python settings file. By default, env_settings.py is used, but this can be overridden by providing false as a third argument. (Eventually, this will be removed.)

  6. Start the application stack. Specify a unique Docker project name so that resources are placed within a Docker namespace. Examples: "brc-dev", "lrc-dev".

    export DOCKER_PROJECT_NAME=brc-dev
docker compose \
    -f bootstrap/development/docker/docker-compose.yml \
    -p $DOCKER_PROJECT_NAME \
    up

    Notes:

    • Some services (e.g., web) are expected to be failing at this point.
    • If the IMAGE_TAG environment variable is set, Docker Compose will use images with the specified tag.

  7. Run Django scripts to set up the database and perform other tasks. You must provide the name of your Docker project.

    sh bootstrap/development/docker/scripts/docker_run_django_scripts.sh $DOCKER_PROJECT_NAME

    Notes:

    • This step may be run multiple times.

  8. Retrieve a PostgreSQL database dump file that will be provided for you. Place it in the root directory of the repo. Load it into your instance. You must provide the name of your Docker project.

    export RELATIVE_CONTAINER_DUMP_FILE_PATH=YYYY_MM_DD-HH-MM.dump
sh bootstrap/development/docker/scripts/docker_load_database_backup.sh $DOCKER_PROJECT_NAME $RELATIVE_CONTAINER_DUMP_FILE_PATH

    Notes:

    • This may take several minutes.
    • The following error may appear in the output, but is not an issue: 
      ERROR:  role "postgres" already exists

  9. At this point, the web service should be functioning. Navigate to it from the browser at "http://localhost:WEB_PORT", where WEB_PORT is the one defined above.

  10. After authenticating for the first time, grant your user administrator privileges in Django:

    • Enter into the application shell container:

      docker compose -p $DOCKER_PROJECT_NAME exec app-shell bash

    • From within the container, start a Django shell:

      python3 manage.py shell

    • From within the Django shell, update your user:

      from django.contrib.auth.models import User

# The username is the string that appears on the right-hand side of the
# menu. It will be an email address if you do not have a cluster account.
user = User.objects.get(username="your_username")
user.is_staff = True
user.is_superuser = True
user.save()