Podman Quadlet

Running DOCSight as a Podman Quadlet

Podman is a daemonless container engine popular on Fedora, RHEL, and related distributions. Quadlets are systemd unit files that describe a container — Podman generates a .service unit from them automatically, so DOCSight starts and restarts like any other systemd service.

This is the recommended approach for running DOCSight on Podman-based systems.

Prerequisites

• Podman 4.4 or newer (quadlet support was added in 4.4)
• systemd as your init system
• The ghcr.io/itsdnns/docsight:latest image (pulled automatically on first start)

Check your Podman version:

podman --version

Create the Quadlet File

Quadlet files live in one of two locations depending on whether you want to run as root or as a regular user:

Mode	Directory
Rootless (recommended)	~/.config/containers/systemd/
Root	/etc/containers/systemd/

Create the directory if it doesn't exist:

mkdir -p ~/.config/containers/systemd/

Create the file ~/.config/containers/systemd/docsight.container:

[Unit]
Description=DOCSight DOCSIS Monitoring
After=network-online.target

[Container]
Image=ghcr.io/itsdnns/docsight:latest
ContainerName=docsight
PublishPort=8765:8765
Volume=docsight_data:/data
Environment=TZ=Europe/Berlin

[Service]
Restart=always
TimeoutStartSec=60

[Install]
WantedBy=default.target

Adjust TZ=Europe/Berlin to your timezone if needed.

Enable and Start

Reload the systemd user daemon so it picks up the new quadlet file:

systemctl --user daemon-reload

Start DOCSight:

systemctl --user start docsight

Enable auto-start on login/boot:

systemctl --user enable docsight

To start services on boot even without logging in (lingering):

loginctl enable-linger $USER

Check Status

systemctl --user status docsight

View logs:

journalctl --user -u docsight -f

Open DOCSight

Go to http://localhost:8765 in your browser. On first launch, the setup wizard walks you through connecting your modem.

Updating

Pull the latest image and restart the service:

podman pull ghcr.io/itsdnns/docsight:latest
systemctl --user restart docsight

Your configuration and history are stored in the docsight_data volume and survive updates.

Using a Persistent Volume

By default, Podman creates a named volume docsight_data automatically. To check where it lives:

podman volume inspect docsight_data

If you prefer to bind-mount a specific directory on your host:

[Container]
...
Volume=/home/youruser/docsight-data:/data

Create the directory first: mkdir -p ~/docsight-data

Docker Compose Alternative

If you prefer podman-compose over quadlets, DOCSight works with the standard docker-compose.yml from the Installation Guide. Run:

podman-compose up -d

Note: podman-compose is a separate package (pip install podman-compose or via your package manager).

Troubleshooting

Container fails to start

Check the journal for errors:

journalctl --user -u docsight --no-pager | tail -20

Port 8765 already in use

Change the host port in the quadlet file:

PublishPort=9876:8765

Then access DOCSight at http://localhost:9876.

Image not found

Pull it manually first:

podman pull ghcr.io/itsdnns/docsight:latest

Rootless networking issues

If DOCSight cannot reach your modem (on the same LAN), check that Podman's rootless network mode allows LAN access. On some systems you may need to add:

[Container]
...
Network=host

Note: Network=host bypasses port mapping, so DOCSight will be available directly on port 8765.