podview

README

podview

A simple web dashboard for Podman.

Features

• Apps dashboard - start page showing labeled containers as application cards
• List and inspect all containers
• List images with tags and sizes
• Trigger podman auto-update
• Environment variables and secrets are never displayed
• Single binary, no JavaScript, zero dependencies (only Go stdlib)

App labels

Containers with labels prefixed ch.jo-m.go.podview.app. appear as apps on the start page. Multiple containers sharing the same name are grouped into one app.

Label	Required	Description	Example
ch.jo-m.go.podview.app.name	yes	App name (used for grouping)	Nextcloud
ch.jo-m.go.podview.app.icon	no	Emoji icon	☁️
ch.jo-m.go.podview.app.category	no	Category heading (default: "Uncategorized")	Productivity
ch.jo-m.go.podview.app.sort-index	no	Sort order within category (default: 0)	10
ch.jo-m.go.podview.app.subtitle	no	Short subtitle	Cloud storage
ch.jo-m.go.podview.app.description	no	Longer description	Self-hosted file sync and share
ch.jo-m.go.podview.app.url	no	URL opened when clicking the card	https://cloud.example.com

Example:

podman run -d \
  --label ch.jo-m.go.podview.app.name=Nextcloud \
  --label ch.jo-m.go.podview.app.icon=☁️ \
  --label ch.jo-m.go.podview.app.category=Productivity \
  --label ch.jo-m.go.podview.app.sort-index=10 \
  --label ch.jo-m.go.podview.app.subtitle="Cloud storage" \
  --label ch.jo-m.go.podview.app.url=https://cloud.example.com \
  nextcloud:latest

Additional apps via environment variables

Apps can also be defined without containers using environment variables. This is useful for adding links to external services (e.g. a router admin page) that aren't managed by Podman.

The format is PODVIEW_APP_<ID>_<FIELD>=<value>, where <ID> is an arbitrary identifier grouping the fields together, and <FIELD> is one of:

Field	Required	Description
NAME	yes	App name
ICON	no	Emoji icon
CATEGORY	no	Category heading (default: "Uncategorized")
SORT_INDEX	no	Sort order within category (default: 0)
SUBTITLE	no	Short subtitle
DESCRIPTION	no	Longer description
URL	no	URL opened when clicking the card

Example:

export PODVIEW_APP_ROUTER_NAME=Router
export PODVIEW_APP_ROUTER_URL=http://192.168.1.1
export PODVIEW_APP_ROUTER_ICON=🌐
export PODVIEW_APP_ROUTER_CATEGORY=Infrastructure
export PODVIEW_APP_NAS_NAME=NAS
export PODVIEW_APP_NAS_URL=http://192.168.1.2
export PODVIEW_APP_NAS_CATEGORY=Storage

These apps appear on the apps dashboard alongside container-based apps. If a container app and an env app share the same name, the container app takes precedence.

Requirements

• Go 1.23+
• Podman with the API socket enabled (podman system service)

Build

go build -o podview .

Usage

./podview

The server starts on :8080 by default and connects to the rootless Podman socket.

Environment variables

Variable	Default	Description
LISTEN_ADDR	:8080	HTTP listen address
PODMAN_SOCKET	$XDG_RUNTIME_DIR/podman/podman.sock	Path to the Podman API socket
BASE_PATH	(none)	URL path prefix for hosting at a subpath (e.g. /podview), no trailing slash

Running with Docker

Docker images are available at ghcr.io/jo-m/podview for linux/amd64 and linux/arm64.

Mount the Podman API socket into the container and point PODMAN_SOCKET to it:

docker run -d \
  -p 8080:8080 \
  -v $XDG_RUNTIME_DIR/podman/podman.sock:/run/podman.sock:ro \
  -e PODMAN_SOCKET=/run/podman.sock \
  ghcr.io/jo-m/podview

With Podman (rootless):

podman run -d \
  -p 8080:8080 \
  -v $XDG_RUNTIME_DIR/podman/podman.sock:/run/podman.sock:ro \
  -e PODMAN_SOCKET=/run/podman.sock \
  ghcr.io/jo-m/podview

All environment variables (LISTEN_ADDR, PODMAN_SOCKET, BASE_PATH) work as described above. For example, to host at a subpath behind a reverse proxy:

docker run -d \
  -p 8080:8080 \
  -v $XDG_RUNTIME_DIR/podman/podman.sock:/run/podman.sock:ro \
  -e PODMAN_SOCKET=/run/podman.sock \
  -e BASE_PATH=/podview \
  ghcr.io/jo-m/podview

Make sure the Podman socket is running before starting the container (systemctl --user enable --now podman.socket).

Running as a systemd user service

A sample unit file is provided in podview.service. Install it with:

cp podview.service ~/.config/systemd/user/
systemctl --user enable --now podview

Enabling the Podman socket

For rootless Podman, enable the socket with:

systemctl --user enable --now podman.socket

Documentation

Overview

Package main implements podview, a simple web dashboard for rootless Podman. It connects to the Podman API socket and renders container/image information server-side using Go templates. No JavaScript, no external dependencies.