dslim/docker-slim repository overview

⁠Optimize Your Experience with Containers. Make Your Containers Better, Smaller, More Secure and Do Less to Get There (free and open source!)

DockerSlim⁠ is a tool for developers that provides a set of commands (build, xray, lint and others) to simplify and optimize your developer experience with containers. It makes your containers betters, smaller and more secure.

Don't change anything in your Docker container image and minify it by up to 30x making it secure too! Optimizing images isn't the only thing it can do though. It can also help you understand and author better container images.

Keep doing what you are doing. No need to change anything. Use the base image you want. Use the package manager you want. Don't worry about hand optimizing your Dockerfile. You shouldn't have to throw away your tools and your workflow to have small container images.

Don't worry about manually creating Seccomp and AppArmor security profiles. You shouldn't have to become an expert in Linux syscalls, Seccomp and AppArmor to have secure containers. Even if you do know enough about it wasting time reverse engineering your application behavior can be time-consuming.

docker-slim will optimize and secure your containers by understanding your application and what it needs using various analysis techniques. It will throw away what you don't need, reducing the attack surface of your container. What if you need some of those extra things to debug your container? You can use dedicated debugging side-car containers for that (more details below).

Understand your container image before and after you optimize it using the xray command in docker-slim or the Slim SaaS⁠ where you can get even more powerful insights including how your container image changed.

docker-slim has been used with Node.js, Python, Ruby, Java, Golang, Rust, Elixir and PHP (some app types) running on Ubuntu, Debian, CentOS, Alpine and even Distroless.

Note that some application stacks do require advanced container probing to make sure that all dynamically loaded components are detected. See the --http-probe* flags for more details to know how you can define custom probe commands. In some cases you might also need to use the --include-path flag to make sure everything your application needs is included (e.g., ubuntu.com python SPA app container image example⁠ where the client side template files are explicitly included).

It's also a good idea to use your app/environment tests when you run docker-slim. See the --continue-after flag for more details about integrating your tests with the temporary container docker-slim creates when it's doing its dynamic analysis. Running tests in the target container is also an option, but it does require you to specify a custom ENTRYPOINT/CMD with a custom wrapper to start your app and to execute your tests.

When docker-slim runs it gives you an opportunity to interact with the temporary container it creates. By default, it will pause and wait for your input before it continues its execution. You can change this behavior using the --continue-after flag.

If your application exposes any web interfaces (e.g., when you have a web server or an HTTP API), you'll see the port numbers on the host machine you will need to use to interact with your application (look for the port.list and target.port.info messages on the screen). For example, in the screencast above you'll see that the internal application port 8000 is mapped to port 32911 on your host.

Note that docker-slim will interact with your application for you when HTTP probing is enabled (enabled by default; see the --http-probe* flag docs for more details). Some web applications built with scripting languages like Python or Ruby require service interactions to load everything in the application. Enable HTTP probing unless it gets in your way.

You can also interact with the temporary container via a shell script or snippet using --exec-file or --exec. For example, you can create a container which is only capable of using curl.

>> docker pull archlinux:latest
...

>> docker-slim build --target archlinux:latest --tag archlinux:curl --http-probe=false --exec "curl checkip.amazonaws.com"
...

>> docker run archlinux:curl curl checkip.amazonaws.com
...

>> docker images
archlinux                 curl                ...        ...         17.4MB
archlinux                 latest              ...        ...         467MB
...

Watch this screencast to see how an application image is minified by more than 30x.

⁠Community

Feel free to join any of these channels or just open a new Github issue⁠ if you want to chat or if you need help.

• YouTube channel⁠
• Gitter channel⁠
• Discord server⁠
• Discussions⁠ (new)
• Twitter⁠
• Slack⁠
• Original IRC channel on freenode (not used anymore, but we can start using it again :-): #dockerslim

⁠DockerSlim on the Internet

⁠Books:

• Everyone's Docker/Kubernetes⁠ (Japanese)
• Docker in Practice (2nd edition)⁠
• Docker/Kubernetes Security Practice Guide⁠ (Japanese)

⁠Minification Examples

You can find the examples in a separate repository: https://github.com/docker-slim/examples⁠

Node.js application images:

• from ubuntu:14.04 - 432MB => 14MB (minified by 30.85X)
• from debian:jessie - 406MB => 25.1MB (minified by 16.21X)
• from node:alpine - 66.7MB => 34.7MB (minified by 1.92X)
• from node:distroless - 72.7MB => 39.7MB (minified by 1.83X)

Python application images:

• from ubuntu:14.04 - 438MB => 16.8MB (minified by 25.99X)
• from python:2.7-alpine - 84.3MB => 23.1MB (minified by 3.65X)
• from python:2.7.15 - 916MB => 27.5MB (minified by 33.29X)
• from centos:7 - 647MB => 23MB (minified by 28.57X)
• from centos/python-27-centos7 - 700MB => 24MB (minified by 29.01X)
• from python2.7:distroless - 60.7MB => 18.3MB (minified by 3.32X)

Ruby application images:

• from ubuntu:14.04 - 433MB => 13.8MB (minified by 31.31X)
• from ruby:2.2-alpine - 319MB => 27MB (minified by 11.88X)
• from ruby:2.5.3 - 978MB => 30MB (minified by 32.74X)

Golang application images:

• from golang:latest - 700MB => 1.56MB (minified by 448.76X)
• from ubuntu:14.04 - 531MB => 1.87MB (minified by 284.10X)
• from golang:alpine - 258MB => 1.56MB (minified by 165.61X)
• from centos:7 - 615MB => 1.87MB (minified by 329.14X)

