undocker/README.md

121 lines
3.1 KiB
Markdown
Raw Normal View History

2023-04-13 11:30:37 +03:00
[![godocs.io](http://godocs.io/git.jakstys.lt/motiejus/undocker?status.svg)](http://godocs.io/git.jakstys.lt/motiejus/undocker)
2021-05-31 21:46:49 +03:00
2021-05-24 00:11:58 +03:00
Undocker
--------
2021-05-24 00:11:58 +03:00
Converts a Docker image (a bunch of layers) to a flattened "rootfs" tarball.
2021-05-24 00:11:58 +03:00
2024-02-09 10:49:27 +02:00
Project Status
--------------
The project was announced to be deprecated in the beginning of 2024, but the
maintainer has an interest in Docker ecosystem again, thus will maintain it
somewhat starting at mid-2024.
The author has some significant changes in mind, but the timeline is unknown.
2024-02-09 10:49:27 +02:00
2021-05-24 00:11:58 +03:00
Why?
2021-05-24 00:11:58 +03:00
----
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
Docker images became a popular way to distribute applications with their
2021-05-24 09:40:21 +03:00
dependencies; however, Docker is not the best runtime environment. At least not
for everyone. May boring technology run our software.
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
Undocker bridges the gap between application images (in docker image format)
2021-05-24 09:40:21 +03:00
and application isolation ("container") runtimes: once the docker image is
extracted, it can be run with old-fashioned tools: lxc, systemd-nspawn,
systemd, FreeBSD Jails, and many others.
2021-05-24 00:11:58 +03:00
2021-05-24 09:40:21 +03:00
Installation
------------
Build it like this for the "current" platform:
```
$ make undocker
```
`make -B` will print the extra flags (`-X <...>`) for cross-compiling with
other archs. It's all `go build <...>` in the back, and depends only on Go's
compiler and stdlib.
2021-05-24 09:40:21 +03:00
Usage: convert docker image to rootfs
-------------------------------------
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
Download `busybox` docker image from docker hub and convert it to a rootfs:
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
```
2021-05-24 09:40:21 +03:00
$ skopeo copy docker://docker.io/busybox:latest docker-archive:busybox.tar
$ undocker busybox.tar - | tar -xv | sponge | head -10; echo '<...>'
bin/
bin/[
bin/[[
bin/acpid
bin/add-shell
bin/addgroup
bin/adduser
bin/adjtimex
bin/ar
bin/arch
<...>
2021-05-24 00:11:58 +03:00
```
Refer [here][2] for other ways to download Docker images. There are many.
2021-05-24 00:11:58 +03:00
On author's laptop converting a [1.1GB Docker image with 77
layers](https://hub.docker.com/r/homeassistant/home-assistant) takes around 3
seconds and uses ~65MB of residential memory.
2021-05-26 10:40:53 +03:00
Usage example: systemd
----------------------
2021-05-24 00:11:58 +03:00
```
2021-05-24 00:11:58 +03:00
systemd-run \
--wait --pty --collect --service-type=exec \
-p RootDirectory=$PWD \
-p ProtectProc=invisible \
2021-05-24 00:11:58 +03:00
-p PrivateUsers=true \
-p DynamicUser=yes \
-- busybox httpd -vfp 8080
2021-05-24 00:11:58 +03:00
```
[Systemd protections][1] like `PrivateUsers`, `DynamicUser`, `ProtectProc` and
others are available, just like to any systemd unit.
2021-05-24 00:11:58 +03:00
2021-05-24 07:39:40 +03:00
Similar Projects
----------------
* [rootfs_builder](https://github.com/ForAllSecure/rootfs_builder)
2021-05-24 00:11:58 +03:00
Contributions
-------------
2021-05-24 00:11:58 +03:00
2021-05-24 09:40:21 +03:00
The following contributions may be accepted:
2021-05-24 00:11:58 +03:00
- Patchsets, with accompanying tests.
2021-05-24 09:40:21 +03:00
- Regression reports.
2021-05-24 00:11:58 +03:00
2021-05-24 09:40:21 +03:00
If you found a container that undocker cannot extract, or extracts incorrectly
and you need this that work with undocker, do not submit an issue: submit a
patchset.
2021-05-24 00:11:58 +03:00
2021-05-24 09:40:21 +03:00
Reports of regression reports must provide examples of "works before" and "does
not work after". Issues without an accompanying patch will most likely be
rejected.
2021-05-24 00:11:58 +03:00
Communication
-------------
2023-04-13 11:30:37 +03:00
Feel free to ping me [directly][motiejus-comms].
2021-05-24 00:11:58 +03:00
LICENSE
-------
2021-05-24 07:39:40 +03:00
MIT
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
[1]: https://www.freedesktop.org/software/systemd/man/systemd.exec.html
2021-05-24 00:11:58 +03:00
[2]: https://fly.io/blog/docker-without-docker/
2023-04-13 11:30:37 +03:00
[motiejus-comms]: https://jakstys.lt/contact/