Dockerize

A Docker-in-Docker (DinD) setup for building and pushing Docker images to a container registry using Docker Compose. This tool is designed to be integrated into existing projects to provide containerized Docker builds.

Overview

Dockerize provides a containerized environment for building Docker images without requiring Docker to be installed on the host machine. It uses Docker-in-Docker (DinD) to create an isolated Docker daemon and a separate builder container to perform build and push operations.

This is not a standalone project - it's a build tool that should be integrated into your existing project to build and push your application's Docker images.

Architecture

• dind: Docker-in-Docker daemon container that runs the Docker daemon
• builder: Docker CLI container that connects to the dind daemon to build and push images

This tool integrates with your project's existing Dockerfile and builds/pushes your application image to the specified registry.

Prerequisites

• Docker and Docker Compose installed on your host machine
• An existing project with a Dockerfile
• Access to a Docker registry (e.g., git.mnco.dev, Docker Hub, etc.)
• Registry credentials (username and token/password)

Setup

1. Integrate into your existing project:

   # Add dockerize files to your project root
   # Copy the following files to your project:
   # - dockerize.yml (rename from docker-compose.yaml)
   # - .env.example -> .env.dockerize
   # - docker-daemon.json (optional)

2. Create environment configuration:

   cp .env.example .env.dockerize

3. Configure your environment variables in .env.dockerize:

   USER=your-registry-username
   TOKEN=your-registry-token
   REGISTRY=your-registry-host  # e.g., docker.io
   IMAGE=your-repo/image-name   # e.g., organization/project
   TAG=your-tag                 # e.g., latest, v1.0.0

4. Ensure your project has a Dockerfile: Make sure your project has a Dockerfile in the root directory. The dockerize tool will use this Dockerfile to build your application image.

5. Configure Docker daemon (optional): The included docker-daemon.json file provides optimized settings for the Docker daemon.

Usage

Build and Push Your Application Image

To build and push your application's Docker image to the registry:

docker compose -f dockerize.yml up

This command will:

1. Start the DinD daemon and wait for it to be ready
2. Log in to your configured registry
3. Build your application's Docker image using your project's Dockerfile
4. Export the image as an OCI tar file
5. Import and push the image to the registry using regctl
6. Clean up temporary files

Run Individual Services

Start only the DinD daemon:

docker compose -f dockerize.yml up dind

Run the builder separately:

docker compose -f dockerize.yml up builder

Cleanup

Stop all services:

docker compose -f dockerize.yml down

Remove volumes (will clear build cache):

docker compose -f dockerize.yml down -v

Configuration

Environment Variables

Variable	Description	Example
USER	Registry username	myuser
TOKEN	Registry token/password	ghp_xxxxxxxxxxxx
DOCKER_HOST	Docker daemon endpoint	tcp://dind:2375
DOCKER_BUILDKIT	Enable BuildKit	1
REGISTRY	Registry hostname	docker.io.
IMAGE	Image repository/name	tyou0/dockerize
TAG	Image tag	latest
BLOB_CHUNK	Chunk size for large images (default: 5MB)	5242880
BLOB_MAX	Max blob size before splitting (default: 100MB)	104857600

Docker Daemon Configuration

The docker-daemon.json file allows you to configure the Docker daemon. Common configurations include:

{
  "max-concurrent-uploads": 3,
  "max-concurrent-downloads": 3,
  "storage-driver": "overlay2",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Cloudflare Tunnel Registry Settings

For Docker registries hosted through Cloudflare Tunnel with size limitations (100MB limit), the dockerize tool automatically splits large images into chunks:

• BLOB_CHUNK: Size of each chunk when splitting large images (default: 5MB)
• BLOB_MAX: Maximum blob size before splitting (default: 100MB)

These settings are particularly useful when pushing images to a Docker registry hosted through Cloudflare Tunnel, which has a 100MB limit per blob. When an image layer exceeds this limit, it will be automatically split into 5MB chunks.

To configure these settings, add them to your .env.dockerize file:

# Cloudflare Tunnel registry settings (for images > 100MB)
BLOB_CHUNK=5242880    # 5MB chunks
BLOB_MAX=104857600    # 100MB max (Cloudflare Tunnel limit)

If not specified, the default values will be used.

Dockerfile Requirements

Your project's Dockerfile can be any valid Dockerfile. The dockerize tool will build whatever is defined in your Dockerfile.

Example Dockerfile structure:

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

Note: If you use multi-stage builds, the dockerize tool will build the final stage by default. You can specify a target stage by modifying the build command in dockerize.yml.

Troubleshooting

Common Issues

1. DinD daemon not starting:

   • Check if Docker is running on the host
   • Ensure the container has privileged access
   • Check logs: docker compose -f dockerize.yml logs dind

2. Registry login fails:

   • Verify your credentials in .env.dockerize
   • Check if the registry URL is correct
   • Ensure your token has push permissions

3. Build fails:

   • Check if your project has a valid Dockerfile
   • Verify the build context (current directory)
   • Check logs: docker compose -f dockerize.yml logs builder

4. Push fails:

   • Verify registry permissions
   • Check network connectivity
   • Ensure the image name follows registry naming conventions

Debug Mode

To run with more verbose output:

docker compose -f dockerize.yml up --build --no-deps builder

Security Considerations

• The DinD container runs with privileged access
• Environment files contain sensitive credentials
• Ensure .env.dockerize is not committed to version control
• Use secure tokens with minimal required permissions
• Consider using Docker secrets for production deployments

Development

Integration into Existing Projects

To integrate dockerize into your existing project:

1. Copy the dockerize files to your project root:

   • dockerize.yml (Docker Compose configuration)
   • .env.example (Environment template)
   • docker-daemon.json (Docker daemon config)

2. Create your environment file:

   cp .env.example .env.dockerize
   # Edit .env.dockerize with your registry credentials

3. Build and push your application:

   docker compose -f dockerize.yml up

Local Development

For local development and testing:

1. Use a test registry or local registry
2. Set TAG=dev or TAG=test in your .env.dockerize
3. Use shorter-lived tokens when possible

CI/CD Integration

This setup can be integrated into CI/CD pipelines:

# Example GitHub Actions workflow
- name: Build and Push Docker Image
  env:
    USER: ${{ secrets.REGISTRY_USER }}
    TOKEN: ${{ secrets.REGISTRY_TOKEN }}
    TAG: ${{ github.sha }}
  run: |
    echo "USER=$USER" > .env.dockerize
    echo "TOKEN=$TOKEN" >> .env.dockerize
    echo "TAG=$TAG" >> .env.dockerize
    docker compose -f dockerize.yml up --build

License

[Add your license information here]

Contributing

[Add contribution guidelines here]