Skip to content

README.md

Latest commit

 

History

History
230 lines (165 loc) · 8.94 KB

README.md

File metadata and controls

230 lines (165 loc) · 8.94 KB
Raw

Using Docker with CVE Services

Security Considerations

Warning

DO NOT use the included Docker Compose configuration on a public network. The example environment files contain development credentials and MongoDB authentication is not enforced. This setup is for local development only.

Local Development and Testing

Run all commands in this guide from the repository root. Docker with the Compose plugin is required. Choose one of the two configurations:

Configuration Application MongoDB Application port
docker/docker-compose.yml Development container One-member replica set, docdb:27017 inside Docker 3000
docker/docker-compose.mongo-cluster.yml Runs separately on the host Three-member replica set, host ports 27017–27019 8081 by default

The configurations share container names and ports, so stop one before starting the other. MongoDB runs as a replica set because application operations use transactions.

Start Docker Containers

Initialize the migrations submodule before building the development image:

git submodule update --init migrations
cp docker/.docker-env.test-example docker/.docker-env

The test example is also used by CI and starts the application in development mode. It matches the one-member replica set in docker-compose.yml; the .docker-env.example connection string names additional members that this Compose file does not start.

Review docker/.docker-env before starting. Keep NODE_ENV=development, MONGO_HOST=docdb, MONGO_PORT=27017, PORT=3000, and TEST_PORT=3001. LOCAL_KEY supplies the API key for all users created by local population; keep the example value when running the integration suite, whose request headers use that fixture key. Add these empty overrides so the application and population scripts select the development or test database from the container configuration:

MONGO_CONN_STRING=
MONGO_DB_NAME=

The development image copies the checkout, including any root .env. These overrides prevent host connection settings from that file from being used inside the container. The image installs application and migration dependencies during the build.

docker compose -f docker/docker-compose.yml up -d --build
docker compose -f docker/docker-compose.yml logs -f cveawg

The mongo-init service initializes replica set rs0. Wait for the application log to show Serving on port 3000; press Ctrl+C to leave the log view. Open Swagger UI at http://localhost:3000/api-docs/.

The Compose application uses Dockerfile.dev, based on Node.js 24. The separate production Dockerfile builds with Node.js 24.22.1 and uses a Distroless Node.js 24 runtime. Shell, population, and test commands in this guide apply to the development image.

The Docker CVE_PREFLIGHT argument

Both Dockerfiles accept an optional CVE_PREFLIGHT build argument for environment-specific setup, such as corporate CA certificates or proxy configuration, before package installation. To supply a command approved for your environment:

docker compose -f docker/docker-compose.yml build --no-cache --build-arg CVE_PREFLIGHT='<setup command>'

Omit the argument when no extra setup is needed.

Pre-load Data and Run Migrations

The population command prompts before dropping the entire development database, loading seed data, and applying pending migrations:

docker compose -f docker/docker-compose.yml exec cveawg npm run populate:dev

It populates Cve, Cve-Id-Range, Cve-Id, BaseOrg, BaseUser, and Glossary using fixtures in datadump/pre-population/ and generated organizations. All seeded users share the LOCAL_KEY value in docker/.docker-env. Population is restricted to development and test environments.

To apply migrations to existing development data without a reset:

docker compose -f docker/docker-compose.yml exec cveawg npm run db:migrate:status
docker compose -f docker/docker-compose.yml exec cveawg npm run db:migrate:dev

See the migration instructions for details, including how to skip automatic migrations during population. Rebuild the development image after updating the migrations submodule; it is copied into the image.

Use curl to Call the API

After population, use the seeded Secretariat organization mitre, user admin2@mitre.org, and your configured LOCAL_KEY.

Create a curl configuration file and restrict its permissions before adding credentials:

touch "$HOME/.curl-cve-config"
chmod 600 "$HOME/.curl-cve-config"

Save the following in that file, replacing <LOCAL_KEY> with the value from docker/.docker-env:

