Document frontend development

Author: aequitas

Makefile

@@ -399,6 +399,7 @@ qa: fix check test
 env ?=
 environment ?= ${env}
 test_args ?= ${testargs}
+services ?= ${service}
 ifeq (${environment},dev)
 	environment = develop
 endif
@@ -440,13 +441,16 @@ docker-compose:
 	${DOCKER_COMPOSE_CMD} ${args}
 
 up docker-compose-up:
-	${DOCKER_COMPOSE_UP_PULL_CMD} up --wait --no-build --remove-orphans ${services}
+	${DOCKER_COMPOSE_UP_PULL_CMD} up --wait --no-build --remove-orphans --timeout=0 ${services}
 	@if [ "${environment}" = "test" ]; then echo -e "\n🚀 Running on http://localhost:8081"; fi
 	@if [ "${environment}" = "develop" ]; then echo -e "\n🚀 Running on http://localhost:8080"; fi
 	@if [ "${environment}" = "batch-test" ]; then echo -e "\n🚀 Running on http://localhost:8081"; fi
 
+up-no-wait:
+	${DOCKER_COMPOSE_UP_PULL_CMD} up --detach --no-build --remove-orphans --timeout=0 ${services}
+
 run docker-compose-run:
-	${DOCKER_COMPOSE_UP_PULL_CMD} up --no-build ${services}
+	${DOCKER_COMPOSE_UP_PULL_CMD} up --watch --remove-orphans --timeout=0 ${services}
 
 restart docker-compose-restart:
 	${DOCKER_COMPOSE_CMD} restart --no-deps ${services}
@@ -512,7 +516,7 @@ stop docker-compose-stop:
 
 # stop and remove all containers, but keep volumes (eg: routinator cache, databases)
 down docker-compose-down:
-	${DOCKER_COMPOSE_CMD} down
+	${DOCKER_COMPOSE_CMD} down --timeout=0
 
 down-remove-volumes docker-compose-down-remove-volumes:
 	${DOCKER_COMPOSE_CMD} down --volumes
@@ -718,3 +722,21 @@ ${TMPDIR}/tranco_list_%k.txt: ${TMPDIR}/tranco_list.txt
 ${TMPDIR}/tranco_list.txt:
 	# download tranco list, unzip, convert from csv to plain list of domains
 	curl -Ls https://tranco-list.eu/download_daily/4Q39X | bsdtar -xOf - | cut -d, -f2 > $@
+
+# convenience target, will build and run all services for development and output logs for the relevant ones
+develop:
+	# (re)build all services
+	${MAKE} build env=develop
+	# bring entire environment up
+	${MAKE} up-no-wait env=develop
+	# wait and log on relevant services
+	${MAKE} run env=develop services='app webserver worker worker-slow worker-nassl'
+	# shut everything down
+	${MAKE} down env=develop
+
+# same as develop, but focus on frontend only
+develop_frontend:
+	# only bring up what is needed for frontend development
+	${MAKE} build run env=develop services='app webserver port-expose'
+	# shut everything down
+	${MAKE} down env=develop

documentation/Docker-development-environment.md

@@ -64,6 +64,28 @@ Multiple services can be specified like so:
 
 Using a Docker runtime with more memory and CPU cores improves rebuild/restart speed.
 
+### Auto reload
+
+Once the development environment is up and running it will autotically rebuild/restart/reload when certain parts of the source code change. Currently changes to the following files will be detected and acted upon:
+
+- Python sources in  `checks/`, `internetnl/`, `interface/`: will reload `app` and `worker*` using Django autoreload, when needed open browser sessions will reload.
+- CSS files in `frontend/css/`: will rebuild CSS files and open browser sessions will reload.
+- Django template files (`.html`) in `interface/templates/`: open browser sessions will reload.
+
+### Foreground development
+
+Instead of running in the background the application stack can also be started in foreground mode using the command:
+
+    make develop
+
+This convenience command will build all relevant services, start the entire stack and show log output for the most relevant services. The Docker Compose application will keep running in the foreground. Terminating it (with `ctrl-c`) will shutdown all running services and bring down the entire application stack.
+
+#### Frontend development
+
+When only developing on frontend parts of the application (eg: `html`, `css`, `javascript`, Django templates/views), a smaller subset of the application can be started using:
+
+    make develop_frontend
+
 ### Running/debugging individual probes
 
 It is possible to run individual probes with debug logging using a manage command. This provides a quick way to iterate over changes regarding test/probe code without having to go through the web interface. For this run the following command: