Debian 13 Tutorial / Run Rootless Podman Containers and Preserve Volume Data

In Debian 13, you can run Podman as a regular user and create rootless containers. To retain the necessary files even after replacement, you need to separate the container's temporary writable layer from a separate volume and rerun it with the same user and same volume. This tutorial locks the official httpd image by digest and verifies the response and data preservation on a loopback port.

Separate Images, Containers and Named Volumes

An image is a distribution unit containing the program and the files needed for execution, while a container is a running instance created from an image. Files written into the container’s writable layer, outside separately mounted storage, are lost when that container is deleted. Named volumes are storage spaces managed with separate names, allowing the separation of container replacement and lifecycle.

Rootless means running with regular user privileges on the host. User ID (UID) 0 inside the container is not treated the same as root on the host. A rootless container can still use resources available to that host user and shares the host kernel. Its isolation is not equivalent to a separate VM. The basic execution structure can be referred to in the Podman 5.4.2 documentation.

Target Practice name Handling during replacement
Image digest of docker.io/library/httpd Record this based on re-executing the same content.
Container lf-web27 Stop and delete, then create a new one.
Named volume lf-web27-data Preserve during container replacement and connect to the new container.
External port 127.0.0.1:8080 Accessible only within the Debian VM, and check again after running.

Check Packages and the Ordinary-user Session

A separate Debian 13 VM with sudo access and a network to reach the image registry are required. Only perform the installation with sudo, and thereafter, all podman commands are run as the logged-in regular user. Do not change to sudo podman, because this would access root's separate image and container storage, so it is not mixed in the troubleshooting process either.

sudo apt update
sudo apt install podman uidmap passt fuse-overlayfs curl
podman --version
id
printf '%s\n' "$XDG_RUNTIME_DIR"
grep "^$(id -un):" /etc/subuid /etc/subgid
systemctl --user is-system-running
podman info --format json

In the exercise, we used Podman 5.4.2, a regular user with UID and group ID (GID) 1000, and the execution path /run/user/1000. /etc/subuid and /etc/subgid each contained lfstudent:100000:65536, and the user manager was running. This range is used when mapping additional container user IDs. Do not copy ranges from other accounts to allocate duplicates.

podman info showed host.security.rootless as true, cgroupVersion as v2, cgroupManager as systemd, and storage under the user's home directory using overlay. If there are environment variable or user manager connection errors, check again from a real SSH or console login session of the regular user. Do not fake XDG_RUNTIME_DIR with any path or mix sudo environments to make it appear normal.

If any lab name or port 8080 is already in use, plan to change the practice name and port without removing existing resources. Use one dedicated Bash session for the lab. The preparation block enables error stopping; if an unexpected failure ends the shell, inspect remaining resources from a new ordinary-user session before continuing.

set -euo pipefail
if podman container exists lf-web27; then
    echo "A container with this name already exists." >&2
    exit 1
fi
if podman volume exists lf-web27-data; then
    echo "A volume with this name already exists." >&2
    exit 1
fi
if test -e "$HOME/lf-course27-image.txt"; then
    echo "The image record file already exists." >&2
    exit 1
fi
ss -ltn

Select the Official Image and Record Its Digest

Instead of a short httpd name, use an address that includes the registry and namespace. httpd Docker Official Image Guide was used to check and select the tag, Dockerfile, and web root path. This is the Docker Official Image for Apache HTTP Server and runs programs inside the container that are different from the host's Nginx.

podman pull docker.io/library/httpd:2.4.71-trixie
image=$(podman image inspect docker.io/library/httpd:2.4.71-trixie --format '{{index .RepoDigests 0}}')
case "$image" in
    docker.io/library/httpd@sha256:*) ;;
    *) echo "Unexpected image reference." >&2; exit 1 ;;
esac
printf '%s\n' "$image" | tee "$HOME/lf-course27-image.txt"
podman image inspect "$image" --format '{{.Architecture}} {{.Os}} {{.Id}}'

The references recorded during verification are as follows. In actual execution, use the values obtained from the above inspect, and if the tag changes, a new digest may appear. The architecture was amd64, and the operating system was linux.

docker.io/library/httpd@sha256:32e9403360ab2f1047523e72f256527fb9aee68b342abf6ad03f0d629157f3d9

Tags can move to other images, but the digest is used to identify content. Recording the digest does not automatically resolve who created the image or respond to vulnerabilities. Fixed images do not automatically update to the latest security patches, so the schedule for reviewing, testing, and replacing new versions is managed separately. If pull fails, distinguish between registry authentication, request limits, DNS, TLS, and network errors, and do not run arbitrary images with the same name instead.

Populate a Dedicated Volume and Publish a Loopback Port

First, create a named volume and then record index.html with a one-time container. The preparation container does not need a network, so it runs with none and is removed with --rm after exiting. The volume itself remains. This volume is for new practice purposes, so it does not overwrite the web root of existing services.

podman volume create lf-web27-data
podman run --rm --network none -v lf-web27-data:/data --entrypoint /bin/sh "$image" -c 'printf "LF PODMAN 27\n" > /data/index.html'
podman run -d --name lf-web27 -p 127.0.0.1:8080:80 -v lf-web27-data:/usr/local/apache2/htdocs:ro "$image"
podman ps
podman port lf-web27
curl --noproxy '*' -fsS http://127.0.0.1:8080/

