Configuring Docker Executor

1. Specifying Docker Executor

Property	Values	Description
executor	`docker`	Specifies the use of the Docker executor for running jobs.
image	`circleci/node:16`	The Docker image to use for the job environment.
working_directory	`/home/circleci/project`	Directory where the job will run and where code is checked out.
resource_class	`medium`	Resource allocation for the job (e.g., `medium`, `large`, `xlarge`).

Example: Basic Docker Executor Configuration

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
        working_directory: /home/circleci/project
    steps:
      - checkout
      - run: npm install

2. Using Docker Images

Property	Value	Description
docker.image	`circleci/node:16`	Primary Docker image to use for the job
docker.image.name	`circleci/python:3.9`	Name of the Docker image to pull and run
docker.image.credentials	`{ username: "user", password: "pass" }`	Credentials for private Docker registries

Example: Using a Custom Docker Image

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
        environment:
          NODE_ENV: production
    steps:
      - checkout
      - run: npm install

Example: Using Private Docker Registry

version: 2.1
jobs:
  build:
    docker:
      - image: my-private-registry.com/my-app:latest
        credentials:
          username: $DOCKER_USERNAME
          password: $DOCKER_PASSWORD
    steps:
      - checkout
      - run: npm test

Note: CircleCI supports Docker images from public and private registries. Ensure credentials are properly configured in the project settings.

3. Specifying Image Tags

Tag Type	Description	Examples	Notes
image	Primary Docker image to use for the job	`circleci/node:16`	Must be a valid Docker image reference
image.tag	Specific tag to pull from Docker registry	`circleci/node:16-browsers`	Can be a version, branch, or digest
image.digest	SHA256 digest of the image	`circleci/node@sha256:abc123...`	Ensures reproducible builds

Example: Using a specific image tag

jobs:
  build:
    docker:
      - image: circleci/node:16-browsers

Example: Using image digest for reproducibility

jobs:
  build:
    docker:
      - image: circleci/node@sha256:abc123def456...

4. Using CircleCI Convenience Images

Image Name	Language/Stack	Tags	Notes
circleci/python	`Python`	`3.11`, `3.10`, `3.9`	Pre-configured Python environment with pip and venv
circleci/node	`Node.js`	`18`, `16`, `14`	Node.js with npm and yarn pre-installed
circleci/java	`Java`	`17`, `11`, `8`	OpenJDK with Maven and Gradle support
circleci/ruby	`Ruby`	`3.1`, `3.0`, `2.7`	Bundler and gems pre-installed
circleci/go	`Go`	`1.20`, `1.19`, `1.18`	Go with common tools like glide and dep

Example: Using Python Convenience Image

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/python:3.11
    steps:
      - checkout
      - run:
          name: Install Dependencies
          command: pip install -r requirements.txt

Note: Convenience images are optimized for CircleCI and include pre-installed tools to speed up builds.

5. Using Multiple Docker Images

Image	Usage	Notes
primary	`docker.image`	Primary container for the job
service	`docker.service`	Additional containers (e.g., databases, caches)
auxiliary	`docker.aux`	Optional containers for specific tasks

Example: Primary and Service Images

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
      - image: circleci/mongo:4.0
        name: mongodb
    steps:
      - checkout
      - run: echo "Running tests"

Note: Service containers are started before the primary container and can be accessed via their name or alias.

Example: Auxiliary Image for Testing

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
      - image: circleci/redis:6.0
        name: redis-cache
      - image: circleci/postgres:13
        name: postgres-db
    steps:
      - checkout
      - run: npm test

6. Authenticating with Registries

Registry	Authentication Method	Configuration	Notes
Docker Hub	`docker login`	`docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD`	Username and password required
Amazon ECR	AWS credentials	`eval $(aws ecr get-login --region us-east-1 --no-include-email)`	Requires AWS CLI and proper IAM permissions
Google Container Registry (GCR)	Service Account Key	`gcloud auth activate-service-account --key-file=service-account.json`	JSON key file must be base64 encoded
Azure Container Registry (ACR)	Azure CLI	`az acr login --name myregistry`	Requires Azure CLI and valid credentials
GitHub Container Registry (GHCR)	Personal Access Token	`echo $GITHUB_TOKEN \| docker login ghcr.io -u $GITHUB_USERNAME --password-stdin`	Token must have `read:packages` scope

docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD

Note: Store registry credentials as CircleCI environment variables to avoid exposing them in configuration files.

Warning: Avoid using long-lived credentials; prefer short-lived tokens or role-based access.

7. Using Private Docker Registries

Registry Type	Authentication Method	Configuration Example	Notes
Private Docker Registry	`docker login`	`docker login -u $DOCKER_USER -p $DOCKER_PASS`	Use environment variables for credentials
AWS ECR	AWS CLI credentials	`eval $(aws ecr get-login --region us-east-1 --no-include-email)`	Requires AWS CLI and proper IAM permissions
Google Container Registry (GCR)	Service Account JSON	`gcloud auth activate-service-account --key-file=service-account.json`	Use GCP service account with registry access
Azure Container Registry (ACR)	Azure CLI	`az acr login --name myregistry`	Requires Azure CLI and proper RBAC roles

Example: Using Private Registry in CircleCI Config

version: 2.1
jobs:
  build:
    docker:
      - image: my-private-registry.com/myapp:latest
        auth:
          username: $DOCKER_USER
          password: $DOCKER_PASS
    steps:
      - checkout
      - run: echo "Running build..."

Note: Ensure that the registry credentials are stored as environment variables in CircleCI project settings to avoid exposing them in config files.

8. Setting Container Environment

Environment Variable	Value	Description
CI	`true`	Indicates that the build is running in a CI environment
CIRCLECI	`true`	Flag indicating the build is running on CircleCI
CIRCLE_BUILD_NUM	`12345`	The build number for the current job
CIRCLE_JOB	`build`	The name of the current job
CIRCLE_WORKFLOW_ID	`abc123def456`	Unique identifier for the current workflow
CIRCLE_SHA1	`5f4dcc3b5aa765d61900000000000000`	Git commit SHA of the current build

Example: Setting Custom Environment Variables

version: 2.1
jobs:
  build:
    docker:
      - image: circleci/node:16
    environment:
      NODE_ENV: production
      API_URL: https://api.example.com
      DATABASE_URL: postgres://user:pass@localhost:5432/mydb
    steps:
      - run: echo $NODE_ENV

Note: Environment variables set in the environment block are available to all steps within the job.

Warning: Avoid storing sensitive data like passwords or API keys directly in the config file. Use CircleCI's encrypted environment variables or context features instead.

9. Configuring Docker Entrypoint

Property	Description	Values	Notes
entrypoint	Specifies the entrypoint for the Docker container	`string` or `array`	Can be a string or array of strings. Overrides the default entrypoint from the Docker image.

Example: Setting Docker Entrypoint

jobs:
  build:
    docker:
      - image: circleci/node:16
        entrypoint: ["/bin/bash", "-c"]

10. Using Docker Commands

Command	Description	Example
docker run	Runs a new container from an image	`docker run -it circleci/node:16 bash`
docker build	Builds a Docker image from a Dockerfile	`docker build -t my-app .`
docker exec	Executes a command in a running container	`docker exec -it container-name ls /app`
docker ps	Lists running containers	`docker ps -a`
docker images	Lists Docker images	`docker images`
docker pull	Downloads an image from a registry	`docker pull circleci/postgres:13`

Example: Running a Docker Container in CircleCI

jobs:
  build:
    docker:
      - image: circleci/node:16
        command: bash -c "npm install && npm test"

Example: Building and Using a Custom Docker Image

jobs:
  build:
    docker:
      - image: my-custom-image:latest
        command: /bin/bash -c "echo 'Hello from custom image'"

Note: When using custom Docker images, ensure they are built with the correct base image and dependencies for your CircleCI job.