Publish v2025.6

.github/workflows/lint_md_changes.yml

@@ -16,12 +16,12 @@ jobs:
     - uses: actions/checkout@v4
       with:
         fetch-depth: 0
-    - uses: tj-actions/changed-files@823fcebdb31bb35fdf2229d9f769b400309430d0
+    - uses: tj-actions/changed-files@ed68ef82c095e0d48ec87eccea555d944a631a4c
       id: changed-files
       with:
         files: '**/*.md'
         separator: ","
-    - uses: DavidAnson/markdownlint-cli2-action@v19
+    - uses: DavidAnson/markdownlint-cli2-action@v20
       if: steps.changed-files.outputs.any_changed == 'true'
       with:
         globs: ${{ steps.changed-files.outputs.all_changed_files }}

.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

Makefile

@@ -1,66 +1,48 @@
 # Project-specific vars
-PFX=ssvc
-DOCKER=docker
-DOCKER_BUILD=$(DOCKER) build
-DOCKER_RUN=$(DOCKER) run --tty --rm
-PROJECT_VOLUME=--volume $(shell pwd):/app
 MKDOCS_PORT=8765
-
-# docker names
-TEST_DOCKER_TARGET=test
-TEST_IMAGE = $(PFX)_test
-DOCS_DOCKER_TARGET=docs
-DOCS_IMAGE = $(PFX)_docs
+DOCKER_DIR=docker
 
 # Targets
-.PHONY: all dockerbuild_test dockerrun_test dockerbuild_docs dockerrun_docs docs docker_test clean help
+.PHONY: all test docs docker_test clean help
 
 all: help
 
 mdlint_fix:
 	@echo "Running markdownlint..."
 	markdownlint --config .markdownlint.yml --fix .
 
-dockerbuild_test:
-	@echo "Building the test Docker image..."
-	$(DOCKER_BUILD) --target $(TEST_DOCKER_TARGET) --tag $(TEST_IMAGE) .
-
-dockerrun_test:
-	@echo "Running the test Docker image..."
-	$(DOCKER_RUN) $(PROJECT_VOLUME) $(TEST_IMAGE)
+test:
+	@echo "Running tests locally..."
+	pytest -v src/test
 
-dockerbuild_docs:
-	@echo "Building the docs Docker image..."
-	$(DOCKER_BUILD) --target $(DOCS_DOCKER_TARGET) --tag $(DOCS_IMAGE) .
+docker_test:
+	@echo "Running tests in Docker..."
+	pushd $(DOCKER_DIR) && docker-compose run --rm test
 
-dockerrun_docs:
-	@echo "Running the docs Docker image..."
-	$(DOCKER_RUN) --publish $(MKDOCS_PORT):8000 $(PROJECT_VOLUME) $(DOCS_IMAGE)
+docs:
+	@echo "Building and running docs in Docker..."
+	pushd $(DOCKER_DIR) && docker-compose up docs
 
+up:
+	@echo "Starting Docker services..."
+	pushd $(DOCKER_DIR) && docker-compose up -d
 
-docs: dockerbuild_docs dockerrun_docs
-docker_test: dockerbuild_test dockerrun_test
+down:
+	@echo "Stopping Docker services..."
+	pushd $(DOCKER_DIR) && docker-compose down
 
 clean:
-	@echo "Cleaning up..."
-	$(DOCKER) rmi $(TEST_IMAGE) $(DOCS_IMAGE) || true
+	@echo "Cleaning up Docker resources..."
+	pushd $(DOCKER_DIR) && docker-compose down --rmi local || true
 
 help:
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
 	@echo " all         - Display this help message"
 	@echo " mdlint_fix  - Run markdownlint with --fix"
-	@echo " docs        - Build and run the docs Docker image"
-	@echo " docker_test - Build and run the test Docker image"
-	@echo ""
-	@echo " dockerbuild_test - Build the test Docker image"
-	@echo " dockerrun_test   - Run the test Docker image"
-	@echo " dockerbuild_docs - Build the docs Docker image"
-	@echo " dockerrun_docs   - Run the docs Docker image"
-	@echo ""
-	@echo " clean - Remove the Docker images"
-	@echo " help  - Display this help message"
-
-
-
+	@echo " test        - Run the tests in a local shell"
+	@echo " docs        - Build and run the docs Docker service"
+	@echo " docker_test - Run the tests in a Docker container"
+	@echo " clean       - Remove Docker containers and images"
+	@echo " help        - Display this help message"

README.md

@@ -61,6 +61,19 @@ These json files are generated examples from the python `ssvc` module.
 
 These files are used by the `ssvc-calc` module.
 
+## `/docker/*`
+
+The `docker` directory contains Dockerfiles and related configurations for to
+create images that can run the SSVC documentation site and unit tests.
+
+Example:
+
+```bash
+cd docker
+docker-compose up test
+docker-compose up docs
+```
+
 ## `/src/*`
 
 This directory holds helper scripts that can make managing or using SSVC easier.
