Skip to content

README.md

Latest commit

 

History

History
120 lines (87 loc) · 5.09 KB

README.md

File metadata and controls

120 lines (87 loc) · 5.09 KB
Raw

Docker Development Environment

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

  1. Build Docker images.

    make build

    Notes:

    • An optional tag may be specified to avoid overriding existing images (e.g., when testing images from a different branch): make build TAG=my-tag.

  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.
    • The MailHog web UI port is derived from the web port (e.g., 8880 → 8025, 8881 → 8026). Access it at http://localhost:MAILHOG_PORT.
    • 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. The default project name is brc-dev; override with PROJECT=lrc-dev for an LRC instance or a second parallel stack.

    make 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.
    • To persist the project name across sessions (required for non-BRC deployments), create a gitignored local.mk in the repo root: echo "PROJECT := lrc-dev" > local.mk.

  7. Run Django scripts to set up the database and perform other tasks.

    make setup

    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.

    make load-db DUMP=YYYY_MM_DD-HH-MM.dump

    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:

      make shell

    • 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()