https://github.com/podenv/podenv
a container wrapper
https://github.com/podenv/podenv
dhall haskell linux-containers nix podman rootless-containers
Last synced: 7 months ago
JSON representation
a container wrapper
- Host: GitHub
- URL: https://github.com/podenv/podenv
- Owner: podenv
- License: apache-2.0
- Created: 2019-07-30T13:32:11.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-02-18T13:21:13.000Z (9 months ago)
- Last Synced: 2025-03-28T02:50:39.822Z (8 months ago)
- Topics: dhall, haskell, linux-containers, nix, podman, rootless-containers
- Language: Haskell
- Homepage:
- Size: 639 KB
- Stars: 72
- Watchers: 3
- Forks: 11
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-dhall - podenv - A container runtime wrapper using Dhall to define functional environments. (Projects)
README
# podenv: a container wrapper
[](https://hackage.haskell.org/package/podenv)
[](LICENSE)
> 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](#capabilities)
- [Multiple runtimes](#runtimes)
- [VPN network namespace](#namespace)
- [Functional configuration](#configuration)
- [Simple to use](#usages)
Podenv differs from [toolbx](https://containertoolbx.org/) or [flatpak](https://flatpak.org/):
- 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
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](https://github.com/podenv/podenv/blob/main/hub/schemas/Capabilities.dhall)
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.
Podenv works with multiple container runtimes:
- Podman for image and Containerfile.
- Bubblewrap for local rootfs and Nix Flakes.
The runtime integration is decoupled from the application description
so that more options can be added in the future.
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](./docs/howtos/vpn.md).
Applications are user-defined with functionnal and re-usable expressions:
#### Firefox with a fedora container
```dhall
(env:PODENV).Application::{
, name = "firefox"
, description = Some "Mozilla Firefox"
, runtime = (env:PODENV).Hub.fedora.useGraphic [ "firefox" ]
, command = [ "firefox", "--no-remote" ]
, capabilities = (env:PODENV).Capabilities::{ wayland = True, network = True }
}
```
The fedora useGraphic function defines a custom Containerfile:
```dhall
\(pkgs : List Text) ->
(env:PODENV).ContainerBuild::{
, containerfile =
''
FROM fedora:latest
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](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix.html#installables):
```dhall
(env:PODENV).Application::{
, name = "polyglot"
, description = Some "Tool to count lines of source code."
, runtime = (env:PODENV).Hub.nix.useInstallables [ "github:podenv/polyglot.nix" ]
, capabilities = (env:PODENV).Capabilities::{ cwd = True }
}
```
#### Hub
By default, podenv uses the [hub](./hub) collection.
Run `podenv --list` to see the available applications.
Podenv provides a simple command line: `podenv [--caps] application-name [args]`.
Checkout the tutorials for examples.
# Documentation
Podenv documentation is organized into the following [four sections][documentation]:
[documentation]: https://www.divio.com/en/blog/documentation/
## Tutorials
These guides help you get your hands dirty with working examples:
* [Install and use podenv](./docs/tutorials/install.md)
* [Use an application](./docs/tutorials/use.md)
* [Create an application](./docs/tutorials/create.md)
* [Howto use Nix](./docs/tutorials/nix.md)
* [Work with rawhide](./docs/tutorials/rawhide.md)
## Howtos
These cookbooks teach you how to solve specific tasks:
* [Configure a VPN](./docs/howtos/vpn.md)
* [Setup a custom image](./docs/howtos/image.md)
* [Contribute to podenv](./docs/howtos/contribute.md)
## Discussions
These posts explain the context and motivation behind this tool:
* [Declarative containers](./docs/discussions/declarative-containers.md)
* [Using dhall for configuration](./docs/discussions/dhall-configuration.md)
* [Roadmap](./docs/discussions/roadmap.md)
## References
These comprehensive resources cover details that other texts will gloss over:
* [Command line](./docs/references/command-line.md)
* [Configuration](./docs/references/configuration.md)