README.md

guacscanner-docker

Docker Image

This project Dockerizes cisagov/guacscanner, and the resulting Docker container is intended to run as a part of cisagov/guacamole-composition, although it could - probably uselessly - run in a Docker composition alongside only the official PostgreSQL Docker image.

Running

Running with Docker

To run the cisagov/guacscanner image via Docker:

docker run cisagov/guacscanner:1.1.18

Running with Docker Compose

See cisagov/guacamole-composition) for an example of how to create a docker-compose.yml file to use Docker Compose. With a docker-compose.yml file in hand, one need only 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.

Again, see cisagov/guacamole-composition) for an example of how to create a docker-compose.yml file that uses Docker secrets.

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/guacscanner:1.1.18

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

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. :1.1.18).

Image:tag	Description
cisagov/guacscanner:1.1.18	An exact release version.
cisagov/guacscanner:1.1	The most recent release matching the major and minor version numbers.
cisagov/guacscanner:1	The most recent release matching the major version number.
cisagov/guacscanner:edge	The most recent image built from a merge into the develop branch of this repository.
cisagov/guacscanner:nightly	A nightly build of the develop branch of this repository.
cisagov/guacscanner: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

There are no volumes.

Ports

No ports are exposed by this container.

Environment variables

Required

There are no required environment variables.

Optional

There are no optional environment variables.

Secrets

Filename	Purpose
postgres_username	Text file containing the username of the postgres user used by the guacamole container.
postgres_password	Text file containing the password of the postgres user used by the guacamole container.
private_ssh_key	Text file containing the private SSH key to use for SFTP file transfer in Guacamole.
rdp_username	Text file containing the username for Guacamole to use when connecting to an instance via RDP.
rdp_password	Text file containing the password for Guacamole to use when connecting to an instance via RDP.
vnc_username	Text file containing the username for Guacamole to use when connecting to an instance via VNC.
vnc_password	Text file containing the password for Guacamole to use when connecting to an instance via VNC.
windows_sftp_base	Text file containing the base path for the SFTP directories that Guacamole will use when connecting to a Windows instance via VNC.

Building from source

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

docker build \
  --build-arg VERSION=1.1.18 \
  --tag cisagov/guacscanner:1.1.18 \
  https://github.com/cisagov/guacscanner.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/guacscanner.git
   cd guacscanner

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 \
     --build-arg VERSION=1.1.18 \
     --output type=docker \
     --tag cisagov/guacscanner:1.1.18 .

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.