Skip to content

install.md

Latest commit

 

History

History
112 lines (76 loc) · 3.36 KB

install.md

File metadata and controls

112 lines (76 loc) · 3.36 KB

PyPNM Docker Install & Usage

Note: Docker workflows are supported on Linux hosts. macOS users should not use these Docker-specific instructions.

PyPNM ships with Docker assets so you can run the API quickly on a workstation, lab host, or VM. This guide covers the common flows:

  • Install the published release image via the helper script.
  • Use the deploy bundle (tarball) directly.
  • Manual steps for hosts without GitHub access.

Table of Contents

Fast path: PyPNM Docker container install

TAG="v1.5.9.0"
PORT=8080

curl -fsSLo install-pypnm-docker-container.sh \
  https://raw.githubusercontent.com/PyPNMApps/PyPNM/main/scripts/install-pypnm-docker-container.sh

chmod +x install-pypnm-docker-container.sh

sudo ./install-pypnm-docker-container.sh --tag ${TAG} --port ${PORT}

What the script does:

  • Downloads the deploy bundle (falls back to tag source if the asset is missing).
  • Seeds deploy/docker/config/system.json and deploy/docker/compose/.env.
  • Pulls ghcr.io/PyPNMApps/pypnm:${TAG} and starts the stack in /opt/pypnm/compose.
  • Prints next steps (logs, reload docs, config-menu).

Update an existing Docker deployment

Use the same helper script to replace an existing PyPNM Docker deployment.

Latest release:

sudo ./install.sh --update

Specific release:

sudo ./install.sh --update v1.5.3.0

What --update does:

  • Stops the existing PyPNM compose stack under the deploy directory.
  • Removes old PyPNM containers.
  • Removes old ghcr.io/PyPNMApps/pypnm:* images from the host.
  • Downloads the requested deploy bundle.
  • Reinitializes the deploy directory.
  • Pulls and starts the requested PyPNM image.

Use this only for PyPNM Docker hosts where replacing the current deployment is intended.

Implementation note:

  • install.sh --update [tag] is the public entrypoint.
  • It delegates to scripts/update-pypnm-docker-container.sh, which then calls the Docker installer helper.

After install (from /opt/pypnm/compose):

sudo docker compose logs -f --tail=200 pypnm-api
curl -I http://127.0.0.1:${PORT}/docs
sudo docker compose run --rm config-menu

# Reload after config changes, this assumes IP/PORT is set as above:
curl -X GET http://127.0.0.1:${PORT}/pypnm/system/webService/reload -H 'accept: application/json'

Deploy bundle flow (tarball)

TAG="v1.5.9.0"
WORKING_DIR="PyPNM-${TAG}"

mkdir -p "${WORKING_DIR}"
cd "${WORKING_DIR}"

wget "https://github.com/PyPNMApps/PyPNM/archive/refs/tags/${TAG}.tar.gz"
tar -xvf "${TAG}.tar.gz" --strip-components=1

cd deploy/docker
./install.sh

cd compose
sudo docker compose pull
sudo docker compose up -d

Edit deploy/docker/config/system.json as needed, then reload the service (curl or sudo docker compose restart pypnm-api).

Manual/no-network notes

  • If the host cannot reach GitHub, copy the deploy/docker/ folder from a clone or a downloaded tarball and run deploy/docker/install.sh.
  • The helper script falls back to the tag archive and then to main if the deploy asset is missing.
  • The runtime config lives in deploy/docker/config/system.json; config-menu and the API share this file.

Need Docker itself first? See Install Docker prerequisites.