diff --git a/docs/2-local-development/developing-locally-docker.rst b/docs/2-local-development/developing-locally-docker.rst index 05e188e5..07969e5b 100644 --- a/docs/2-local-development/developing-locally-docker.rst +++ b/docs/2-local-development/developing-locally-docker.rst @@ -242,6 +242,41 @@ The stack comes with a dedicated node service to build the static assets, watch .. _Sass: https://sass-lang.com/ .. _live reloading: https://browsersync.io + +Using Just for Docker Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +We have included a ``justfile`` to simplify the use of frequent Docker commands for local development. + +.. warning:: + Currently, "Just" does not reliably handle signals or forward them to its subprocesses. As a result, + pressing CTRL+C (or sending other signals like SIGTERM, SIGINT, or SIGHUP) may only interrupt + "Just" itself rather than its subprocesses. + For more information, see `this GitHub issue `_. + +First, install Just using one of the methods described in the `official documentation `_. + +Here are the available commands: + +- ``just build`` + Builds the Python image using the local Docker Compose file. + +- ``just up`` + Starts the containers in detached mode and removes orphaned containers. + +- ``just down`` + Stops the running containers. + +- ``just prune`` + Stops and removes containers along with their volumes. You can optionally pass an argument with the service name to prune a single container. + +- ``just logs`` + Shows container logs. You can optionally pass an argument with the service name to view logs for a specific service. + +- ``just manage `` + Runs Django management commands within the container. Replace ```` with any valid Django management command, such as ``migrate``, ``createsuperuser``, or ``shell``. + + (Optionally) Developing locally with HTTPS ------------------------------------------ diff --git a/hooks/post_gen_project.py b/hooks/post_gen_project.py index ca1ffad3..1eee7ef6 100644 --- a/hooks/post_gen_project.py +++ b/hooks/post_gen_project.py @@ -82,6 +82,7 @@ def remove_docker_files(): "docker-compose.local.yml", "docker-compose.production.yml", ".dockerignore", + "justfile", ] for file_name in file_names: os.remove(file_name) diff --git a/{{cookiecutter.project_slug}}/justfile b/{{cookiecutter.project_slug}}/justfile new file mode 100644 index 00000000..38ef8dd4 --- /dev/null +++ b/{{cookiecutter.project_slug}}/justfile @@ -0,0 +1,38 @@ +export COMPOSE_FILE := "docker-compose.local.yml" + +## Just does not yet manage signals for subprocesses reliably, which can lead to unexpected behavior. +## Exercise caution before expanding its usage in production environments. +## For more information, see https://github.com/casey/just/issues/2473 . + + +# Default command to list all available commands. +default: + @just --list + +# build: Build python image. +build: + @echo "Building python image..." + @docker compose build + +# up: Start up containers. +up: + @echo "Starting up containers..." + @docker compose up -d --remove-orphans + +# down: Stop containers. +down: + @echo "Stopping containers..." + @docker compose down + +# prune: Remove containers and their volumes. +prune *args: + @echo "Killing containers and removing volumes..." + @docker compose down -v {{ "{{args}}" }} + +# logs: View container logs +logs *args: + @docker compose logs -f {{ "{{args}}" }} + +# manage: Executes `manage.py` command. +manage +args: + @docker compose run --rm django python ./manage.py {{ "{{args}}" }}