The left side of -p is the host address and port, and the right side 80 is the port inside the container. Specifying 127.0.0.1 makes it accessible only inside the VM. The :ro at the end of -v mounts the volume as read-only to this web server. It is not a global setting that prevents other containers or host processes from writing to the volume, so this stage is distinguished from the stage where the preparation container writes to it.

The actual port output was 80/tcp → 127.0.0.1:8080, and the response was LF PODMAN 27. If it's immediately after startup, request again after a short while. If it continues to fail, check for port conflicts with podman logs lf-web27 and podman inspect lf-web27. A container being running does not mean that HTTP serving has succeeded.

Replace the Container and Verify Data Persistence

The following steps involve storing the hash of the volume files and creating a comparison file in the container's /tmp. Inspect is used to read the volume path, but other directories inside the Podman storage are not directly modified. After stopping and deleting the container, verify whether the files in the volume remain the same.

point=$(podman volume inspect lf-web27-data --format '{{.Mountpoint}}')
hash_before=$(sha256sum "$point/index.html")
podman exec lf-web27 sh -c 'printf "ephemeral\n" > /tmp/lf-web27-marker'
podman stop lf-web27
podman rm lf-web27
test -f "$point/index.html"
test "$hash_before" = "$(sha256sum "$point/index.html")"
podman run -d --name lf-web27 -p 127.0.0.1:8080:80 -v lf-web27-data:/usr/local/apache2/htdocs:ro "$image"
curl --noproxy '*' -fsS http://127.0.0.1:8080/
podman exec lf-web27 test ! -e /tmp/lf-web27-marker

In the verification, the HTTP response of the new container was the same, and the hash of index.html was also identical. On the other hand, the /tmp files from the previous container were not present in the new container. The last test does not print anything if successful and returns exit code 0. From these results, you can distinguish the lifespan differences between volumes and container writable layers.

If the new container is slow to get ready and curl fails, check the actual state and logs and try the request again. In a shell that stops on errors, do not assume that cleanup was performed afterwards; check remaining resources with podman ps -a and volume ls. Preserving volumes is different from backup. Losing the user home or host disk could also result in losing the same local volumes.

Inspect the Running Container’s Actual AppArmor State

Even if AppArmor is enabled on the host, one should not assume that all rootless containers are restricted by an enforced profile. With the replaced container now running, compare the inspect information and the actual process state using the following command.

podman info --format json
podman inspect lf-web27 --format '{{.AppArmorProfile}}'
podman exec lf-web27 cat /proc/self/attr/current

In this tutorial, we checked while the first container was running. The host AppArmor module was Y, but the rootless information's apparmorEnabled was false, the container AppArmorProfile was empty, and the process output was crun (unconfined). Do not interpret these results as an enforce-mode AppArmor profile being applied to this container. We did not disable AppArmor or seccomp, nor did we add --privileged to avoid errors.

Compare Host and Container UID Mappings

Check the numeric ID mapping rather than the username of the rootless container. In the default namespace of this practice, container UID 0 corresponded to host 1000, and UIDs 1 to 65536 corresponded to host 100000 onwards. Groups had the same structure. It may differ with a different account or with the --userns option.

podman unshare cat /proc/self/uid_map /proc/self/gid_map
stat -c '%u:%g' "$point/index.html"
podman unshare stat -c '%u:%g' "$point/index.html"

The index.html appeared as 1000:1000 on the host and 0:0 inside podman unshare. Unshare is a tool for looking at the same file from the perspective of a different ID within Podman's user namespace, and it is not a command that makes you root over the entire host. The podman unshare manual describes this namespace scope.

For additional comparison, after stopping the server, create a single file in the same practice volume and set it to container UID/GID 33. This number is for observing the mapping and does not mean that all images use the same service account.

podman stop lf-web27
podman rm lf-web27
podman run --rm --network none -v lf-web27-data:/data --entrypoint /bin/sh "$image" -c 'printf "mapped\n" > /data/mapped.txt; chown 33:33 /data/mapped.txt'
stat -c '%u:%g' "$point/mapped.txt"
podman unshare stat -c '%u:%g' "$point/mapped.txt"

The actual result was host 100032:100032, namespace 33:33. This is not the same as changing the file owner to 33 on the host. To resolve permission issues, we do not apply chown to the entire user home. The :U option can recursively change ownership on the host side, and :z and :Z relate to SELinux labels, so it is not attached as a general solution for AppArmor issues. The exact effects of volume options can be checked in Podman run's volume and security options .

Remove Only the Lab Volume and Retain the Image Record

The mapping comparison above already stopped and removed lf-web27. Confirm this in podman ps -a before removing its volume. If you skipped that comparison and the lab container still exists, stop it with podman stop lf-web27 and remove it with podman rm lf-web27. Do not force removal of an in-use volume.

Deleting the remaining dedicated volumes in this exercise will also delete their data. First, determine whether any files need to be preserved, then remove only the specific name. The scope of creation and management of named volumes can be checked in Podman volume create documentation .

podman ps -a
podman volume inspect lf-web27-data
podman volume rm lf-web27-data
podman volume ls
ss -ltn

In the actual cleanup, only the lf-web27 container and lf-web27-data volume were removed. The received images and the digest records of lf-course27-image.txt were retained, and prune, which deletes other images and volumes in bulk, was not used. By deciding separately whether to retain persistent data and image reproduction information, one can avoid confusing exercise cleanup with operational data deletion.