Skip to content

Commit b71b525

Browse files
committed
refactor(rest_db): allow more local customization
* devs may or may not want to reset their local DB * devs may want to change which DB file is targeted * devs may want to change which fixture file is loaded update docs to reflect these changes
1 parent aeaa3aa commit b71b525

File tree

5 files changed

+107
-52
lines changed

5 files changed

+107
-52
lines changed

.env.sample

+6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
DJANGO_SUPERUSER_USERNAME=benefits-admin
22
DJANGO_SUPERUSER_EMAIL=[email protected]
33
DJANGO_SUPERUSER_PASSWORD=superuser12345!
4+
5+
DJANGO_DB_RESET=true
6+
DJANGO_DB_DIR=.
7+
DJANGO_DB_FILE=django.db
8+
DJANGO_DB_FIXTURES="benefits/core/migrations/local_fixtures.json"
9+
410
testsecret=Hello from the local environment!
511
auth_provider_client_id=benefits-oauth-client-id
612
courtesy_card_verifier_api_auth_key=server-auth-token

benefits/settings.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ def RUNTIME_ENVIRONMENT():
166166
DATABASES = {
167167
"default": {
168168
"ENGINE": "django.db.backends.sqlite3",
169-
"NAME": os.path.join(DATABASE_DIR, "django.db"),
169+
"NAME": os.path.join(DATABASE_DIR, os.environ.get("DJANGO_DB_FILE", "django.db")),
170170
}
171171
}
172172

bin/reset_db.sh

+34-24
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,35 @@
11
#!/usr/bin/env bash
2-
set -eux
3-
4-
# remove database file
5-
6-
# construct the path to the database file from environment or default
7-
DB_DIR="${DJANGO_DB_DIR:-.}"
8-
DB_FILE="${DB_DIR}/django.db"
9-
10-
# -f forces the delete (and avoids an error when the file doesn't exist)
11-
rm -f "${DB_FILE}"
12-
13-
# run database migrations and other initialization
14-
15-
bin/init.sh
16-
17-
# create a superuser account for backend admin access
18-
# set username, email, and password using environment variables
19-
# DJANGO_SUPERUSER_USERNAME, DJANGO_SUPERUSER_EMAIL, and DJANGO_SUPERUSER_PASSWORD
20-
21-
python manage.py createsuperuser --no-input
22-
23-
# load sample data fixtures
24-
25-
python manage.py loaddata benefits/core/migrations/local_fixtures.json
2+
set -ex
3+
4+
# whether to reset database file, defaults to true
5+
DB_RESET="${DJANGO_DB_RESET:-true}"
6+
# optional fixtures to import
7+
FIXTURES="${DJANGO_DB_FIXTURES}"
8+
9+
if [[ $DB_RESET = true ]]; then
10+
# construct the path to the database file from environment or default
11+
DB_DIR="${DJANGO_DB_DIR:-.}"
12+
DB_FILE="${DJANGO_DB_FILE:-django.db}"
13+
DB_PATH="${DB_DIR}/${DB_FILE}"
14+
15+
rm -f "${DB_PATH}"
16+
17+
# run database migrations and other initialization
18+
bin/init.sh
19+
20+
# create a superuser account for backend admin access
21+
# set username, email, and password using environment variables
22+
# DJANGO_SUPERUSER_USERNAME, DJANGO_SUPERUSER_EMAIL, and DJANGO_SUPERUSER_PASSWORD
23+
python manage.py createsuperuser --no-input
24+
else
25+
echo "DB_RESET is false, skipping"
26+
fi
27+
28+
valid_fixtures=$( echo $FIXTURES | grep -e fixtures\.json$ )
29+
30+
if [[ -n "$valid_fixtures" ]]; then
31+
# load data fixtures
32+
python manage.py loaddata "$FIXTURES"
33+
else
34+
echo "No JSON fixtures to load"
35+
fi

docs/configuration/data.md

+18-25
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,24 @@
11
# Configuration data
22

3-
!!! example "Data migration file"
3+
!!! example "Sample data fixtures"
44

5-
[`benefits/core/migrations/0002_data.py`][data-migration]
5+
[`benefits/core/migrations/local_fixtures.json`][sample-fixtures]
66

77
!!! tldr "Django docs"
88

99
[How to provide initial data for models][django-load-initial-data]
1010

1111
## Introduction
1212

13-
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].
13+
The app's model classes are defined in [`benefits/core/models.py`][core-models].
1414

1515
Migrations are run as the application starts up. See the [`bin/init.sh`][init] script.
1616

1717
The sample values provided in the repository are sufficient to run the app locally and interact with e.g. the sample Transit
18-
Agencies.
18+
Agencies. [Django fixtures][django-fixtures] are used to load the database with sample data when running locally.
1919

20-
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.
20+
During the [deployment](../deployment/README.md) process, some environment-specific values are set in environment variables and
21+
read dynamically at runtime. Most configuration values are managed directly in the Django Admin interface at the `/admin` endpoint.
2122

2223
## Sample data
2324

@@ -37,32 +38,24 @@ Some configuration data is not available with the samples in the repository:
3738
- Payment processor configuration for the enrollment phase
3839
- Amplitude configuration for capturing analytics events
3940

