docker-builder

Build and host your own Docker images locally, without relying on an upstream registry.

Images are built for amd64 and arm64 (multi-arch) and tagged with a date-based tag (YYYYMMDD), then pushed to a local Docker Registry v2 running on localhost:5000.

---

Prerequisites

• Docker with Buildx support (included in Docker Desktop and Docker Engine ≥ 19.03)
• Docker Compose v2+
• make, curl, python3 (for the list target)

---

Project Structure

docker-builder/
├── Makefile                   ← build entrypoint
├── docker-compose.yml         ← local registry
├── .env                       ← configuration
├── images/
│   └── debian-base/
│       └── Dockerfile
└── README.md

---

Configuration

Edit .env to change defaults:

REGISTRY=localhost:5000       # local registry address
BUILDX_BUILDER=multiarch      # buildx builder name

---

Quick Start

1. Start the local registry

make registry-up

This starts a Docker Registry v2 container at http://localhost:5000. Image data is persisted in a Docker named volume (registry-data).

2. Configure Docker to allow the insecure local registry

Add localhost:5000 to your Docker daemon's insecure registries.

Linux (/etc/docker/daemon.json):

{
  "insecure-registries": ["localhost:5000"]
}

Then restart Docker: sudo systemctl restart docker

Docker Desktop (Mac/Windows): go to Settings → Docker Engine and add the same JSON snippet.

3. Build an image

make build IMAGE=debian-base

This builds images/debian-base/Dockerfile for both linux/amd64 and linux/arm64, tags it as:

• localhost:5000/debian-base:YYYYMMDD
• localhost:5000/debian-base:latest

and pushes it directly to the local registry.

4. Build all images

make all

5. List images in the registry

make list

6. Pull an image from the local registry

docker pull localhost:5000/debian-base:latest

---

Adding a New Image

1. Create a new directory under images/:

   mkdir images/my-new-image

2. Add a Dockerfile inside it.
3. Build it:

   make build IMAGE=my-new-image

The make all target automatically discovers all directories under images/.

---

Stopping the Registry

make registry-down

Image data is preserved in the registry-data volume. To also remove the data:

docker compose down -v

---

Using the Local Registry in Other Projects

Same machine

In any docker-compose.yml, prefix the image name with localhost:5000:

services:
  myapp:
    image: localhost:5000/debian-base:latest
    pull_policy: always

Tip: pull_policy: always ensures Docker checks the local registry for updates on every docker compose up.

Different machine on the same network

Replace localhost with the builder machine's IP address:

services:
  myapp:
    image: 192.168.1.100:5000/debian-base:latest

On the consuming machine, also add the remote address to insecure registries:

Linux (/etc/docker/daemon.json):

{
  "insecure-registries": ["192.168.1.100:5000"]
}

Then restart Docker: sudo systemctl restart docker

Docker Desktop (Mac/Windows): go to Settings → Docker Engine and add the same snippet.

---

Deploying an Image Built on Another Machine

If you built an image elsewhere and want to push it into this local registry:

1. One-time setup on the other machine

Add the registry to insecure registries in /etc/docker/daemon.json:

{
  "insecure-registries": ["192.168.1.100:5000"]
}

Then restart Docker: sudo systemctl restart docker

Replace 192.168.1.100 with your registry machine's actual IP (hostname -I to find it).

2. Tag and push

# Retag your local image to point at the registry
docker tag my-image:latest 192.168.1.100:5000/my-image:latest

# Push it
docker push 192.168.1.100:5000/my-image:latest

Or use the import Makefile target from the other machine:

make import IMAGE=my-image TAG=latest REGISTRY=192.168.1.100:5000

3. Verify it arrived (on the registry machine)

make list

---

All Makefile Targets

Target	Description
registry-up	Start the local Docker registry
registry-down	Stop the local Docker registry
buildx-setup	Create the multi-arch buildx builder
build IMAGE=<name>	Build + push a single image
push IMAGE=<name>	Push a pre-built image to local registry
import IMAGE=<name> TAG=<tag>	Retag a local image and push to registry
all	Build + push all images
list	List all repositories in the registry