How to Configure Persistent Storage for Containers in IGEL Managed Containers

IGEL Managed Containers (IMC) provisions a dedicated storage partition for container data, mounted at /services_rw/imc/container_data. Data written here is persistent across reboots.

For your own container data (databases, config, uploads, etc.), IMC provides a dedicated directory on this partition:

/services_rw/imc/container_data/volumes

This is the recommended location on the host where containers can store and access data. IMC creates this directory automatically during installation, and it is owned by the local IGEL OS user account. To allow containers to read and write here, any sub-directories or files must be created with regular user permissions, since containers do not run as root.

To configure the storage size of the dedicated storage partition, see Configuring the Container Storage.

Rules & Limitations

• Named and anonymous volumes are not supported. They are not removed when the container they are attached to is removed, which would leave orphaned data on the storage partition.

• The host path should be under /services_rw/imc/container_data/volumes for read-write access. Other paths which allow read-write access are /logging, /media and /tmp. Paths outside the permitted directories are rejected and the container will not be created.

• Environment-variable expansion ($VAR, ${VAR}) and home-directory expansion (~) are not supported in bind sources — always use a full absolute path.

Mapping a Host Directory into the Container

Choose a path for the directory that will hold your container’s data, for example: /services_rw/imc/container_data/volumes/myapp/.

Notes:

• Use one directory per container (or per data set) to keep things organized.

• The directory lives on the IMC storage partition, so its contents survive reboots.

Reference the directory as a bind mount in the container's Compose file. The host path (the source value) must be an absolute path under /services_rw/imc/container_data/volumes.

Example

services:
  myapp:
    image: docker.io/library/alpine:latest
    volumes:
      - "/services_rw/imc/container_data/volumes/myapp:/data:rw"

Read-only vs Read-write

• Specify ro to mount the directory read-only.

• Omit the mode or use rw for read-write access.

Permissions (rootless containers)

IMC runs containers rootless under the local IGEL OS user account.

A process running as root inside the container is mapped to the local IGEL OS user. Therefore, it can normally read from and write to a bind-mounted directory owned by that user.

A process running as a non-root user inside the container is mapped differently and might not have write access to the mounted directory. Use one of the following approaches.

Changing the Host Directory Ownership

By default, non-root container UIDs and GIDs are mapped to subordinate IDs on IGEL OS.

1. Subordinate UID and GID ranges start at 100000 so, for example, container UID and GID 1000 are mapped as follows:

Container UID 1000 → IGEL OS UID 100999
Container GID 1000 → IGEL OS GID 100999

2. To allow the container user to write to the directory, change its ownership on IGEL OS. Run the following command as root:

chown 100999:100999 /services_rw/imc/container_data/volumes/myapp

Letting the IMC Container Runtime Adjust the Ownership

The Podman-specific :U volume option recursively changes the ownership of the bind-mount source to the host UID and GID that correspond to the container process.

1. Specify both the UID and GID of the container process:

services:
  myapp:
    image: example/myapp
    user: "1000:1000"
    volumes:
      - "/services_rw/imc/container_data/volumes/myapp:/data:U"

2. After the container is created, the changed ownership is visible on IGEL OS:

$ ls -ld /services_rw/imc/container_data/volumes/myapp
drwx------ 2 100999 100999 4096 Jul 31 12:30 /services_rw/imc/container_data/volumes/myapp

Mapping the IGEL OS User to the Container User

The keep-id user namespace mode maps the local IGEL OS user directly to a selected UID and GID inside the container.

For example, the following configuration maps the local IGEL OS account to container UID and GID 1000:

services:
  myapp:
    image: example/myapp
    user: "1000:1000"
    volumes:
      - "/services_rw/imc/container_data/volumes/myapp:/data:rw"

The host directory can therefore remain owned by the local IGEL OS user.