feat: modernize Docker Compose setup and simplify installation docs

.devcontainer/demo/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "DejaCode Demo (Codespaces only)",
-  "dockerComposeFile": "../../docker-compose.demo.yml",
+  "dockerComposeFile": "../../compose.demo.yml",
   "service": "web",
   "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",
   "overrideCommand": false,

.github/workflows/check-code-and-docs-validation.yml

@@ -0,0 +1,34 @@
+name: Run unit tests
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  check-code-and-docs-validation:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false  # do not keep the token around
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: "3.14"
+
+      - name: Install uv from vendored wheel
+        run: pip install --no-index --find-links=./thirdparty/dist uv
+
+      - name: Validate code format
+        run: make check
+
+      - name: Build the documentation
+        run: make docs

Makefile

@@ -6,14 +6,84 @@
 # See https://aboutcode.org for more information about AboutCode FOSS projects.
 #
 
+########################################################################################
+# Docker dev commands
+########################################################################################
+
+IMAGE_NAME=dejacode:dev
+COMPOSE=docker compose -f compose.dev.yml
+MANAGE=${COMPOSE} exec web ./manage.py
+EXEC=${COMPOSE} exec
+
+run:
+	@echo "-> Run the Docker compose services in dev mode (hot reload on code changes)"
+	${COMPOSE} up
+
+bash:
+	# Open a bash session in the running web container
+	${COMPOSE} exec web bash
+
+shell:
+	# Open a bash session in a standalone container (no stack required)
+	docker run -it $(IMAGE_NAME) bash
+
+test:
+	@echo "-> Run the test suite"
+	${MANAGE} test --noinput --parallel auto
+
+migrations:
+	@echo "-> Creates new database migrations"
+	${MANAGE} makemigrations
+
+migrate:
+	@echo "-> Apply database migrations"
+	${MANAGE} migrate
+
+build:
+	@echo "-> Build the dev Docker images"
+	${COMPOSE} build
+
+superuser:
+	${MANAGE} createsuperuser
+
+########################################################################################
+# Utilities
+########################################################################################
+
+DOCS_LOCATION=./docs
+
+doc8:
+	@echo "-> Run documentation .rst validation"
+	uvx doc8==2.0.0 --max-line-length 100 --ignore-path docs/_build/ --quiet docs/
+
+valid:
+	@echo "-> Run Ruff format"
+	uvx ruff format
+	@echo "-> Run Ruff linter"
+	uvx ruff check --fix
+
+check:
+	@echo "-> Run Ruff linter validation (pycodestyle, bandit, isort, and more)"
+	uvx ruff check
+	@echo "-> Run Ruff format validation"
+	uvx ruff format --check
+	@$(MAKE) doc8
+
+docs:
+	@echo "-> Builds the documentation"
+	rm -rf ${DOCS_LOCATION}/_build/
+	uvx --from sphinx==9.1.0 --with furo==2025.12.19 sphinx-build -b singlehtml ${DOCS_LOCATION} ${DOCS_LOCATION}/_build/singlehtml/
+	uvx --from sphinx==9.1.0 --with furo==2025.12.19 sphinx-build -b html ${DOCS_LOCATION} ${DOCS_LOCATION}/_build/html/
+
+########################################################################################
+
 VENV_LOCATION=.venv
 ACTIVATE?=. ${VENV_LOCATION}/bin/activate;
-MANAGE=${VENV_LOCATION}/bin/python manage.py
+#MANAGE=${VENV_LOCATION}/bin/python manage.py
 # Do not depend on Python to generate the SECRET_KEY
 GET_SECRET_KEY=`head -c50 /dev/urandom | base64 | head -c50`
 # Customize with `$ make envfile ENV_FILE=/etc/dejacode/.env`
 ENV_FILE=.env
-DOCS_LOCATION=./docs
 DOCKER_COMPOSE=docker compose -f docker-compose.yml
 DOCKER_EXEC=${DOCKER_COMPOSE} exec
 DB_NAME=dejacode_db
@@ -23,19 +93,6 @@ DB_CONTAINER_NAME=db
 DB_INIT_FILE=./data/postgresql/initdb.sql.gz
 POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8
 TIMESTAMP=$(shell date +"%Y-%m-%d_%H%M")
-IMAGE_NAME=dejacode
-
-# Use sudo for postgres, only on Linux
-UNAME := $(shell uname)
-ifeq ($(UNAME), Linux)
-	SUDO_POSTGRES=sudo -u postgres
-else
-	SUDO_POSTGRES=
-endif
-
-virtualenv:
-	@echo "-> Bootstrap the virtualenv with uv"
-	uv venv --allow-existing ${VENV_LOCATION}
 
 conf: virtualenv
 	@echo "-> Install dependencies"
@@ -91,28 +148,6 @@ envfile_dev: envfile
 	@echo "-> Update the .env file for development"
 	@echo DATABASE_PASSWORD=\"dejacode\" >> ${ENV_FILE}
 