Rust application images:

• from rust:1.31 - 2GB => 14MB (minified by 147.16X)

JAVA application images:

• from ubuntu:14.04 - 743.6 MB => 100.3 MB

PHP application images:

• from php:7.0-cli - 368MB => 26.6MB (minified by 13.85X)

Haskell application images:

• (Scotty service) from haskell:8 - 2.09GB => 16.6MB (minified by 125.32X)
• (Scotty service) from haskell:7 - 1.5GB => 21MB (minified by 71X)

⁠RECENT UPDATES

Latest version: 1.37.6 (4/24/2022)

The 1.37.x releases add an experimental docker-compose support and various improved application tracing capabilities for the build command.

For more info about the latest release see the CHANGELOG⁠.

⁠INSTALLATION

If you already have docker-slim installed use the update command to get the latest version:

docker-slim update

⁠Docker

docker pull dslim/docker-slim

See the RUNNING CONTAINERIZED⁠ section for more usage info.

⁠SaaS

Powered by DockerSlim. It will help you understand and troubleshoot your application containers and a lot more. If you use the xray command you'll want to try the SaaS. Understanding image changes is easy with its container diff capabilities. Connect your own registry and you can do the same with your own containers. Try it here⁠ without installing anything locally.

⁠BASIC USAGE INFO

docker-slim [global flags] [lint|xray|build|profile|update|version|help] [command-specific flags] <IMAGE_ID_OR_NAME>

If you don't specify any command docker-slim will start in the interactive prompt mode.

⁠COMMANDS

• build - Analyzes, profiles and optimizes your container image generating the supported security profiles. This is the most popular command.
• xray - Performs static analysis for the target container image (including 'reverse engineering' the Dockerfile for the image). Use this command if you want to know what's inside of your container image and what makes it fat.
• lint - Analyzes container instructions in Dockerfiles (Docker image support is WIP)
• profile - Performs basic container image analysis and dynamic container analysis, but it doesn't generate an optimized image.
• run - Runs one or more containers (for now runs a single container similar to docker run)
• version - Shows the version information.
• update - Updates docker-slim to the latest version.
• help - Show the available commands and global flags

Example: docker-slim build my/sample-app

See the USAGE DETAILS section for more details. You can also get additional information about the parameters running docker-slim.

Run docker-slim help to get a high level overview of the available commands. Run a docker-slim command without any parameters and you'll get more information about that command (e.g., docker-slim build).

If you run docker-slim without any parameters you'll get an interactive prompt that will provide suggestions about the available commands and flags. Tabs are used to show the available options, to autocomplete the parameters and to navigate the option menu (which you can also do with Up and Down arrows). Spaces are used to move to the next parameter and Enter is used to run the command. For more info about the interactive prompt see go-prompt⁠.

⁠USAGE DETAILS

docker-slim [global options] command [command options] <target image ID or name>

⁠RUNNING CONTAINERIZED

The current version of docker-slim is able to run in containers. It will try to detect if it's running in a containerized environment, but you can also tell docker-slim explicitly using the --in-container global flag.

You can run docker-slim in your container directly or you can use the docker-slim container in your containerized environment. If you are using the docker-slim container make sure you run it configured with the Docker IPC information, so it can communicate with the Docker daemon. The most common way to do it is by mounting the Docker unix socket to the docker-slim container. Some containerized environments (like Gitlab and their dind service) might not expose the Docker unix socket to you, so you'll need to make sure the environment variables used to communicate with Docker (e.g., DOCKER_HOST) are passed to the docker-slim container. Note that if those environment variables reference any kind of local host names those names need to be replaced or you need to tell docker-slim about them using the --etc-hosts-map flag. If those environment variables reference local files those local files (e.g., files for TLS cert validation) will need to be copied to a temporary container, so that temporary container can be used as a data container to make those files accessible by the docker-slim container.

When docker-slim runs in a container it will attempt to save its execution state in a separate Docker volume. If the volume doesn't exist it will try to create it (docker-slim-state, by default). You can pick a different state volume or disable this behavior completely by using the global --archive-state flag. If you do want to persist the docker-slim execution state (which includes the seccomp and AppArmor profiles) without using the state archiving feature you can mount your own volume that maps to the /bin/.docker-slim-state directory in the docker-slim container.

By default, docker-slim will try to create a Docker volume for its sensor unless one already exists. If this behavior is not supported by your containerized environment you can create a volume separately and pass its name to docker-slim using the --use-sensor-volume flag.

Here's a basic example of how to use the containerized version of docker-slim: docker run -it --rm -v /var/run/docker.sock:/var/run/docker.sock dslim/docker-slim build your-docker-image-name

Here's a GitLab example for their dind .gitlab-ci.yml config file: docker run -e DOCKER_HOST=tcp://$(grep docker /etc/hosts | cut -f1):2375 dslim/docker-slim build your-docker-image-name

Here's a CircleCI example for their remote docker .circleci/config.yml config file (used after the setup_remote_docker step):

docker create -v /dcert_path --name dcert alpine:latest /bin/true
docker cp $DOCKER_CERT_PATH/. dcert:/dcert_path
docker run --volumes-from dcert -e DOCKER_HOST=$DOCKER_HOST -e DOCKER_TLS_VERIFY=$DOCKER_TLS_VERIFY -e DOCKER_CERT_PATH=/dcert_path dslim/docker-slim build your-docker-image-name