Custom disk images

How to create custom ext2 images to use as a filesystem for CheerpX

This guide will show you how to configure a Docker container and build it into an ext2 image for use with CheerpX.

1. Create a Dockerfile

First, create your Dockerfile to define the environment. Here’s an example of how to build a Docker image that installs the curl command:

FROM --platform=i386 docker.io/i386/debian:buster
ARG DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get -y upgrade && apt-get -y install curl

Note

The base image’s architecture must be 32-bit x86 (for example, i386 or i686).

2. Create a container out of your Dockerfile

Once the Dockerfile is ready, build the image. Use buildah to create a container image for your filesystem.

buildah build -f Dockerfile --dns=none --platform linux/i386 -t cheerpximage

3. Create a container from the Docker Image

Now, create a container from the image using podman. Ensure the image name matches the one you built in the previous step.

podman create --name cheerpxcontainer cheerpximage

4. Copy the Filesystem from the Container into a local directory

Create a directory for the filesystem:

mkdir cheerpXFS

Use the podman cp command to copy the container’s filesystem into the local directory:

podman unshare podman cp cheerpxcontainer:/ cheerpXFS/

Note

The podman unshare command helps avoid permission problems by running the operation in a special mode where you act like the container’s “root user.”

5. Create an ext2 Image from the local directory

Now that you have the local directory, you can create an ext2 image from it:

podman unshare mkfs.ext2 -b 4096 -d cheerpXFS/ cheerpXImage.ext2 600M

6. Clean up unused resources

After creating your ext2 image, it’s good practice to clean up unused resources to free up space:

Remove the container:

podman rm cheerpxcontainer

Remove the image:

buildah rmi cheerpximage

Remove temporary directories:

rm -rf cheerpXFS

Optional: edit /etc/subgid (for the host user)

The /etc/subgid file defines the ranges of subordinate group IDs allocated to specific user accounts on the host for managing user namespaces in containers. This step is optional and not necessary for most use cases. However, you may choose to configure it if you encounter namespace-related conflicts.

1. Identify your host user

Run the following command to determine the host user running container commands:

whoami

2. Check /etc/subgid for your user

Open /etc/subgid and look for an entry matching your user:

sudo nano /etc/subgid

The file should contain lines in the format:

<username>:<start_id>:<count>

For example, for the user johndoe:

johndoe:100000:65536

3. Modify the file

If you need to change the subgid range for the host user, modify the start_id and/or count as needed. For example, if you want to assign a new range starting at 200000 with a count of 65536, you would change it to:

johndoe:200000:65536

For more information about subgid, refer to the subgid documentation.

Conclusion

Congratulations! You have successfully created a custom ext2 image that can be used as a filesystem for CheerpX. This image is now ready to be loaded into your CheerpX environment for further testing and deployment.

If you’d like to see more details on how to implement the custom ext2 image with CheerpX, please refer to the Full OS tutorial.