-doc8:
-	@echo "-> Run documentation .rst validation"
-	uvx doc8==2.0.0 --max-line-length 100 --ignore-path docs/_build/ --quiet docs/
-
-valid:
-	@echo "-> Run Ruff format"
-	@${ACTIVATE} ruff format
-	@echo "-> Run Ruff linter"
-	@${ACTIVATE} ruff check --fix
-
-check:
-	@echo "-> Run Ruff linter validation (pycodestyle, bandit, isort, and more)"
-	@${ACTIVATE} ruff check
-	@echo "-> Run Ruff format validation"
-	@${ACTIVATE} ruff format --check
-	@echo "-> Running ABOUT files validation"
-	@${ACTIVATE} about check ./thirdparty/
-	@${ACTIVATE} about check ./data/
-	@${ACTIVATE} about check ./dje/
-	@${ACTIVATE} about check ./dejacode_toolkit/
-	@$(MAKE) doc8
-
 check-deploy:
 	@echo "-> Check Django deployment settings"
 	${MANAGE} check --deploy
@@ -139,62 +174,11 @@ initdb:
 	@echo "Starting Docker services"
 	${DOCKER_COMPOSE} start
 
-migrate:
-	@echo "-> Apply database migrations"
-	${MANAGE} migrate
-
-postgresdb:
-	@echo "-> Configure PostgreSQL database"
-	@echo "-> Create database user ${DB_NAME}"
-	@${SUDO_POSTGRES} createuser --no-createrole --no-superuser --login --inherit --createdb '${DB_USERNAME}' || true
-	@${SUDO_POSTGRES} psql -c "alter user ${DB_USERNAME} with encrypted password '${DB_PASSWORD}';" || true
-	@echo "-> Drop ${DB_NAME} database if exists"
-	@${SUDO_POSTGRES} dropdb ${DB_NAME} || true
-	@echo "-> Create ${DB_NAME} database: createdb --owner=${DB_USERNAME} ${POSTGRES_INITDB_ARGS} ${DB_NAME}"
-	@${SUDO_POSTGRES} createdb --owner=${DB_USERNAME} ${POSTGRES_INITDB_ARGS} ${DB_NAME}
-	@gunzip < ${DB_INIT_FILE} | psql --username=${DB_USERNAME} ${DB_NAME}
-	@echo "-> Apply database migrations"
-	${MANAGE} migrate
-
-postgresdb_clean:
-	@echo "-> Drop PostgreSQL user and database"
-	@${SUDO_POSTGRES} dropdb ${DB_NAME} || true
-	@${SUDO_POSTGRES} dropuser '${DB_USERNAME}' || true
-
-run:
-	DJANGO_RUNSERVER_HIDE_WARNING=true ${MANAGE} runserver 8000 --insecure
-
-worker:
-	${MANAGE} rqworker
-
-test:
-	@echo "-> Run the test suite"
-	${MANAGE} test --noinput --parallel auto
-
-docs:
-	@echo "-> Builds the documentation"
-	rm -rf ${DOCS_LOCATION}/_build/
-	uvx --from sphinx==9.1.0 --with furo==2025.12.19 sphinx-build -b singlehtml ${DOCS_LOCATION} ${DOCS_LOCATION}/_build/singlehtml/
-	uvx --from sphinx==9.1.0 --with furo==2025.12.19 sphinx-build -b html ${DOCS_LOCATION} ${DOCS_LOCATION}/_build/html/
-
-build:
-	@echo "-> Build the Docker image"
-	docker build -t $(IMAGE_NAME) .
-
-bash:
-	docker run -it $(IMAGE_NAME) bash
-
-shell:
-	${DOCKER_EXEC} web ./manage.py shell
-
 psql:
 	${DOCKER_EXEC} ${DB_CONTAINER_NAME} psql --username=${DB_USERNAME} postgres
 
 # $ make log SERVICE=db
 log:
 	${DOCKER_COMPOSE} logs --tail="100" ${SERVICE}
 
-createsuperuser:
-	${DOCKER_EXEC} web ./manage.py createsuperuser
-
-.PHONY: virtualenv conf dev lock upgrade envfile envfile_dev check outdated doc8 valid check-deploy clean initdb postgresdb postgresdb_clean migrate run test docs build psql bash shell log createsuperuser
+.PHONY: virtualenv conf dev lock upgrade envfile envfile_dev check outdated doc8 valid check-deploy clean initdb postgresdb postgresdb_clean migrate run test docs build psql bash shell log superuser

README.rst

@@ -3,7 +3,8 @@ DejaCode
 ========
 
 DejaCode provides an enterprise-level application to automate open source license 
-compliance and ensure software supply chain integrity, powered by `ScanCode <https://github.com/aboutcode-org/scancode-toolkit>`_,
+compliance and ensure software supply chain integrity, powered by 
+`ScanCode <https://github.com/aboutcode-org/scancode-toolkit>`_,
 the industry-leading code scanner.
 
 Why Use DejaCode?

compose.build.yml

@@ -0,0 +1,13 @@
+name: dejacode
+
+x-description: "Build override: builds the app image from source instead of using the pre-built image"
+
+services:
+  web:
+    build: .
+
+  worker:
+    build: .
+
+  scheduler:
+    build: .

docker-compose.demo.yml → compose.demo.yml

@@ -1,4 +1,7 @@
-name: dejacode
+name: dejacode-demo
+
+x-description: "Minimal demo stack: web + db only, auto-created superuser, Codespaces-ready"
+
 services:
   db:
     image: docker.io/library/postgres:16.13
@@ -7,8 +10,9 @@ services:
     volumes:
       - ./data/postgresql:/docker-entrypoint-initdb.d/
     shm_size: "1gb"
+    restart: always
     healthcheck:
-      test: [ "CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}" ]
+      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
       interval: 10s
       timeout: 5s
       retries: 5