Develop on Ubuntu 24.04 with Podman

Visual Studio Code with Podman on a Fresh Ubuntu 24.04 VM

This guide explains exactly how to set up Visual Studio Code (VS Code) with Podman on a clean installation of Ubuntu 24.04 LTS inside a virtual machine, and how to build and run the maui-docker project locally inside a Dev Container.

1. Prepare the System

After installing Ubuntu 24.04, open a terminal and install the required packages:

sudo apt update
sudo apt install -y podman podman-docker uidmap curl git x11-apps
snap install code --classic

Package overview

• Podman: Docker-compatible container engine
• podman-docker: enables Docker-CLI compatibility
• uidmap: required for rootless containers
• x11-apps: optional, useful to test X11 GUI forwarding
• code: Visual Studio Code - Our IDE

2. Enable the Podman User Socket

Enable the user socket so VS Code can communicate with Podman:

systemctl --user enable --now podman.socket

Add this line to your shell configuration (for example ~/.bashrc):

echo 'export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock' >> ~/.bashrc

Reload the configuration:

source ~/.bashrc

Create folder for your Source

mkdir ~/source
cd ~/source

3. Configure Visual Studio Code

Start VS Code:

code .

Install these extensions:

• C#
• C# Dev Kit
• Dev Containers — ms-vscode-remote.remote-containers
• Container Tools

Optional: adjust your user settings (settings.json) so VS Code uses Podman directly:

{
    "dev.containers.dockerPath": "podman",
    "dev.containers.dockerSocketPath": "unix:///run/user/1000/podman/podman.sock",
    "containers.environment": {
        "DOCKER_HOST": "unix:///run/user/1000/podman/podman.sock",
        "CONTAINERS_STORAGE_CONF": "/home/dev/.config/containers/storage.conf",
        "XDG_DATA_HOME": "/home/dev/.local/share",
        "XDG_RUNTIME_DIR": "/run/user/${localEnv:UID}"
    },
    "containers.containerClient": "com.microsoft.visualstudio.containers.podman",
    "containers.orchestratorClient": "com.microsoft.visualstudio.orchestrators.podmancompose",
    "containers.commands.attach": "${containerCommand} exec -it ${containerId} ${shellCommand}",
    "dev.containers.defaultFeatures": {
        
    }
}

Install .NET SDK, there should be a message

4. Build the MAUI Docker Environment Locally

Clone the repository and build the container image on your own system:

cd ~/source
git clone https://github.com/MauiGtk/maui-docker.git
cd ~/source/maui-docker
podman build -t maui-env .

This creates a local image named maui-env that will be used by VS Code when opening the project inside a Dev Container.

5. Allow GUI Access (X11)

To run graphical MAUI GTK applications, allow the container to use your X display:

xhost +local:

(You can later restrict access again with xhost -local:.)

6. Clone the maui-linux Project

You can just clone the maui-linux repository

git clone https://github.com/MauiGtk/maui-linux.git

or you could clone the lytico repository

git clone https://github.com/lytico/maui.git

I don't know witch is a better point to start, in future maui-linux.net will provide it's own stable compilable repository

7. Open the Project in VS Code

Open the project folder:

cd ~/source/maui-docker
code .

Then run Ctrl + Shift + P → “Dev Containers: Reopen in Container”. VS Code will start a Podman container based on the included .devcontainer configuration.

8. Build Solution

In VS Code, go to Terminal and run

dotnet build Microsoft.Maui.BuildTasks.slnf

9. Run the MAUI Sample Application

Inside the container terminal, execute:

cd /mauienv/maui/src/Controls/samples/Controls.Sample
dotnet run --framework net8.0-gtk

If everything is configured correctly, a GTK window should appear on your Ubuntu 24.04 desktop.

9. Troubleshooting

VS Code reports “Docker not found”

Ensure podman-docker is installed and DOCKER_HOST is set correctly.

GUI does not open / “cannot open display”

Verify $DISPLAY (e.g. :0) is set and that you have run xhost +local:.

Container fails to start

Check if the socket is active:

 systemctl --user status podman.socket

10. Downloads

For a faster installation, here is a shell script, after running go to Step 7

https://wiki.maui-linux.net/downloads/install_ubuntu_podman_mauilinux.sh

And for easy start you can Download a full working Xubuntu 24.04 VM here

https://wiki.maui-linux.net/downloads/Maui+Linux+V1.0+(Xubuntu).rar

User: dev

Password: Dev123

11. Summary

Component	Purpose
Ubuntu 24.04 VM	Clean test environment
Podman	Docker-compatible container engine
podman-docker	Docker CLI compatibility layer
podman.socket	API endpoint for VS Code
VS Code Dev Containers	Container-based development environment
X11 forwarding	Enables GUI applications inside containers

With these steps, a clean Ubuntu 24.04 VM can run Visual Studio Code Dev Containers using Podman, including full GUI support for .NET MAUI GTK applications.