@@ -103,75 +116,30 @@ To preview any `make` command without actually executing it, run:
 make -n <command>
 ```
 
-### Run Local Server With Docker
-
-The easiest way to get started is using make to build a docker image and run the site:
-
-```bash
-make docs
-```
-
-Then navigate to <http://localhost:8765/SSVC/> to see the site.
-
-Note that the docker container will display a message with the URL to visit, for
-example: `Serving on http://0.0.0.0:8000/SSVC/` in the output. However, that port
-is only available inside the container. The host port 8765 is mapped to the container's
-port 8000, so you should navigate to <http://localhost:8765/SSVC/> to see the site.
+### Run Local Docs Server
 
-Or, if make is not available:
+The easiest way to get started is using make to build a docker image and run the site. However, we provide a few other options below.
 
-```bash
-docker build --target docs --tag ssvc_docs .
-docker run --tty --rm -p 8765:8000 --volume .:/app ssvc_docs
-```
+| Environment | Command |
+|-------------|---------|
+| Make, Docker | `make docs` |
+| ~~Make~~, Docker | `cd docker && docker-compose up docs` |
+| ~~Make~~, ~~Docker~~ | `mkdocs serve` |
 
-### Run Local Server Without Docker
-
-If you prefer to run the site locally without Docker, you can do so with mkdocs.
-We recommend using a virtual environment to manage dependencies:
-
-```bash
-python3 -m venv ssvc_venv
-pip install -r requirements.txt
-```
-
-Start a local server:
-
-```bash
-mkdocs serve
-```
-
-By default, the server will run on port 8001.
-This is configured in the `mkdocs.yml` file.
-Navigate to <http://localhost:8001/> to see the site.
-
-(Hint: You can use the `--dev-addr` argument with mkdocs to change the port, e.g. `mkdocs serve --dev-addr localhost:8000`)
+Then navigate to <http://localhost:8000/SSVC/> to see the site.
 
 ## Run tests
 
 We include a few tests for the `ssvc` module.
+Options for running the test suite are provided below.
 
-### Run Tests With Docker
-
-The easiest way to run tests is using make to build a docker image and run the tests:
+| Environment | Command | Comment |
+|-------------|---------|---------|
+| Make, Docker | `make docker_test` | runs in docker container |
+| ~~Make~~, Docker | `cd docker && docker-compose run -rm test` | runs in docker container |
+| Make, ~~Docker~~ | `make test` | runs in host OS |
+| ~~Make~~, ~~Docker~~ | `pytest src/test` | runs in host OS |
 
-```bash
-make docker_test
-```
-
-Or, if make is not available:
-
-```bash
-docker build --target test --tag ssvc_test .
-docker run --tty --rm --volume .:/app ssvc_test
-```
-
-### Run Tests Without Docker
-
-```bash
-pip install pytest
-pytest src/test
-```
 
 ## Environment Variables
 

Dockerfile → docker/Dockerfile

@@ -5,10 +5,10 @@ WORKDIR /app
 FROM base AS dependencies
 
 # install requirements
-COPY requirements.txt .
+COPY ../requirements.txt .
 RUN pip install -r requirements.txt
 # Copy the files we need
-COPY . /app
+COPY .. /app
 # Set the environment variable
 ENV PYTHONPATH=/app/src
 

docker/docker-compose.yml

@@ -0,0 +1,36 @@
+services:
+  base:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: base
+    image: base:latest
+
+  dependencies:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: dependencies
+    image: dependencies:latest
+    depends_on:
+      - base
+
+  test:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: test
+    image: test:latest
+    depends_on:
+      - dependencies
+
+  docs:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile
+      target: docs
+    image: docs:latest
+    depends_on:
+      - dependencies
+    ports:
+      - "8000:8000"

docs/index.md

@@ -10,14 +10,14 @@ We have organized the SSVC documentation into four main sections:
 
 <div class="grid cards" markdown>
 
-- :material-television-shimmer:{ .lg .middle } **Get Started with SSVC**
+- :fontawesome-regular-eye:{ .lg .middle } **SSVC Overview**
 
     ---
 
-    Get started learning about SSVC and how it can help you prioritize vulnerabilities.
-    This section is intended for people who are new to SSVC.
+    A beginner's guide to SSVC.
+    This section is for people who have never heard of SSVC.
 
-    [:octicons-arrow-right-24: Learning SSVC](tutorials/index.md)
+    [:octicons-arrow-right-24: An Overview of SSVC](ssvc_overview.md)
 
 - :material-clipboard-check:{ .lg .middle } **SSVC How To**
 
@@ -28,7 +28,7 @@ We have organized the SSVC documentation into four main sections:
 
     [:octicons-arrow-right-24: SSVC How To](howto/index.md)
 
-- :fontawesome-solid-book:{ .lg .middle } **Learn More about SSVC**
+- :fontawesome-solid-book:{ .lg .middle } **More about SSVC**
 
     ---