Local Setup with Docker Compose
Relevant source files
The following files were used as context for generating this wiki page:
The huskyCI project provides a docker-compose.yml file to facilitate the setup of a complete local development and testing environment. This setup orchestrates all the necessary backend services, including the main API, a database, and a Docker-in-Docker (DinD) environment for running the security analysis containers.
This local environment is essential for developers contributing to huskyCI, allowing them to run and test the entire application stack on their local machine. The setup is designed to mirror a production-like environment, ensuring consistency and reliability during development.
Sources: README.md:42, deployments/docker-compose.yml
System Architecture
The local environment is composed of three core services that are orchestrated by Docker Compose. These services communicate over a dedicated Docker network (huskyCI_net) to provide the full functionality of huskyCI.
The following diagram illustrates the high-level architecture of the services defined in the Docker Compose setup.
Sources: deployments/docker-compose.yml:4-105
Services
The table below summarizes the services that constitute the local huskyCI environment.
| Service | Container Name | Image | Purpose |
|---|---|---|---|
dockerapi | huskyCI_Docker_API | docker:24-rc-dind | Provides a Docker-in-Docker (DinD) environment, exposing a Docker API endpoint for the api service to create and manage security test containers. |
api | huskyCI_API | Custom built from api.Dockerfile | The core huskyCI backend. It receives analysis requests, orchestrates the security scans by communicating with the dockerapi service, and stores results in MongoDB. |
mongodb | huskyCI_MongoDB | mongo:4.2.2 | The database service used to store analysis data, security test configurations, and user information. |
Sources: deployments/docker-compose.yml:4-65
dockerapi Service
This service runs a Docker daemon inside a container (Docker-in-Docker). It is configured to listen on a TCP socket, allowing the api service to connect to it and manage Docker containers for security scans.
- Image:
docker:24-rc-dind - Exposed Port:
2376 - Key Configuration: It runs with
privileged: trueand mounts a volume (docker_vol) to persist the Docker data. It also mounts adaemon.jsonfor custom Docker daemon configuration and acertsdirectory for TLS communication.
Sources: deployments/docker-compose.yml:5-16
api Service
This is the main application service. It is built from the local source code using deployments/dockerfiles/api.Dockerfile. It depends on mongodb and dockerapi to be running before it starts.
- Exposed Port:
8888 - Dependencies: The
apiservice will only start after themongodbservice is healthy and thedockerapiservice has started. This ensures that the database and Docker engine are available when the API boots up. - Volumes: It mounts the
docker_volto interact with the DinD service and also mounts certificate files (cert.pem,key.pem,ca.pem) to securely communicate with thedockerapi.
Sources: deployments/docker-compose.yml:18-47
mongodb Service
This service provides a MongoDB database instance. It uses an official mongo image and is configured with initial credentials and a database name.
- Image:
mongo:4.2.2 - Exposed Ports:
27017,27018 - Healthcheck: A healthcheck is configured to ensure the
apiservice waits until the database is fully operational. It does this by runningdb.stats().okperiodically. - Persistence: It uses a named volume
mongo_volto persist database files across container restarts.
Sources: deployments/docker-compose.yml:49-65
Configuration
The behavior of the local environment, particularly the api service, is controlled through environment variables defined in docker-compose.yml.
Environment Variables
The api service is configured with several environment variables that dictate its connection to other services and its default settings.
| Variable | Value | Description |
|---|---|---|
HUSKYCI_DATABASE_DB_ADDR | mongodb | The network address of the MongoDB service. |
HUSKYCI_DATABASE_DB_NAME | huskyCIDB | The name of the database to use. |
HUSKYCI_DATABASE_DB_USERNAME | huskyCIUser | The username for the database connection. |
HUSKYCI_DATABASE_DB_PASSWORD | huskyCIPassword | The password for the database connection. |
HUSKYCI_API_DEFAULT_USERNAME | huskyCIUser | The default username for the API. |
HUSKYCI_API_DEFAULT_PASSWORD | huskyCIPassword | The default password for the API. |
HUSKYCI_API_ALLOW_ORIGIN_CORS | * | Configures the CORS policy for the API. |
HUSKYCI_DOCKERAPI_ADDR | dockerapi | The network address of the dockerapi service. |
HUSKYCI_DOCKERAPI_TLS_VERIFY | 0 | Disables TLS verification for the Docker API connection (for local dev). |
HUSKYCI_INFRASTRUCTURE_USE | docker | Specifies that the infrastructure for running scans is Docker. |
Sources: deployments/docker-compose.yml:22-32, api/util/api/api.go:52-79
Volumes and Networking
- Networking: All services are connected to a bridge network named
huskyCI_net, allowing them to resolve each other by their service names (e.g.,api,mongodb,dockerapi). - Volumes:
docker_vol: A shared volume betweenapianddockerapito manage Docker state.mongo_vol: A dedicated volume formongodbto persist data.certs: Thedeployments/certsdirectory is mounted to provide TLS certificates for securing the Docker daemon socket.
Sources: deployments/docker-compose.yml:12-15, 36-40, 59-60, 101-105
Setup and Usage
To run the local environment, you first need to build the necessary Docker images for the security tools, and then you can start the stack using Docker Compose.
Building Security Tool Containers
The deployments/scripts/build-containers.sh script is used to build all the Docker images for the security tools that huskyCI orchestrates.
This script builds the following tool images and tags them as :latest:
| Tool | Image Name |
|---|---|
| Bandit | huskyci/bandit |
| Brakeman | huskyci/brakeman |
| Enry | huskyci/enry |
| GitAuthors | huskyci/gitauthors |
| Gosec | huskyci/gosec |
| NpmAudit | huskyci/npmaudit |
| YarnAudit | huskyci/yarnaudit |
| Safety | huskyci/safety |
| Gitleaks | huskyci/gitleaks |
| SpotBugs | huskyci/spotbugs |
| TFSec | huskyci/tfsec |
| SecurityCodeScan | huskyci/securitycodescan |
Sources: deployments/scripts/build-containers.sh:9-20
Running the Environment
After building the tool containers, the environment can be started with docker-compose up. The startup process respects the dependencies defined between services.
The diagram below shows the startup sequence based on the depends_on configuration.
Sources: deployments/docker-compose.yml:43-47
Pushing Containers
For development and release purposes, the deployments/scripts/push-containers.sh script is provided. It retrieves the version of each security tool, tags the corresponding :latest image with that version, and pushes both the :latest and versioned tags to a Docker registry. This is useful for sharing the built images.
Sources: deployments/scripts/push-containers.sh
Conclusion
The Docker Compose setup is a cornerstone of the huskyCI development workflow. It provides a self-contained, easy-to-launch environment that includes all the necessary backend components. By defining the services, configurations, and dependencies in code, it ensures that all developers can work with a consistent and reliable stack, simplifying testing, debugging, and contribution to the project.
Sources: README.md:42, deployments/docker-compose.yml