Base Docker Images

This project is a centralized way of managing Docker base images. It is recommended to have, at least, Java 11, and Docker installed. Hadolint and Trivy are required for lint and vulnerabilities scanning.

Table of Contents

• Project structure
• Building images
• Linting
• Vulnerabilities scanning
• Smoke testing
• Releasing
• Commit messages convention
• References

Project structure

When working in a large team with many developers that are responsible for the same codebase, having a common understanding of how the application should be structured is vital. Based on best practices from the community, other github projects and developer experience, your project should look like this:

.
├── .github
├── .mvn
├── base-image-nginx
│   ├── src
│   │   ├── docker
│   │   │   ├── assembly.xml
│   │   │   ├── Dockerfile
│   │   │   └── nginx.conf
│   │   └── test
│   │       ├── java
│   │       │   └── SmokeTests.java
│   │       └── resources
|   └── pom.xml
├── base-image-payara
│   ├── src
│   │   ├── docker
│   │   └── test
|   └── pom.xml
├── .editorconfig
├── .gitignore
├── .hadolint.yaml
├── mvnw
├── mvnw.cmd
├── pom.xml
└── README.md

All Docker content goes into a src/docker folder. The smoke tests are in the src/test folder.

Building images

Traditionally, you work with Docker images by authoring a Dockerfile, and with the help of docker build and docker push, you build and push your image to a remote registry. docker-maven-plugin is a Maven plugin for managing Docker images and containers.

To build all Docker images defined in each Dockerfile, you can use the next command:

./mvnw clean package

Then you can verify the built images via docker images command.

Linting

A linter is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs. Hadolint is a Dockerfile linter that helps to build best practice Docker images. The linter parses the Dockerfile into an AST and performs rules on top of the AST.

To enforce all best practices, you can use the next command:

./mvnw exec:exec -Plint

Depending on your editor, you may want to add an editor extension to lint your files while you type or on-save. This project includes some recommendations for Visual Studio Code.

Vulnerabilities scanning

Image scanning is way of detecting potential problems before running your containers. Trivy is a simple and comprehensive vulnerability/misconfiguration/secret scanner for containers and other artifacts.

To scan for vulnerabilities, you can use the next command:

./mvnw exec:exec -Pscan

Trivy supports different report formats. For more details, see the Report Formats page.

Smoke testing

Smoke testing is non-exhaustive software analysis that ascertains that the most crucial functions of a program work but does not delve into finer details. JUnit 5, Testcontainers and REST Assured are used in smoke tests.

To execute the smoke tests, you can use the next command:

./mvnw test -Psmoke

The first time, you need to build the Docker images used in the smoke tests. See Building images section.

You can also run per-module smoke tests. In each module run the test command.

Releasing

This project uses the Maven Release Plugin to release a new version of the project.

To create the first SNAPSHOT version, you must execute the commands ./mvnw release:prepare and ./mvnw release:perform. Considering a complete flow with an official release or a bugfix fix, you will need to change the MAJOR and MINOR versions of the project. Then, you will execute the prepare and perform command again so that these changes are inserted into your repository.

Commit messages convention

In order to have a consistent git history every commit must follow a specific template. Here's the template:

<type>(<ITEM ID>?): <subject>

Type

Must be one of the following:

• build: Changes that affect the build system or external dependencies (example scopes: Gradle, Maven)
• ci: Changes to our CI configuration files and scripts (example scopes: Jenkins, Travis, Circle, SauceLabs)
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
• docs: Documentation only changes
• feat: A new feature
• fix: A bug fix
• perf: A code change that improves performance
• refactor: A code change that neither fixes a bug nor adds a feature
• revert: A commit that reverts a previous one
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
• test: Adding missing tests or correcting existing tests

ITEM ID

The related issue or user story or even defect.

• For user stories, you shoud use US- as prefix. Example: feat(US-4321): ...
• For no related issues or defects you should leave it blank. Example: feat: ...

Subject

The subject contains a succinct description of the change.

References

For further reference, please consider the following articles:

• Official Apache Maven documentation
• How to use Fabric8
• Using Hadolint To Enforce Best Practices
• Continuous Container Vulnerability Testing
• Docker Test Containers in Java
• Conventional Commits
• Git Hooks Tutorial
• Maven Release Plugin