Skip to content

PyPNM Docker Commands Cheat Sheet

Common commands for administering the PyPNM Docker deployment on a host/VM.

Table Of Contents

Working Directory

All commands below assume:

cd /opt/pypnm/compose

Tip: verify what services exist in your compose bundle:

sudo docker compose config --services

Stack Lifecycle

Start the stack:

sudo docker compose up -d

Stop the stack:

sudo docker compose down

Stop the stack and remove named volumes (deletes stored logs/output/data in volumes):

sudo docker compose down --volumes

Restart only the API service:

sudo docker compose restart pypnm-api

Recreate containers (useful after changing the image tag or ports):

sudo docker compose up -d --force-recreate

Developer Workflow

Local development relies on the same compose services, just executed from your cloned repository:

  1. Clone the repo and run the installer:
git clone https://github.com/PyPNMApps/PyPNM.git
cd PyPNM
./install.sh
  1. Build/test locally via docker-compose.yml helpers:
make docker-up      # docker compose up -d --build
make docker-logs    # follow API logs
make docker-down    # stop + remove volumes
  1. Use the Python tooling (pytest, ruff, etc.) inside .env/ for day-to-day development.

Images And Updates

Pull the image tag referenced by your .env (or docker-compose.yml):

sudo docker compose pull

Show current images in use:

sudo docker compose images

Show container status (compose services only):

sudo docker compose ps

Config Menu

If your compose file includes a config-menu service, run it interactively:

sudo docker compose run --rm -it config-menu

If config-menu is not listed in docker compose config --services, it is not available in the deployed bundle.

Reload the API without a container restart (only if your API exposes this endpoint):

curl -X GET "http://127.0.0.1:${HOST_PORT:-8080}/pypnm/system/webService/reload" -H "accept: application/json"

Logs And Health

Tail API logs:

sudo docker compose logs -f --tail=200 pypnm-api

Follow all logs for the API service (no tail limit):

sudo docker compose logs -f pypnm-api

Quick docs endpoint health check:

curl -I "http://127.0.0.1:${HOST_PORT:-8080}/docs"

Wait for container health to turn healthy:

watch -n 1 "sudo docker ps --format 'table {{.Names}}   {{.Status}} {{.Ports}}' | sed -n '1p;/pypnm-api/p'"

Inspect And Debug

Open a shell in the running API container:

sudo docker exec -it pypnm-api sh

List containers (running only):

sudo docker ps

List containers (all, including stopped):

sudo docker ps -a

List container names only (useful for scripting):

sudo docker ps -a --format "{{.Names}}"

Show effective compose configuration (after env var expansion):

sudo docker compose config

Inspect the container (networking, mounts, env):

sudo docker inspect pypnm-api

Test network reachability from inside the container (HTTP example):

sudo docker exec -it pypnm-api sh -lc "python -c 'import urllib.request; urllib.request.urlopen("http://127.0.0.1:8000/docs").read(); print("OK")'"

If ping is available in the image, you can also do:

sudo docker exec -it pypnm-api ping -c 1 <target-ip>

Cleanup

Remove a specific container:

sudo docker rm -f <container>

Remove all stopped containers only:

sudo docker container prune -f

Remove all containers (running and stopped). This is destructive:

sudo docker rm -f $(sudo docker ps -aq)

Examples: targeted cleanup without touching other projects:

List containers and find old PyPNM instances:

sudo docker ps -a --format "table {{.Names}}    {{.Image}}  {{.Status}}" | grep -i pypnm

Remove only containers whose names start with pypnm:

sudo docker rm -f $(sudo docker ps -a --format "{{.Names}}" | grep '^pypnm')

Remove only containers created from a specific image tag:

sudo docker rm -f $(sudo docker ps -a --filter "ancestor=ghcr.io/PyPNMApps/pypnm:v0.9.48.0" -q)

Remove unused images (dangling):

sudo docker image prune -f

Remove unused images (all unreferenced by any container):

sudo docker image prune -a -f

Prune unused resources (stopped containers, dangling images, unused networks):

sudo docker system prune -f

Aggressive prune (also removes unused images and volumes):

sudo docker system prune -a --volumes -f

List Docker volumes:

sudo docker volume ls

Remove a specific volume:

sudo docker volume rm <volume>

Remove all unused volumes:

sudo docker volume prune -f

Networking Notes

If the API must share host routes directly (for example, to reach modems on local LAN subnets with strict ACLs), configure host networking for the API service and recreate the stack.

1) Edit /opt/pypnm/compose/docker-compose.yml and set under pypnm-api:

network_mode: host

2) Recreate:

cd /opt/pypnm/compose
sudo docker compose down
sudo docker compose up -d

When network_mode: host is enabled, published ports: mappings are ignored because the container shares the host network.