This is my Docker reference: how to build an image (with a Dockerfile or docker commit), move it to another machine (docker save / docker load), host it on your own private registry, and find where Docker keeps images on disk. The short version: build with a multi-stage Dockerfile, ship images with docker save | docker load or a registry, and run docker info to see where they live (usually /var/lib/docker on Linux).
Hi there! This is yet another note from me ^^ I’ve been working with container technologies for years, and it’s a good habit to dump my notes here. These were first written in March 2018 and have been refreshed for current Docker. I hope you find them useful as well.
Build a Docker image
Method 1: docker build with a Dockerfile
A Dockerfile is the standard, reproducible way to build an image. In it you define:
- the base image to start from,
- the files to copy in,
- the configuration steps to run,
- the process to start.
You know I like using Django for projects. Here is a multi-stage Dockerfile based on a Cookiecutter Django local setup. The first stage builds Python wheels. The second stage installs those wheels, so the build tools never land in the final image.
# define an alias for the specific python version used in this file.FROM python:3.11.6-slim-bullseye AS python
# Python build stageFROM python AS python-build-stage
ARG BUILD_ENVIRONMENT=local
# Install apt packagesRUN apt-get update && apt-get install --no-install-recommends -y \ # dependencies for building Python packages build-essential \ # psycopg2 dependencies libpq-dev
# Requirements are installed here to ensure they will be cached.COPY ./requirements .
# Create Python Dependency and Sub-Dependency Wheels.RUN pip wheel --wheel-dir /usr/src/app/wheels \ -r ${BUILD_ENVIRONMENT}.txt
# Python 'run' stageFROM python AS python-run-stage
ARG BUILD_ENVIRONMENT=localARG APP_HOME=/app
ENV PYTHONUNBUFFERED=1ENV PYTHONDONTWRITEBYTECODE=1ENV BUILD_ENV=${BUILD_ENVIRONMENT}
WORKDIR ${APP_HOME}
# devcontainer dependencies and utilsRUN apt-get update && apt-get install --no-install-recommends -y \ sudo git bash-completion ssh vimRUN echo "alias ls='ls --color=auto'" >> ~/.bashrcRUN echo "alias ll='ls -lh --color=auto'" >> ~/.bashrc
# Create devcontainer user and add it to sudoersRUN groupadd --gid 1000 dev-user \ && useradd --uid 1000 --gid dev-user --shell /bin/bash --create-home dev-user \ && echo dev-user ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/dev-user \ && chmod 0440 /etc/sudoers.d/dev-user
# Install required system dependenciesRUN apt-get update && apt-get install --no-install-recommends -y \ # psycopg2 dependencies libpq-dev \ # Translations dependencies gettext \ # cleaning up unused files && apt-get purge -y --auto-remove -o APT::AutoRemove::RecommendsImportant=false \ && rm -rf /var/lib/apt/lists/*
# All absolute dir copies ignore workdir instruction. All relative dir copies are wrt to the workdir instruction# copy python dependency wheels from python-build-stageCOPY --from=python-build-stage /usr/src/app/wheels /wheels/
# use wheels to install python dependenciesRUN pip install --no-cache-dir --no-index --find-links=/wheels/ /wheels/* \ && rm -rf /wheels/
COPY ./compose/production/django/entrypoint /entrypointRUN sed -i 's/\r$//g' /entrypointRUN chmod +x /entrypoint
COPY ./compose/local/django/start /startRUN sed -i 's/\r$//g' /startRUN chmod +x /start
COPY ./compose/local/django/celery/worker/start /start-celeryworkerRUN sed -i 's/\r$//g' /start-celeryworkerRUN chmod +x /start-celeryworker
COPY ./compose/local/django/celery/beat/start /start-celerybeatRUN sed -i 's/\r$//g' /start-celerybeatRUN chmod +x /start-celerybeat
COPY ./compose/local/django/celery/flower/start /start-flowerRUN sed -i 's/\r$//g' /start-flowerRUN chmod +x /start-flower
# copy application code to WORKDIRCOPY . ${APP_HOME}
ENTRYPOINT ["/entrypoint"]Build and tag it from the project root:
docker build -t myproject/django:dev .The sed -i 's/\r$//g' lines strip Windows line endings from the start scripts. Without them, a script saved on Windows fails inside the Linux container.
Method 2: docker commit
The other way is to turn a running (or stopped) container into an image:
docker commit <container_id> <new_image_name>:<tag>This takes the container’s current filesystem changes, on top of the image it was started from, and saves them as a new image in your local Docker storage. It’s handy for quick experiments. It isn’t reproducible, though: nobody can see how the image was made. For anything you’ll keep, write a Dockerfile.
Move images between machines: save/load vs export/import
Once you have an image, you’ll often want to share it or copy it to a machine without registry access. Docker has two pairs of commands for this, and they are not the same.
docker save / docker load works on images and keeps layers, tags and history:
docker save <image_name:version> > exported_file.tardocker load < exported_file.tarCompress it, or stream it straight to another host over SSH:
docker save <image_name:version> | gzip > exported_file.tar.gzdocker load < exported_file.tar.gz
docker save <image_name:version> | ssh user@other-host docker loaddocker export / docker import works on a container’s filesystem and produces a single flattened image:
docker export <container_id> > container_fs.tardocker import container_fs.tar <new_image_name>:<tag>docker save / docker load | docker export / docker import | |
|---|---|---|
| Works on | Images | Containers |
| Layers and history | Kept | Flattened into one layer |
| Tags | Kept | You set a new name on import |
| Image config (CMD, ENTRYPOINT, ENV) | Kept | Lost (can be re-added with docker import -c) |
| Typical use | Copying an image to an offline machine | Snapshotting a container’s filesystem |
Run a private Docker registry
My original 2018 notes installed the old docker-registry package from Docker’s yum repo on CentOS 7.2. That package, that repo and the v1 registry API are all retired. Today the simple way is to run the official registry image as a container.
Start the registry
docker run -d \ -p 5000:5000 \ --restart=always \ --name registry \ -v /data/docker/registry:/var/lib/registry \ registry:2The -v mount plays the role of the old storage_path setting. Pushed images are stored under /data/docker/registry on the host, so they survive a container restart or upgrade.
Verify the registry
curl http://localhost:5000/v2/_catalogOn a fresh registry you should get:
{"repositories":[]}You can also check the container with docker ps --filter name=registry and docker logs registry.
Set up clients to use the registry
Docker treats localhost:5000 as trusted out of the box. Other machines reaching the registry over plain HTTP must list it as an insecure registry. Add it to /etc/docker/daemon.json, merging with any settings already there:
{ "insecure-registries": ["your_ip_or_hostname:5000"]}Then restart Docker:
sudo systemctl restart dockerAn insecure registry is only suitable for a lab or a trusted internal network. For anything else, put TLS and authentication in front of it.
Push to the registry
First get an image to push, for example from Docker Hub:
docker pull alpineIf you push a name that doesn’t exist locally yet, you get an error:
# docker push your_ip_or_hostname:5000/ciThe push refers to a repository [your_ip_or_hostname:5000/ci]An image does not exist locally with the tag: your_ip_or_hostname:5000/ciThe image name has to include the registry address. So tag the image with your registry’s address first, then push:
docker tag alpine your_ip_or_hostname:5000/alpinedocker push your_ip_or_hostname:5000/alpineCheck that it arrived, then pull it from any configured client:
curl http://your_ip_or_hostname:5000/v2/_catalogdocker pull your_ip_or_hostname:5000/alpineDocker storage
Where does Docker store images?
On Linux it’s usually /var/lib/docker/. The exact layout inside depends on the storage driver Docker uses. Ask Docker directly instead of guessing:
docker info --format '{{.DockerRootDir}}' # root directory, e.g. /var/lib/dockerdocker info --format '{{.Driver}}' # storage driver, e.g. overlay2docker system df # space used by images, containers, volumes| Setup | Where images live |
|---|---|
| Docker Engine on Linux | /var/lib/docker/ by default. With the overlay2 driver, layer contents are under /var/lib/docker/overlay2/ |
| Docker Desktop (macOS, Windows) | Inside the Linux VM that Docker Desktop runs, stored as a disk image file, not directly on your host filesystem |
To move Docker’s data to another disk, set data-root in /etc/docker/daemon.json and restart Docker. To pick a storage driver, use the storage-driver key in the same file, or the --storage-driver daemon option.
{ "data-root": "/data/docker", "storage-driver": "overlay2"}Older Docker versions used drivers like aufs, with layer contents in /var/lib/docker/aufs/diff/<id> and metadata in /var/lib/docker/graph/<id>. That layout is legacy. You’ll only see it on old hosts.
Don’t edit files under /var/lib/docker by hand. Use docker rmi, docker image prune and docker system prune to clean up.
Cheat sheet
| Command | What it does |
|---|---|
docker version | Client and server versions |
docker info | Daemon details: storage driver, root dir, registries |
docker images | List local images |
docker ps -a | List containers, including stopped ones |
docker rmi <image> | Remove an image |
docker run -it ubuntu bash | Start an interactive container |
docker run -d ubuntu /bin/sh -c "while true; do echo hello world; sleep 1; done" | Start a detached container |
docker exec -it <container> bash | Open a shell in a running container |
docker stop <container> | Stop a container |
docker inspect <container or image> | Show full JSON details |
docker tag <source_image> <target_image> | Add a new name/tag to an image |
docker logs -f <container> | Follow a container’s logs |
docker system df | Disk usage summary |
docker image prune | Remove dangling images |
FAQ
What’s the difference between docker save and docker export?
docker save exports an image with all its layers, tags and config, and you restore it with docker load. docker export dumps a container’s filesystem as one flat tarball, and docker import turns that into a new single-layer image without the original history or config.
Should I use docker commit or a Dockerfile?
Use a Dockerfile for anything you’ll rebuild, share or deploy, because it records exactly how the image is built. docker commit is fine for a quick snapshot while experimenting.
Why does docker push say “An image does not exist locally with the tag”?
The image name must include the registry address. Run docker tag <image> your_ip_or_hostname:5000/<name> first, then push that exact name.
How do I see which images are in my private registry?
Query the registry API: curl http://your_ip_or_hostname:5000/v2/_catalog lists repositories, and curl http://your_ip_or_hostname:5000/v2/<name>/tags/list lists the tags for one repository.
Where are Docker images stored on a Mac?
With Docker Desktop, images live inside the Linux VM’s disk image, not in a normal folder on macOS. Use docker system df to see how much space they take and docker image prune to free it.
Okay, that’s all from me. Thanks for reading! Questions or corrections are welcome via the contact page.