[GrandComicsDatabase/gcd-django] Add core development environment (PR #745)
Adam Hernandez
Summary
- add the one-clone Docker Compose development stack and
./bin/devlauncher - document supported Docker and Docker-free Python 3.13/MySQL 8 setup paths
- add contract coverage and a Compose smoke job to the development-environment workflow
Validation
./bin/dev up,./bin/dev doctor, and localhost HTTP smoke check./bin/dev test apps/gcd/tests/test_dev_environment_core.py./bin/dev test apps/gcd/tests/test_publisher.py -q(43 passed)bash -n bin/dev,docker compose config --quiet, andgit diff --check
The native launcher is implemented and documented. A complete native macOS dependency install was not run on this machine because its Homebrew ICU/pkg-config prerequisites are not installed; the exact prerequisites are included in the guide.
You can view, comment on, or merge this pull request online at:
https://github.com/GrandComicsDatabase/gcd-django/pull/745
Commit Summary
- b49ee85 Add core development environment
File Changes
(10 files)
- A .dockerignore (9)
- A .env.example (13)
- M .github/workflows/dev-environment-ci.yml (23)
- M .gitignore (3)
- A Dockerfile.dev (22)
- M README.md (3)
- A apps/gcd/tests/test_dev_environment_core.py (91)
- A bin/dev (215)
- A compose.yaml (65)
- A docs/development/CORE_SETUP.md (82)
Patch Links:
- https://github.com/GrandComicsDatabase/gcd-django/pull/745.patch
- https://github.com/GrandComicsDatabase/gcd-django/pull/745.diff
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
gemini-code-assist[bot]
@gemini-code-assist[bot] commented on this pull request.
Code Review
This pull request introduces a unified core development environment supporting both Docker and native (Docker-free) workflows. It adds a development launcher script (bin/dev), a Docker Compose configuration (compose.yaml), a development Dockerfile (Dockerfile.dev), comprehensive contract tests, and updated setup documentation. Feedback on these changes suggests improving the robustness of the environment by handling CRLF line endings in .env parsing for Windows compatibility, adding MYSQL_HOST and MYSQL_PORT to the allowed environment variables list, quoting the database password in the healthcheck to handle special characters, and simplifying the quote escaping in the web service healthcheck command.
In bin/dev:
> + while IFS= read -r line || [[ -n "$line" ]]; do + [[ -z "$line" || "$line" == \#* ]] && continue
When developers on Windows clone the repository, files may end up with CRLF line endings. If .env has CRLF line endings, the read loop will preserve the trailing carriage return (\r) in the value of the environment variable, leading to broken ports or credentials (e.g., 8000\r).
To prevent this, strip trailing carriage returns from each line before parsing.
while IFS= read -r line || [[ -n "$line" ]]; do
line="${line%$'\r'}"
[[ -z "$line" || "$line" == \#* ]] && continue
In bin/dev:
> +ALLOWED_ENVIRONMENT_VARIABLES=( + COMPOSE_PROJECT_NAME GCD_WEB_PORT GCD_MYSQL_PORT MYSQL_DATABASE MYSQL_USER + MYSQL_PASSWORD MYSQL_ROOT_PASSWORD +)
The native_environment function supports and uses the MYSQL_HOST and MYSQL_PORT environment variables, but they are currently omitted from ALLOWED_ENVIRONMENT_VARIABLES. This prevents native developers from specifying a custom database host or port in their .env file, forcing them to prefix every command in the shell.
Adding MYSQL_HOST and MYSQL_PORT to ALLOWED_ENVIRONMENT_VARIABLES allows them to be loaded from .env seamlessly.
ALLOWED_ENVIRONMENT_VARIABLES=(
COMPOSE_PROJECT_NAME GCD_WEB_PORT GCD_MYSQL_PORT MYSQL_DATABASE MYSQL_USER
MYSQL_PASSWORD MYSQL_ROOT_PASSWORD MYSQL_HOST MYSQL_PORT
)
In compose.yaml:
> +name: gcd-django-dev
+
+services:
+ db:
+ image: mysql:8.0
+ environment:
+ MYSQL_DATABASE: ${MYSQL_DATABASE:-gcd_dev}
+ MYSQL_USER: ${MYSQL_USER:-gcd_dev}
+ MYSQL_PASSWORD: ${MYSQL_PASSWORD:-gcd_dev_password}
+ MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-gcd_dev_root}
+ ports:
+ - "127.0.0.1:${GCD_MYSQL_PORT:-3308}:3306"
+ volumes:
+ - mysql_data:/var/lib/mysql
+ healthcheck:
+ test: ["CMD-SHELL", "mysqladmin ping -h localhost -u$$MYSQL_USER -p$$MYSQL_PASSWORD"]
If MYSQL_PASSWORD contains spaces or special characters, passing it unquoted to mysqladmin can lead to word splitting or unexpected shell behavior during the healthcheck.
Quoting the variable as '$$MYSQL_PASSWORD' ensures it is treated as a single argument.
test: ["CMD-SHELL", "mysqladmin ping -h localhost -u'$$MYSQL_USER' -p'$$MYSQL_PASSWORD'"]
In compose.yaml:
> + build:
+ context: .
+ dockerfile: Dockerfile.dev
+ user: "${DEV_UID:-1000}:${DEV_GID:-1000}"
+ working_dir: /workspace
+ volumes:
+ - ./:/workspace
+ environment: *django_environment
+ depends_on:
+ migrate:
+ condition: service_completed_successfully
+ command: python manage.py runserver 0.0.0.0:8000
+ ports:
+ - "127.0.0.1:${GCD_WEB_PORT:-8000}:8000"
+ healthcheck:
+ test: ["CMD-SHELL", 'python -c "from urllib.request import urlopen; urlopen(\"http://127.0.0.1:8000/\", timeout=3)"']
The current healthcheck command uses escaped double quotes \" inside a single-quoted YAML string, which can be hard to read and prone to parsing issues.
Using single quotes for the Python string literal and double quotes for the outer YAML string makes the command much cleaner and easier to maintain.
test: ["CMD-SHELL", "python -c \"from urllib.request import urlopen; urlopen('http://127.0.0.1:8000/', timeout=3)\""]
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
Adam Hernandez
@DeusExTaco pushed 1 commit.
- bfa1cc7 Clarify macOS native build prerequisites
—
View it on GitHub or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
Adam Hernandez
@DeusExTaco pushed 1 commit.
- 61364d5 Harden development environment configuration
—
View it on GitHub or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
Adam Hernandez
@DeusExTaco commented on this pull request.
In bin/dev:
> +ALLOWED_ENVIRONMENT_VARIABLES=( + COMPOSE_PROJECT_NAME GCD_WEB_PORT GCD_MYSQL_PORT MYSQL_DATABASE MYSQL_USER + MYSQL_PASSWORD MYSQL_ROOT_PASSWORD +)
Fixed in 61364d5. I added MYSQL_HOST and MYSQL_PORT to the .env allowlist and included the native defaults in .env.example.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
Adam Hernandez
> + while IFS= read -r line || [[ -n "$line" ]]; do + [[ -z "$line" || "$line" == \#* ]] && continue
Fixed in 61364d5. I strip a trailing carriage return from each .env line before parsing it, and added regression coverage.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
Adam Hernandez
@DeusExTaco commented on this pull request.
In compose.yaml:
> +name: gcd-django-dev
+
+services:
+ db:
+ image: mysql:8.0
+ environment:
+ MYSQL_DATABASE: ${MYSQL_DATABASE:-gcd_dev}
+ MYSQL_USER: ${MYSQL_USER:-gcd_dev}
+ MYSQL_PASSWORD: ${MYSQL_PASSWORD:-gcd_dev_password}
+ MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-gcd_dev_root}
+ ports:
+ - "127.0.0.1:${GCD_MYSQL_PORT:-3308}:3306"
+ volumes:
+ - mysql_data:/var/lib/mysql
+ healthcheck:
+ test: ["CMD-SHELL", "mysqladmin ping -h localhost -u$$MYSQL_USER -p$$MYSQL_PASSWORD"]
Fixed in 61364d5. I now quote the MySQL user and password in the health check, and verified it with the live Compose stack.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
Adam Hernandez
> + build:
+ context: .
+ dockerfile: Dockerfile.dev
+ user: "${DEV_UID:-1000}:${DEV_GID:-1000}"
+ working_dir: /workspace
+ volumes:
+ - ./:/workspace
+ environment: *django_environment
+ depends_on:
+ migrate:
+ condition: service_completed_successfully
+ command: python manage.py runserver 0.0.0.0:8000
+ ports:
+ - "127.0.0.1:${GCD_WEB_PORT:-8000}:8000"
+ healthcheck:
+ test: ["CMD-SHELL", 'python -c "from urllib.request import urlopen; urlopen(\"http://127.0.0.1:8000/\", timeout=3)"']
Fixed in 61364d5. I simplified the web health-check quoting and added coverage for the rendered command.
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.
JochenGCD
—
Reply to this email directly, view it on GitHub, or unsubscribe.
Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS and Android. Download it today!
You are receiving this because you are subscribed to this thread.