Project and Repository Structure
Filesystem Structure
This is the structure of the repository with the most important directories and files. There is of course more in the repository, but the important parts are listed here.
+--+ components
| +--- app # The main application code
| +--- configs # Configuration files used in Docker images
| +--- test-acceptance # BDD-style Acceptance tests
| +--- test-compliance # Compliance tests with Chef Inspec
+--- docs # Documentation (Antora component)
+--- testdata # Test data for all kinds of tests
+--- Dockerfile # Multi-Stage Dockerfile for the main applicationwebsite
+--- docker-compose.yml # Docker Compose file with the toolchain (e.g. for local development)Pipeline
The build pipeline is triggered by a commit to any branch in the repository. But not all branches are treated equally. The main branch is the most important branch in the repository. It is the branch that is always deployable and is the branch that is used to deploy to production. Other branches use a subset of the pipeline to ensure that they can be merged into the main branch and are are in a deployable state.
Docker Scout Scan
We use the docker-scout tool to scan the Docker image for vulnerabilities. The tool is run as part of the Docker image build process in out pipeline. The tool is configured not to break the build, but to provide a report of the vulnerabilities found in the image. The report is then used to decide if the image is safe or if it needs to be fixed.
Docker Image Build
The Docker image build process is separated into multiple steps. The image is a Multi-Stage Dockerfile to ensure that the final image is as small as possible with as few dependencies as possible. Part of the build process is to run unit tests and acceptance tests to ensure that the image is working as expected. For more information, see Dockerfile.
Acceptance Tests
We use acceptance tests to ensure that the source2adoc CLI tool works as expected. The acceptance tests are written in Gherkin and can be found in the components/test-acceptance/specs directory. We run the same set of tests locally from the IDE and as part of the Docker image build.
The simplest way to run the acceptance tests is to use the docker compose up acceptance-test command. This command will build a binary of the app and runs the acceptance tests against the app. This is intended to be used in the local development environment.
However, the actual build breaker is the Docker image build itself where the acceptance tests are run in a dedicated stage against the binary inside the image.