40-
### Sample transit agency: `ABC`
41+
## Rebuilding the configuration database locally
4142

42-
- Presents the user a choice between two different eligibility pathways
43-
- One eligibility verifier requires authentication
44-
- One eligibility verifier does not require authentication
43+
A local Django database will be initialized upon first startup of the devcontainer.
4544

46-
### Sample transit agency: `DefTL`
47-
48-
- Single eligibility pathway, no choice presented to the user
49-
- Eligibility verifier does not require authentication
50-
51-
## Building the configuration database
52-
53-
When the data migration changes, the configuration database needs to be rebuilt.
54-
55-
The file is called `django.db` and the following commands will rebuild it.
56-
57-
Run these commands from within the repository root, inside the devcontainer:
45+
To rebuild the local Django database, run the [`bin/reset_db.sh`][reset-db] script from within the repository root,
46+
inside the devcontainer:
5847

5948
```bash
60-
bin/init.sh
49+
bin/reset_db.sh
6150
```
6251

52+
See the [Django Environment Variables](environment-variables.md#django) section for details about how to configure the local
53+
database rebuild.
54+
6355
[core-models]: https://github.com/cal-itp/benefits/blob/dev/benefits/core/models.py
64-
[django-load-initial-data]: https://docs.djangoproject.com/en/4.0/howto/initial-data/
56+
[django-fixtures]: https://docs.djangoproject.com/en/5.0/topics/db/fixtures/
57+
[django-load-initial-data]: https://docs.djangoproject.com/en/5.0/howto/initial-data/
6558
[eligibility-server]: https://docs.calitp.org/eligibility-server
66-
[data-migration]: https://github.com/cal-itp/benefits/tree/dev/benefits/core/migrations/0002_data.py
67-
[helper-migration]: https://github.com/cal-itp/benefits/tree/dev/benefits/core/migrations/0003_data_migration_order.py
6859
[init]: https://github.com/cal-itp/benefits/blob/dev/bin/init.sh
60+
[reset-db]: https://github.com/cal-itp/benefits/blob/dev/bin/reset_db.sh
61+
[sample-fixtures]: https://github.com/cal-itp/benefits/tree/dev/benefits/core/migrations/local_fixtures.json

docs/configuration/environment-variables.md

+48-2
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
The first steps of the Getting Started guide mention [creating an `.env` file][getting-started_create-env].
44

5-
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].
5+
The sections below outline in more detail the application environment variables that you may want to override, and their purpose.
6+
In Azure App Services, this is more generally called the ["configuration"][app-service-config].
67

78
See other topic pages in this section for more specific environment variable configurations.
89

@@ -71,6 +72,39 @@ writable by the Django process._
7172

7273
By default, the base project directory (i.e. the root of the repository).
7374

75+
### `DJANGO_DB_FILE`
76+
77+
!!! info "Local configuration"
78+
79+
This setting only affects the app running on localhost
80+
81+
The name of the Django database file to use locally (during both normal app startup and for resetting the database).
82+
83+
By default, `django.db`.
84+
85+
### `DJANGO_DB_FIXTURES`
86+
87+
!!! info "Local configuration"
88+
89+
This setting only affects the app running on localhost
90+
91+
A path, relative to the repository root, of Django data fixtures to load when resetting the database.
92+
93+
The file must end in `fixtures.json` for the script to process it correctly.
94+
95+
By default, `benefits/core/migrations/local_fixtures.json`.
96+
97+
### `DJANGO_DB_RESET`
98+
99+
!!! info "Local configuration"
100+
101+
This setting only affects the app running on localhost
102+
103+
Boolean:
104+
105+
- `True` (default): deletes the existing database file and runs fresh Django migrations.
106+
- `False`: Django uses the existing database file.
107+
74108
### `DJANGO_DEBUG`
75109

76110
!!! warning "Deployment configuration"
@@ -79,7 +113,7 @@ By default, the base project directory (i.e. the root of the repository).
79113

80114
!!! tldr "Django docs"
81115

82-
[Settings: `DEBUG`](https://docs.djangoproject.com/en/4.0/ref/settings/#debug)
116+
[Settings: `DEBUG`](https://docs.djangoproject.com/en/5.0/ref/settings/#debug)
83117

84118
Boolean:
85119

@@ -128,14 +162,26 @@ Django's primary secret, keep this safe!
128162

129163
### `DJANGO_SUPERUSER_EMAIL`
130164

165+
!!! info "Local configuration"
166+
167+
This setting only affects the app running on localhost
168+
131169
The email address of the Django Admin superuser created when resetting the database.
132170

133171
### `DJANGO_SUPERUSER_PASSWORD`
134172

173+
!!! info "Local configuration"
174+
175+
This setting only affects the app running on localhost
176+
135177
The password of the Django Admin superuser created when resetting the database.
136178

137179
### `DJANGO_SUPERUSER_USERNAME`
138180

181+
!!! info "Local configuration"
182+
183+
This setting only affects the app running on localhost
184+
139185
The username of the Django Admin superuser created when resetting the database.
140186

141187
### `DJANGO_TRUSTED_ORIGINS`

0 commit comments

Comments
 (0)