undocker/README.md

124 lines
3.7 KiB
Markdown
Raw Normal View History

2021-05-31 23:15:54 +03:00
[![godocs.io](http://godocs.io/git.sr.ht/~motiejus/undocker?status.svg)](http://godocs.io/git.sr.ht/~motiejus/undocker)
2021-05-31 23:45:04 +03:00
[![builds.sr.ht status](https://builds.sr.ht/~motiejus/undocker.svg)](https://builds.sr.ht/~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
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-26 10:40:53 +03:00
Undocker has no dependencies outside Golang stdlib.
2021-05-24 09:40:21 +03:00
Installation
------------
We recommend using [officially released binaries][3]. To build the project
instead, run:
```
$ make undocker
```
The number of officially released binaries is quite limited. If you'd like me
to expand a list, please contribute a patch to the Makefile.
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 -tv | head -10
drwxr-xr-x 0/0 0 2021-05-17 22:07 bin/
-rwxr-xr-x 0/0 1149184 2021-05-17 22:07 bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/[[ link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/acpid link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/add-shell link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/addgroup link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/adduser link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/adjtimex link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/ar link to bin/[
hrwxr-xr-x 0/0 0 2021-05-17 22:07 bin/arch link to bin/[
2021-05-24 00:11:58 +03:00
```
2021-05-24 09:40:21 +03:00
You can also refer [here][2] for other ways to download Docker images. There
2021-05-24 00:11:58 +03:00
are many.
2021-05-24 00:11:58 +03:00
2021-05-26 10:40:53 +03:00
Converting a [1.1GB Docker image with 77
2021-05-26 10:41:30 +03:00
layers](https://hub.docker.com/r/homeassistant/home-assistant) takes around 4
2021-05-26 10:40:53 +03:00
seconds and on a reasonably powerful Intel laptop.
2021-05-24 09:40:21 +03:00
Usage example: systemd-nspawn
-----------------------------
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
Start with systemd-nspawn:
2021-05-24 00:11:58 +03:00
2021-05-24 00:11:58 +03:00
```
2021-05-24 00:11:58 +03:00
systemd-nspawn -D $PWD busybox httpd -vfp 8080
2021-05-24 00:11:58 +03:00
```
2021-05-24 09:40:21 +03:00
Usage example: plain old 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 PrivateUsers=true \
-p DynamicUser=yes \
-p ProtectProc=invisible \
-p RootDirectory=$PWD \
-- busybox httpd -vfp 8080
2021-05-24 00:11:58 +03:00
```
2021-05-24 00:11:58 +03:00
Good things like `PrivateUsers`, `DynamicUser`, `ProtectProc` and other
[systemd protections][1] 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
Changelog
---------
2021-08-24 07:02:12 +03:00
**v1.0**
2021-05-24 00:11:58 +03:00
* initial release: `rootfs.Flatten` and a simple command-line application.
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
2021-05-24 09:40:21 +03:00
- Pull requests (patchsets) with accompanying tests.
- 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
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/
[3]: http://git.sr.ht/~motiejus/undocker