diff --git a/.env.sample b/.env.sample index c794243418..fb14ecd8ed 100644 --- a/.env.sample +++ b/.env.sample @@ -1,6 +1,12 @@ DJANGO_SUPERUSER_USERNAME=benefits-admin DJANGO_SUPERUSER_EMAIL=benefits-admin@calitp.org DJANGO_SUPERUSER_PASSWORD=superuser12345! + +DJANGO_DB_RESET=true +DJANGO_DB_DIR=. +DJANGO_DB_FILE=django.db +DJANGO_DB_FIXTURES="benefits/core/migrations/local_fixtures.json" + testsecret=Hello from the local environment! auth_provider_client_id=benefits-oauth-client-id courtesy_card_verifier_api_auth_key=server-auth-token diff --git a/bin/reset_db.sh b/bin/reset_db.sh index b852e55865..bac9bb6f3e 100755 --- a/bin/reset_db.sh +++ b/bin/reset_db.sh @@ -1,25 +1,35 @@ #!/usr/bin/env bash set -eux -# remove database file - -# construct the path to the database file from environment or default -DB_DIR="${DJANGO_DB_DIR:-.}" -DB_FILE="${DB_DIR}/django.db" - -# -f forces the delete (and avoids an error when the file doesn't exist) -rm -f "${DB_FILE}" - -# run database migrations and other initialization - -bin/init.sh - -# create a superuser account for backend admin access -# set username, email, and password using environment variables -# DJANGO_SUPERUSER_USERNAME, DJANGO_SUPERUSER_EMAIL, and DJANGO_SUPERUSER_PASSWORD - -python manage.py createsuperuser --no-input - -# load sample data fixtures - -python manage.py loaddata benefits/core/migrations/local_fixtures.json +# whether to reset database file, defaults to true +DB_RESET="${DJANGO_DB_RESET:-true}" +# optional fixtures to import +FIXTURES="${DJANGO_DB_FIXTURES}" + +if [[ $DB_RESET = true ]]; then + # construct the path to the database file from environment or default + DB_DIR="${DJANGO_DB_DIR:-.}" + DB_FILE="${DJANGO_DB_FILE:-django.db}" + DB_PATH="${DB_DIR}/${DB_FILE}" + + rm -f "${DB_PATH}" + + # run database migrations and other initialization + bin/init.sh + + # create a superuser account for backend admin access + # set username, email, and password using environment variables + # DJANGO_SUPERUSER_USERNAME, DJANGO_SUPERUSER_EMAIL, and DJANGO_SUPERUSER_PASSWORD + python manage.py createsuperuser --no-input +else + echo "DB_RESET is false, skipping" +fi + +valid_fixtures=$( echo $FIXTURES | grep -e fixtures\.json$ ) + +if [[ -n "$valid_fixtures" ]]; then + # load data fixtures + python manage.py loaddata "$FIXTURES" +else + echo "No JSON fixtures to load" +fi diff --git a/docs/configuration/data.md b/docs/configuration/data.md index 6e52de0b8c..bbc5c55cfc 100644 --- a/docs/configuration/data.md +++ b/docs/configuration/data.md @@ -1,8 +1,8 @@ # Configuration data -!!! example "Data migration file" +!!! example "Sample data fixtures" - [`benefits/core/migrations/0002_data.py`][data-migration] + [`benefits/core/migrations/local_fixtures.py`][sample-fixtures] !!! tldr "Django docs" @@ -10,14 +10,15 @@ ## Introduction -Django [data migrations](https://docs.djangoproject.com/en/4.0/topics/migrations/#data-migrations) are used to load the database with instances of the app's model classes, defined in [`benefits/core/models.py`][core-models]. +The app's model classes are defined in [`benefits/core/models.py`][core-models]. Migrations are run as the application starts up. See the [`bin/init.sh`][init] script. The sample values provided in the repository are sufficient to run the app locally and interact with e.g. the sample Transit -Agencies. +Agencies. [Django fixtures][django-fixtures] are used to load the database with sample data when running locally. -During the [deployment](../deployment/README.md) process, environment-specific values are set in environment variables and are read by the data migration file to build that environment's configuration database. See the [data migration file][data-migration] for the environment variable names. +During the [deployment](../deployment/README.md) process, some environment-specific values are set in environment variables and +read dynamically at runtime. Most configuration values are managed directly in the Django Admin interface at the `/admin` endpoint. ## Sample data @@ -37,32 +38,24 @@ Some configuration data is not available with the samples in the repository: - Payment processor configuration for the enrollment phase - Amplitude configuration for capturing analytics events -### Sample transit agency: `ABC` +## Rebuilding the configuration database locally -- Presents the user a choice between two different eligibility pathways -- One eligibility verifier requires authentication -- One eligibility verifier does not require authentication +A local Django database will be initialized upon first startup of the devcontainer. -### Sample transit agency: `DefTL` - -- Single eligibility pathway, no choice presented to the user -- Eligibility verifier does not require authentication - -## Building the configuration database - -When the data migration changes, the configuration database needs to be rebuilt. - -The file is called `django.db` and the following commands will rebuild it. - -Run these commands from within the repository root, inside the devcontainer: +To rebuild the local Django database, run the [`bin/reset_db.sh`][reset-db] script from within the repository root, +inside the devcontainer: ```bash -bin/init.sh +bin/reset_db.sh ``` +See the [Django Environment Variables](environment-variables.md#django) section for details about how to configure the local +database rebuild. + [core-models]: https://github.com/cal-itp/benefits/blob/dev/benefits/core/models.py -[django-load-initial-data]: https://docs.djangoproject.com/en/4.0/howto/initial-data/ +[django-fixtures]: https://docs.djangoproject.com/en/5.0/topics/db/fixtures/ +[django-load-initial-data]: https://docs.djangoproject.com/en/5.0/howto/initial-data/ [eligibility-server]: https://docs.calitp.org/eligibility-server -[data-migration]: https://github.com/cal-itp/benefits/tree/dev/benefits/core/migrations/0002_data.py -[helper-migration]: https://github.com/cal-itp/benefits/tree/dev/benefits/core/migrations/0003_data_migration_order.py [init]: https://github.com/cal-itp/benefits/blob/dev/bin/init.sh +[reset-db]: https://github.com/cal-itp/benefits/blob/dev/bin/reset_db.sh +[sample-fixtures]: https://github.com/cal-itp/benefits/tree/dev/benefits/core/migrations/local_fixtures.json diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 305131cf3e..455a637b1a 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -2,7 +2,8 @@ The first steps of the Getting Started guide mention [creating an `.env` file][getting-started_create-env]. -The sections below outline in more detail the application environment variables that you may want to override, and their purpose. In App Service, this is more generally called the ["configuration"][app-service-config]. +The sections below outline in more detail the application environment variables that you may want to override, and their purpose. +In Azure App Services, this is more generally called the ["configuration"][app-service-config]. See other topic pages in this section for more specific environment variable configurations. @@ -71,6 +72,39 @@ writable by the Django process._ By default, the base project directory (i.e. the root of the repository). +### `DJANGO_DB_FILE` + +!!! info "Local configuration" + + This setting only affects the app running on localhost + +The name of the Django database file to use locally (during both normal app startup and for resetting the database). + +By default, `django.db`. + +### `DJANGO_DB_FIXTURES` + +!!! info "Local configuration" + + This setting only affects the app running on localhost + +A path, relative to the repository root, of Django data fixtures to load when resetting the database. + +The file must end in `fixtures.json` for the script to process it correctly. + +By default, `benefits/core/migrations/local_fixtures.json`. + +### `DJANGO_DB_RESET` + +!!! info "Local configuration" + + This setting only affects the app running on localhost + +Boolean: + +- `True` (default): deletes the existing database file and runs fresh Django migrations. +- `False`: Django uses the existing database file. + ### `DJANGO_DEBUG` !!! warning "Deployment configuration" @@ -79,7 +113,7 @@ By default, the base project directory (i.e. the root of the repository). !!! tldr "Django docs" - [Settings: `DEBUG`](https://docs.djangoproject.com/en/4.0/ref/settings/#debug) + [Settings: `DEBUG`](https://docs.djangoproject.com/en/5.0/ref/settings/#debug) Boolean: @@ -128,14 +162,26 @@ Django's primary secret, keep this safe! ### `DJANGO_SUPERUSER_EMAIL` +!!! info "Local configuration" + + This setting only affects the app running on localhost + The email address of the Django Admin superuser created when resetting the database. ### `DJANGO_SUPERUSER_PASSWORD` +!!! info "Local configuration" + + This setting only affects the app running on localhost + The password of the Django Admin superuser created when resetting the database. ### `DJANGO_SUPERUSER_USERNAME` +!!! info "Local configuration" + + This setting only affects the app running on localhost + The username of the Django Admin superuser created when resetting the database. ### `DJANGO_TRUSTED_ORIGINS`