Using Podman in Steam OS

Jan 3, 2023

🏁 Getting Started

NOTE: This guide does NOT require putting Steam OS in developer mode or disabling the read-only file system.

The purpose of this guide is to detail how to install and set up Podman for container-based development in Steam OS.

Prerequisites

IMPORTANT: Change to desktop mode before peforming any instructions defined in this guide.

IMPORTANT: We must set a password for the deck user, as the Podman install script uses sudo to gain privileges needed to modify /etc/subuid and /etc/subgid. Podman requires this to enable rootless containers. More info here & here.

NOTE: We could possibly disable the ‘deck’ user password again after installing Podman

# Set a password for the 'deck' user
passwd

# Install/update pip
python -m ensurepip --upgrade

⛓️ Install Podman and Tools

NOTE: There are multiple ways to install Podman in Steam OS, but this guide provides instructions via the Distrobox repo.

# Distrobox ( optional )
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/install | sh -s -- --prefix ~/.local

# Podman
curl -s https://raw.githubusercontent.com/89luca89/distrobox/main/extras/install-podman | sh -s -- --prefix ~/.local

# Podman Desktop
flatpak install --user flathub io.podman_desktop.PodmanDesktop

# Install podman-remote 
flatpak install flathub com.visualstudio.code.tool.podman

# Podman Compose
python -m pip install --user podman-compose

# Docker Compose
python -m pip install --user docker-compose

Verify that you have something similar to the following contents in ~/.bashrc NOTE: This could be added to any script that executes upon user login

# Add ~/.local/bin to PATH
if [ -d "$HOME/.local/bin" ] ; then
    PATH="$HOME/.local/bin:$PATH"
fi

# Add ~/.local/podman/bin to PATH
if [ -d "$HOME/.local/podman/bin" ] ; then
    PATH="$HOME/.local/podman/bin:$PATH"
fi

# Enable GUI for apps running in Distrobox
xhost +si:localuser:$USER

Congratulations! At this point, you should be able to use podman and podman-compose at your discretion.

🎈 Usage

Create a directory to store our files for individual projects

mkdir -p ~/Workspace/

podman

Test Podman to be sure things are working correctly

# Start a detached HTTP server container
podman run -dt -p 8080:80/tcp docker.io/library/httpd
# Visit http://localhost:8080/ in a web browser to verify

podman-compose

Create ~/Workspace/podman-compose.yml with the following contents:

version: '3.7'
services:
  containerws-web-tools:
	image: python:3
	tty: true
	volumes:
	  - ${WORKSPACE_LOCATION}:/mnt/workspace
	working_dir:
	  /mnt/workspace
	entrypoint: 
	  sh -c "/bin/bash"
	environment:
	  - WORKSPACE_LOCATION=${WORKSPACE_LOCATION}

NOTE: The container will have read / write access to whatever directory you set to the WORKSPACE_LOCATION environment variable here. It is used in ~/Workspace/podman-compose.yml to ( bind ) mount the location in the container. This example sets it to ~/Workspace

Start the container

# run podman-compose to bring up the container
WORKSPACE_LOCATION=~/Workspace podman-compose -f ~/Workspace/podman-compose.yml up -d

Verify that the container is running

podman container ls

Attach to the container. This is where you will spend the majority of your time.

podman attach <container_name>

Stop the container

# run podman-compose to bring down the container
podman-compose -f ~/Workspace/podman-compose.yml down

🧐 Advanced Usage

Podman API

NOTE: Podman Desktop seems to do something similar to this in the background when starting.

Create ~/.config/systemd/user/podman.service with the following contents:

[Unit]
Description=Podman API Service
Requires=podman.socket
After=podman.socket
Documentation=man:podman-system-service(1)
StartLimitIntervalSec=0

[Service]
Delegate=true
Type=exec
KillMode=process
Environment=LOGGING="--log-level=info"
ExecStart=/home/deck/.local/podman/bin/podman $LOGGING system service

[Install]
WantedBy=default.target

Create ~/.config/systemd/user/podman.socket with the following contents:

[Unit]
Description=Podman API Socket
Documentation=man:podman-system-service(1)

[Socket]
ListenStream=%t/podman/podman.sock
SocketMode=0660

[Install]
WantedBy=sockets.target

Start socket user service automatically on login

# (starting Podman Desktop seems to do something similar)
systemctl --user enable podman.socket --now

NOTE: If you did not install podman-remote via Flatpak for some reason, you can do the following as an alternative

# Create `~/.local/podman/bin/podman-remote` with the following
podman --remote $*

# Make it executable
chmod +x ~/.local/podman/bin/podman-remote

Give a specific Flatpak app ( VSCodium ) access to the Podman socket

flatpak override --user --filesystem=/run/user/1000/podman/podman.sock com.vscodium.codium

Set up Development extensions in VSCodium

# In VSCodium: CTRL+P @command:workbench.action.terminal.selectDefaultShell
# select "bash"

# install Docker extension
code --install-extension ms-azuretools.vscode-docker

# install remote dev extension
code --install-extension jeanp413.open-remote-ssh

# ~Docker settings (Extensions -> Docker -> Extension Settings -> Docker)
"docker.environment": {
  "DOCKER_HOST": "unix:///run/user/1000/podman/podman.sock"
},
"docker.dockerPath": "/app/tools/podman/bin/podman-remote"

# Use the manually created podman-remote if not using the Flatpak version:
"docker.dockerPath": "~/.local/podman/bin/podman-remote"

Issues

Networking between containers seems not to work. This means that deploying containers as pods may be problematic.

Table Of Contents