README.md

skeleton-docker 💀🐳

Docker Image

This is a Docker skeleton project that can be used to quickly get a new cisagov GitHub Docker project started. This skeleton project contains licensing information, as well as pre-commit hooks and GitHub Actions configurations appropriate for Docker containers and the major languages that we use.

Running

Running with Docker

To run the cisagov/example image via Docker:

docker run cisagov/example:0.2.0

Running with Docker Compose

1. Create a docker-compose.yml file similar to the one below to use Docker Compose.

   ---
   version: "3.7"
   
   services:
     example:
       image: cisagov/example:0.2.0
       volumes:
         - type: bind
           source: <your_log_dir>
           target: /var/log
       environment:
         - ECHO_MESSAGE="Hello from docker compose"
       ports:
         - target: 8080
           published: 8080
           protocol: tcp

2. Start the container and detach:

   docker compose up --detach

Using secrets with your container

This container also supports passing sensitive values via Docker secrets. Passing sensitive values like your credentials can be more secure using secrets than using environment variables. See the secrets section below for a table of all supported secret files.

1. To use secrets, create a quote.txt file containing the values you want set:

   Better lock it in your pocket.
   

2. Then add the secret to your docker-compose.yml file:

   ---
   version: "3.7"
   
   secrets:
     quote_txt:
       file: quote.txt
   
   services:
     example:
       image: cisagov/example:0.2.0
       volumes:
         - type: bind
           source: <your_log_dir>
           target: /var/log
       environment:
         - ECHO_MESSAGE="Hello from docker compose"
       ports:
         - target: 8080
           published: 8080
           protocol: tcp
       secrets:
         - source: quote_txt
           target: quote.txt

Updating your container

Docker Compose

1. Pull the new image from Docker Hub:

   docker compose pull

2. Recreate the running container by following the previous instructions:

   docker compose up --detach

Docker

1. Stop the running container:

   docker stop <container_id>

2. Pull the new image:

   docker pull cisagov/example:0.2.0

3. Recreate and run the container by following the previous instructions.

Updating Python dependencies

This image uses Pipenv to manage Python dependencies using a Pipfile. Both updating dependencies and changing the Pipenv configuration in src/Pipfile will result in a modified src/Pipfile.lock file that should be committed to the repository.

Warning

The src/Pipfile.lock as generated will fail pre-commit checks due to JSON formatting.

Updating dependencies

If you want to update existing dependencies you would run the following command in the src/ subdirectory:

pipenv lock

Modifying dependencies

If you want to add or remove dependencies you would update the src/Pipfile file and then update dependencies as you would above.

Note

You should only specify packages that are explicitly needed for your Docker configuration. Allow Pipenv to manage the dependencies of the specified packages.

Image tags

The images of this container are tagged with semantic versions of the underlying example project that they containerize. It is recommended that most users use a version tag (e.g. :0.2.0).

Image:tag	Description
cisagov/example:0.2.0	An exact release version.
cisagov/example:0.2	The most recent release matching the major and minor version numbers.
cisagov/example:0	The most recent release matching the major version number.
cisagov/example:edge	The most recent image built from a merge into the develop branch of this repository.
cisagov/example:nightly	A nightly build of the develop branch of this repository.
cisagov/example:latest	The most recent release image pushed to a container registry. Pulling an image using the :latest tag should be avoided.

See the tags tab on Docker Hub for a list of all the supported tags.

Volumes

Mount point	Purpose
/var/log	Log storage

Ports

The following ports are exposed by this container:

Port	Purpose
8080	Example only; nothing is actually listening on the port

The sample Docker composition publishes the exposed port at 8080.

Environment variables

Required

There are no required environment variables.

Optional

Name	Purpose	Default
ECHO_MESSAGE	Sets the message echoed by this container.	Hello World from Dockerfile

Secrets

Filename	Purpose
quote.txt	Replaces the secret stored in the example library's package data.

Building from source

Build the image locally using this git repository as the build context:

docker build \
  --tag cisagov/example:0.2.0 \
  https://github.com/cisagov/example.git#develop

Cross-platform builds

To create images that are compatible with other platforms, you can use the buildx feature of Docker:

1. Copy the project to your machine using the Code button above or the command line:

   git clone https://github.com/cisagov/example.git
   cd example

2. Create the Dockerfile-x file with buildx platform support:

   ./buildx-dockerfile.sh

3. Build the image using buildx:

   docker buildx build \
     --file Dockerfile-x \
     --platform linux/amd64 \
     --output type=docker \
     --tag cisagov/example:0.2.0 .

New repositories from a skeleton

Please see our Project Setup guide for step-by-step instructions on how to start a new repository from a skeleton. This will save you time and effort when configuring a new repository!

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

License

This project is in the worldwide public domain.

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.