podenv: a container wrapper

Note that this is a work in progress, please get in touch if you are interested.

Podenv provides a declarative interface to manage containerized applications. Using rootless containers, podenv let you run applications seamlessly.

Overview and scope

The goal of podenv is to implement a modern application launcher:

• Highlevel capability system
• Multiple runtimes
• VPN network namespace
• Functional configuration
• Simple to use

Podenv differs from toolbx or flatpak:

• Isolation by default: network or home directory access need to be explicitely enabled.
• Unopinionated runtime: applications are provided by distro packages or Containerfile.
• High level command line interface.

Features

Capabilities

Share resources with simple toggles:

• --wayland graphical display.
• --pipewire access audio and video streams.
• --dbus share the dbus session.
• See the full list in this configuration schema: Capabilities.Type

Mount directories with smart volumes:

• --volume ~ share the home directory.
• --volume web:~ use a volume named web for the container home.
• --hostfile ./document.pdf share a single file.

Runtimes

Podenv works with multiple runtimes:

• Podman for container image and Containerfile.
• Bubblewrap for local rootfs and Nix Flakes. Checkout the Howto use Nix tutorial.

The runtime integration is decoupled from the application description so that more options can be added in the future.

Namespace

Applications can share resources using the --namespace NAME option. For example, a browser application can be attached to the network of a VPN application. Checkout the Configure a VPN howto.

Configuration

Applications are user-defined with functionnal and re-usable expressions:

Firefox with a fedora container

Application::{
, name = "firefox"
, description = Some "Mozilla Firefox"
, runtime = (./fedora.dhall).latest.useGraphic [ "firefox" ]
, command = [ "firefox", "--no-remote" ]
, capabilities = Capabilities::{ wayland = True, network = True }
}

The fedora useGraphic function defines a custom Containerfile:

\(pkgs : List Text) ->
ContainerBuild::{
, containerfile =
    ''
    FROM fedora:latest
    RUN ${./mkUser.dhall "fedora"}
    RUN dnf install -y mesa-dri-drivers pipewire-libs
    RUN dnf update -y
    RUN dnf install -y ${concatSep " " pkgs}
    ''
, image_home = Some "/home/fedora"
, image_update = Some "dnf update -y"
}

The graphic packages layer is shared by the other apps.

Nix Flakes

Podenv support the Nix installables syntax:

Application::{
, name = "polyglot"
, description = Some "Tool to count lines of source code."
, runtime = Nix Flakes::{ installables = [ "github:podenv/polyglot.nix" ]}
, capabilities = Capabilities::{ cwd = True }
}

Hub

By default, podenv uses the podenv/hub collection. Run podenv --list to see the available applications.

Usage

Podenv provides a simple command line: podenv [--caps] application-name [args].

Here are some common use cases:

Applications

$ podenv gimp ./image.png

… runs the following command: podman run [wayland args] --volume $(pwd)/image.png:/data/image.png localhost/gimp /data/image.png

If necessary, podenv builds a local image using the Containerfile defined by the application.

Container image

$ podenv --rw --network --root --cwd --shell image:ubi8

… runs the following command: podman run --rm -it --detach-keys '' --volume $(pwd):/data:Z --workdir /data --volume ~/.local/share/podenv/volumes/image-ubi8-home:/root ubi8 /bin/bash

By default podenv mounts a local volumes for the home directory.

Bubblewrap chroot

Extract a container image and execute it with bubblewrap:

$ podenv --volume rawhide:/mnt image:fedora:rawhide bash -c "tar --one-file-system -cf - / | tar -C /mnt -xf -"
$ podenv --network --rw --root rootfs:rawhide

… extracts the rootfs with: podman run --rm --read-only=true --network none --volume ~/.local/share/podenv/volumes/rawhide:/mnt fedora:rawhide bash -c "tar ..."

… and, runs the following command: bwrap [unshare args] --bind ~/.local/share/podenv/volumes/rawhide / --bind ~/.local/share/podenv/volumes/rootfs-7e08b7-home /root /bin/sh

This is useful to avoid polluting the container storage.

Nix flakes

$ podenv nixpkgs#hello

… runs the installable using bubblewrap: bwrap [unshare args] --bind ~/.local/share/podenv/volumes/nix-store /nix --bind ~/.local/share/podenv/volumes/nix-cache ~/.cache/nix --clearenv --setenv NIX_SSL_CERT_FILE /etc/pki/tls/certs/ca-bundle.crt nix --extra-experimental-features "nix-command flakes" run nixpkgs#hello

If necessary, podenv automatically installs the Nix toolchain using bubblewrap with the nix.setup application.

Documentation

Podenv documentation is organized into the following four sections:

Tutorials

These guides help you get your hands dirty with working examples:

• Install and use podenv
• Use an application
• Create an application
• Howto use Nix

Howtos

These cookbooks teach you how to solve specific tasks:

• Configure a VPN
• Setup a custom image
• Contribute to podenv

Discussions

These posts explain the context and motivation behind this tool:

• Declarative containers
• Using dhall for configuration
• Roadmap

References

These comprehensive resources cover details that other texts will gloss over:

• Command line
• Configuration