-H "CVE-API-ORG: mitre"
-H "CVE-API-USER: admin2@mitre.org"
-H "CVE-API-KEY: <LOCAL_KEY>"
-H "Content-Type: application/json"
-s
-S

List CVE IDs or Data Registry organizations:

curl -K "$HOME/.curl-cve-config" http://localhost:3000/api/cve-id
curl -K "$HOME/.curl-cve-config" http://localhost:3000/api/registry/org

Create a CNA using the Data Registry API with the seeded Secretariat credentials:

curl -K "$HOME/.curl-cve-config" -X POST \
  --data-binary '{"long_name":"Example Corporation","short_name":"exampleCorp","authority":["CNA"],"id_quota":1000,"disabled":false}' \
  http://localhost:3000/api/registry/org

See the API documentation for schemas, access rules, and related legacy endpoints.

Open a Shell or Regenerate API Documentation

Open a shell in the development application container:

docker compose -f docker/docker-compose.yml exec cveawg /bin/sh

After changing API annotations, regenerate the documentation and reload Swagger UI:

docker compose -f docker/docker-compose.yml exec cveawg npm run swagger-autogen

This updates the specification inside the container. Run npm run swagger-autogen on the host to update the repository's api-docs/openapi.json. The Compose file mounts src/ but does not mount schemas/ or api-docs/; rebuild the development image after schema changes.

MongoDB

The full application Compose file exposes MongoDB on host port 27017, while replica set discovery advertises the internal hostname docdb. For a host GUI connection to that single member, use:

mongodb://127.0.0.1:27017/cve_dev?directConnection=true

For an application running on the host, use the Mongo-only configuration below. MongoDB Compass is optional.

Run the Mongo Replica Cluster Only

The Mongo-only Compose file starts one primary and two secondary members without starting the application. By default it uses mongo:5.0.

docker compose -f docker/docker-compose.mongo-cluster.yml up -d docdb docdb-read-1 docdb-read-2 mongo-init
docker compose -f docker/docker-compose.mongo-cluster.yml logs -f mongo-init

Wait for Replica set is ready with one primary and two secondaries. and press Ctrl+C to leave the log view. Use this connection string for development on the host, including Compass:

mongodb://127.0.0.1:27017,127.0.0.1:27018,127.0.0.1:27019/cve_dev?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false

Use cve_test in place of cve_dev for test data. Follow the local application setup to configure the API key, install dependencies, populate data, and start the application.

To run the same local replica topology with MongoDB 8, override the image:

MONGO_IMAGE=mongo:8.0 docker compose -f docker/docker-compose.mongo-cluster.yml up -d --force-recreate docdb docdb-read-1 docdb-read-2 mongo-init

The Mongo-only compose file overrides GLIBC_TUNABLES for compatibility with Docker Desktop Linux kernels 6.19 through 7.0.13. MongoDB's default TCMalloc configuration refuses to start on those kernel versions. The override can be removed after all development environments use kernel 7.0.14 or newer.

If the volumes already contain MongoDB 5 data, MongoDB 8 may fail to start against those files. For a fresh MongoDB 8 local cluster, remove the Mongo-only volumes first. This deletes all local MongoDB data for this Compose file.

docker compose -f docker/docker-compose.mongo-cluster.yml down -v
MONGO_IMAGE=mongo:8.0 docker compose -f docker/docker-compose.mongo-cluster.yml up -d docdb docdb-read-1 docdb-read-2 mongo-init

Running Tests

Run unit tests in the development application container:

docker compose -f docker/docker-compose.yml exec cveawg npm run test:unit-tests

Run integration tests against the container's cve_test database:

docker compose -f docker/docker-compose.yml exec -e MONGO_DB_NAME=cve_test cveawg npm run test:integration

Integration tests drop and repopulate the test database without prompting, then apply migrations and run the suite. See the testing README for the host replica command and configuration details.