ptctools 0.1.1__tar.gz → 0.2.0__tar.gz

ptctools-0.2.0/CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md - ptctools
+
+## Overview
+
+Portainer Client Tools CLI package for managing Portainer stacks, volumes, and databases from the command line.
+
+## Project Structure
+
+```text
+src/ptctools/
+├── pyproject.toml          # Package config, entry point: ptctools.cli:main
+├── README.md               # User documentation
+└── src/ptctools/
+    ├── __init__.py         # Version: 0.1.1
+    ├── cli.py              # Main click CLI, registers docker + utils groups
+    ├── docker.py           # Docker command group (registers stack, secret, config, volume, db)
+    ├── _portainer.py       # Shared Portainer API utilities (internal)
+    ├── _s3.py              # Shared S3/URI parsing utilities (internal)
+    ├── stack.py            # docker stack deploy command (Swarm-only)
+    ├── secret.py           # docker secret create command (Swarm-only)
+    ├── config.py           # docker config set/get/list/delete commands (Swarm-only)
+    ├── volume.py           # docker volume backup/restore/cp/rm/rename commands
+    ├── db.py               # docker db backup/restore commands
+    └── utils.py            # utils backup/restore commands (local Duplicati)
+```
+
+## CLI Architecture
+
+Uses [click](https://click.palletsprojects.com/) with nested command groups:
+
+```
+ptctools
+├── docker                    # Docker commands (via Portainer Docker proxy)
+│   ├── stack deploy         # Deploy/update stack (Swarm-only)
+│   ├── secret create        # Create Docker secret (Swarm-only)
+│   ├── config set/get/list/delete  # Manage configs (Swarm-only)
+│   ├── volume backup        # Backup volumes to S3 via Duplicati
+│   ├── volume restore       # Restore single volume from S3
+│   ├── volume cp            # Copy between volumes and S3
+│   ├── volume rm            # Remove volume
+│   ├── volume rename        # Rename volume (copy + delete)
+│   ├── db backup            # Backup PostgreSQL via container exec
+│   └── db restore           # Restore PostgreSQL from backup
+├── utils backup             # Local backup to S3 or directory using Duplicati
+├── utils restore            # Local restore from S3 or directory using Duplicati
+└── k8s ...                  # Kubernetes commands (future)
+```
+
+## Environment Variables
+
+All docker commands require `PORTAINER_ACCESS_TOKEN`. Backup commands also use:
+- `S3_ACCESS_KEY`, `S3_SECRET_KEY` - S3 credentials
+- `DUPLICATI_PASSPHRASE` - Optional encryption
+
+## Development
+
+```bash
+# Install in development mode
+uv tool install . --force
+
+# Test CLI
+ptctools --help
+ptctools docker --help
+```
+
+## Adding New Commands
+
+### Adding a Docker subcommand
+1. Create module in `src/ptctools/` with a `cli` click group
+2. Register in `docker.py` via `cli.add_command(module.cli, name="name")`
+3. Use `_portainer.py` for Portainer API calls
+
+### Adding a new top-level group (e.g., k8s)
+1. Create module in `src/ptctools/` with a `cli` click group
+2. Register in `cli.py` via `main.add_command(module.cli, name="name")`

ptctools-0.2.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: ptctools
+Version: 0.2.0
+Summary: Portainer Client Tools - CLI for managing Portainer from client
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: docker==7.1.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ptctools - Portainer Client Tools
+
+CLI for managing Portainer stacks, volume backups, and database operations.
+
+> **Note:** Only tested on Portainer 2.33.6
+
+## Installation
+
+```bash
+# From Git repository
+uv tool install git+https://github.com/tamntlib/ptctools.git
+# or
+uv tool install ptctools --from git+https://github.com/tamntlib/ptctools.git
+
+# From local path
+uv tool install openapi-generator-cli==7.19.0
+openapi-generator-cli generate \
+  -i portainer_openapi.yml \
+  -g python \
+  -o ./src/ptctools/portainer_client \
+  --skip-validate-spec \
+  --additional-properties=generateSourceCodeOnly=true
+uv tool install . --no-cache --reinstall
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORTAINER_URL` | Yes* | Portainer base URL (can also use `-u` flag) |
+| `PORTAINER_ACCESS_TOKEN` | Yes | Portainer API key |
+| `S3_ACCESS_KEY` | For S3 | S3 access key |
+| `S3_SECRET_KEY` | For S3 | S3 secret key |
+| `S3_ENDPOINT` | For S3 | S3/MinIO endpoint URL |
+| `DUPLICATI_PASSPHRASE` | No | Backup encryption passphrase |
+
+\* Required for `docker` commands. Can be provided via `-u` flag instead.
+
+## Usage
+
+```bash
+# Set environment variables
+export PORTAINER_URL=https://portainer.example.com
+export PORTAINER_ACCESS_TOKEN=your-api-key
+export S3_ACCESS_KEY=your-s3-key
+export S3_SECRET_KEY=your-s3-secret
+export S3_ENDPOINT=https://s3.<region>.amazonaws.com
+
+# Stack deployment (Swarm-only)
+ptctools docker stack deploy -n mystack -f compose.yaml
+
+# Secret management (Swarm-only)
+echo "postgresql://user:pass@db:5432/mydb" | ptctools docker secret create db_dsn
+ptctools docker secret create -f /path/to/secret.txt my_secret
+ptctools docker secret create -v "secret-value" my_secret
+
+# Config management (Swarm-only)
+ptctools docker config set -n my-config -d "config content"
+ptctools docker config set -n nginx.conf -f ./nginx.conf
+ptctools docker config set -n my-config -d "new content" --force
+ptctools docker config list
+ptctools docker config get -n my-config
+ptctools docker config delete -n my-config
+
+# Volume backup/restore (uses Duplicati)
+ptctools docker volume backup -v vol1,vol2 -o s3://mybucket
+ptctools docker volume restore -i s3://mybucket/vol1  # volume name derived from URI path
+ptctools docker volume restore -v vol1 -i s3://mybucket/vol1  # explicit volume name
+
+# Volume copy (raw copy using mc/busybox)
+ptctools docker volume cp source dest                         # volume to volume
+ptctools docker volume cp s3://mybucket/path dest              # S3 to volume
+ptctools docker volume cp source s3://mybucket/path            # volume to S3
+
+# Volume management
+ptctools docker volume rm myvolume                             # remove volume (with confirmation)
+ptctools docker volume rm -y myvolume                          # remove without confirmation
+ptctools docker volume rename old_name new_name                # rename volume (copy + delete)
+
+# Database backup/restore (uses minio/mc for S3)
+ptctools docker db backup -c container_id -v db_data \
+  --db-user postgres --db-name mydb -o backup.sql.gz
+ptctools docker db backup -c container_id -v db_data \
+  --db-user postgres --db-name mydb -o s3://mybucket/backups/db.sql.gz
+
+ptctools docker db restore -c container_id -v db_data \
+  --db-user postgres --db-name mydb -i backup.sql.gz
+ptctools docker db restore -c container_id -v db_data \
+  --db-user postgres --db-name mydb -i s3://mybucket/backups/db.sql.gz
+
+# Override PORTAINER_URL with -u flag
+ptctools docker secret create -u https://other.portainer.com -f dsn.txt my_secret
+
+# Utils - local Duplicati operations (no Portainer needed)
+ptctools utils backup --input ./data --output s3://backups/mydata
+ptctools utils restore --input s3://backups/mydata --output ./restored
+
+```
+
+## CLI Structure
+
+```
+ptctools
+├── docker                    # Docker commands (via Portainer Docker proxy)
+│   ├── stack deploy         # Deploy/update stack (Swarm-only)
+│   ├── secret create        # Create Docker secret (Swarm-only)
+│   ├── config set/get/list/delete  # Manage configs (Swarm-only)
+│   ├── volume backup/restore/cp/rm/rename
+│   └── db backup/restore
+├── utils backup/restore     # Local Duplicati operations
+└── k8s ...                  # Kubernetes commands (future)
+```
+
+## Commands
+
+### `ptctools docker stack deploy`
+Deploy or update a Docker Swarm stack in Portainer.
+
+### `ptctools docker secret create`
+Create a Docker Swarm secret. Value can be provided via stdin, file, or command-line argument.
+
+### `ptctools docker config set/get/list/delete`
+Manage Docker Swarm configs via Portainer API.
+
+### `ptctools docker volume backup/restore`
+
+- **backup**: Backup multiple Docker volumes (comma-separated) to S3 using Duplicati container.
+- **restore**: Restore a single Docker volume from S3. Volume name can be specified via `--volume` or derived from the input URI path.
+
+### `ptctools docker volume cp`
+Copy data between volumes and S3 (raw file copy).
+- **volume to volume**: Uses `busybox` with `cp -a`
+- **S3 to volume**: Uses `minio/mc` to download files
+- **volume to S3**: Uses `minio/mc` to upload files
+
+### `ptctools docker volume rm`
+Remove a Docker volume. Use `-y` to skip confirmation, `-f` to force removal.
+
+### `ptctools docker volume rename`
+Rename a volume by copying data to a new volume and deleting the original.
+
+### `ptctools docker db backup/restore`
+Backup/restore PostgreSQL database. Supports both local files and S3 URIs.
+- Uses `pg_dump`/`psql` for database operations
+- Uses `minio/mc` container for S3 transfers
+
+### `ptctools utils backup/restore`
+Local backup/restore operations using Duplicati CLI (docker or local). Does not require Portainer.

ptctools-0.2.0/README.md

@@ -0,0 +1,148 @@
+# ptctools - Portainer Client Tools
+
+CLI for managing Portainer stacks, volume backups, and database operations.
+
+> **Note:** Only tested on Portainer 2.33.6
+
+## Installation
+
+```bash
+# From Git repository
+uv tool install git+https://github.com/tamntlib/ptctools.git
+# or
+uv tool install ptctools --from git+https://github.com/tamntlib/ptctools.git
+
+# From local path
+uv tool install openapi-generator-cli==7.19.0
+openapi-generator-cli generate \
+  -i portainer_openapi.yml \
+  -g python \
+  -o ./src/ptctools/portainer_client \
+  --skip-validate-spec \
+  --additional-properties=generateSourceCodeOnly=true
+uv tool install . --no-cache --reinstall
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PORTAINER_URL` | Yes* | Portainer base URL (can also use `-u` flag) |
+| `PORTAINER_ACCESS_TOKEN` | Yes | Portainer API key |
+| `S3_ACCESS_KEY` | For S3 | S3 access key |
+| `S3_SECRET_KEY` | For S3 | S3 secret key |
+| `S3_ENDPOINT` | For S3 | S3/MinIO endpoint URL |
+| `DUPLICATI_PASSPHRASE` | No | Backup encryption passphrase |
+
+\* Required for `docker` commands. Can be provided via `-u` flag instead.
+
+## Usage
+
+```bash
+# Set environment variables
+export PORTAINER_URL=https://portainer.example.com
+export PORTAINER_ACCESS_TOKEN=your-api-key
+export S3_ACCESS_KEY=your-s3-key
+export S3_SECRET_KEY=your-s3-secret
+export S3_ENDPOINT=https://s3.<region>.amazonaws.com
+
+# Stack deployment (Swarm-only)
+ptctools docker stack deploy -n mystack -f compose.yaml
+
+# Secret management (Swarm-only)
+echo "postgresql://user:pass@db:5432/mydb" | ptctools docker secret create db_dsn
+ptctools docker secret create -f /path/to/secret.txt my_secret
+ptctools docker secret create -v "secret-value" my_secret
+
+# Config management (Swarm-only)
+ptctools docker config set -n my-config -d "config content"
+ptctools docker config set -n nginx.conf -f ./nginx.conf
+ptctools docker config set -n my-config -d "new content" --force
+ptctools docker config list
+ptctools docker config get -n my-config
+ptctools docker config delete -n my-config
+
+# Volume backup/restore (uses Duplicati)
+ptctools docker volume backup -v vol1,vol2 -o s3://mybucket
+ptctools docker volume restore -i s3://mybucket/vol1  # volume name derived from URI path
+ptctools docker volume restore -v vol1 -i s3://mybucket/vol1  # explicit volume name
+
+# Volume copy (raw copy using mc/busybox)
+ptctools docker volume cp source dest                         # volume to volume
+ptctools docker volume cp s3://mybucket/path dest              # S3 to volume
+ptctools docker volume cp source s3://mybucket/path            # volume to S3
+
+# Volume management
+ptctools docker volume rm myvolume                             # remove volume (with confirmation)
+ptctools docker volume rm -y myvolume                          # remove without confirmation
+ptctools docker volume rename old_name new_name                # rename volume (copy + delete)
+
+# Database backup/restore (uses minio/mc for S3)
+ptctools docker db backup -c container_id -v db_data \
+  --db-user postgres --db-name mydb -o backup.sql.gz
+ptctools docker db backup -c container_id -v db_data \
+  --db-user postgres --db-name mydb -o s3://mybucket/backups/db.sql.gz
+
+ptctools docker db restore -c container_id -v db_data \
+  --db-user postgres --db-name mydb -i backup.sql.gz
+ptctools docker db restore -c container_id -v db_data \
+  --db-user postgres --db-name mydb -i s3://mybucket/backups/db.sql.gz
+
+# Override PORTAINER_URL with -u flag
+ptctools docker secret create -u https://other.portainer.com -f dsn.txt my_secret
+
+# Utils - local Duplicati operations (no Portainer needed)
+ptctools utils backup --input ./data --output s3://backups/mydata
+ptctools utils restore --input s3://backups/mydata --output ./restored
+
+```
+
+## CLI Structure
+
+```
+ptctools
+├── docker                    # Docker commands (via Portainer Docker proxy)
+│   ├── stack deploy         # Deploy/update stack (Swarm-only)
+│   ├── secret create        # Create Docker secret (Swarm-only)
+│   ├── config set/get/list/delete  # Manage configs (Swarm-only)
+│   ├── volume backup/restore/cp/rm/rename
+│   └── db backup/restore
+├── utils backup/restore     # Local Duplicati operations
+└── k8s ...                  # Kubernetes commands (future)
+```
+
+## Commands
+
+### `ptctools docker stack deploy`
+Deploy or update a Docker Swarm stack in Portainer.
+
+### `ptctools docker secret create`
+Create a Docker Swarm secret. Value can be provided via stdin, file, or command-line argument.
+
+### `ptctools docker config set/get/list/delete`
+Manage Docker Swarm configs via Portainer API.
+
+### `ptctools docker volume backup/restore`
+
+- **backup**: Backup multiple Docker volumes (comma-separated) to S3 using Duplicati container.
+- **restore**: Restore a single Docker volume from S3. Volume name can be specified via `--volume` or derived from the input URI path.
+
+### `ptctools docker volume cp`
+Copy data between volumes and S3 (raw file copy).
+- **volume to volume**: Uses `busybox` with `cp -a`
+- **S3 to volume**: Uses `minio/mc` to download files
+- **volume to S3**: Uses `minio/mc` to upload files
+
+### `ptctools docker volume rm`
+Remove a Docker volume. Use `-y` to skip confirmation, `-f` to force removal.
+
+### `ptctools docker volume rename`
+Rename a volume by copying data to a new volume and deleting the original.
+
+### `ptctools docker db backup/restore`
+Backup/restore PostgreSQL database. Supports both local files and S3 URIs.
+- Uses `pg_dump`/`psql` for database operations
+- Uses `minio/mc` container for S3 transfers
+
+### `ptctools utils backup/restore`
+Local backup/restore operations using Duplicati CLI (docker or local). Does not require Portainer.

{ptctools-0.1.1 → ptctools-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ptctools"
-version = "0.1.1"
+version = "0.2.0"
 description = "Portainer Client Tools - CLI for managing Portainer from client"
 readme = "README.md"
 requires-python = ">=3.10"

{ptctools-0.1.1 → ptctools-0.2.0}/src/ptctools/cli.py

@@ -3,11 +3,8 @@
 import click
 
 from ptctools import __version__
-from ptctools import stack
-from ptctools import volume
-from ptctools import db
+from ptctools import docker
 from ptctools import utils
-from ptctools import config
 
 
 @click.group()
@@ -17,11 +14,11 @@ def main():
     pass
 
 
-main.add_command(stack.cli, name="stack")
-main.add_command(volume.cli, name="volume")
-main.add_command(db.cli, name="db")
+# Docker commands (via Portainer Docker proxy)
+main.add_command(docker.cli, name="docker")
+
+# Local utility commands (no Portainer needed)
 main.add_command(utils.cli, name="utils")
-main.add_command(config.cli, name="config")
 
 
 if __name__ == "__main__":

{ptctools-0.1.1 → ptctools-0.2.0}/src/ptctools/config.py

@@ -19,6 +19,7 @@ logger = logging.getLogger(__name__)
 
 class ConfigError(PortainerError):
     """Exception for Docker config operations."""
+
     pass
 
 
@@ -29,7 +30,13 @@ def cli():
 
 
 @cli.command("set")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--name", "-n", required=True, help="Config name")
 @click.option("--data", "-d", default=None, help="Config data (string content)")
 @click.option(
@@ -41,9 +48,7 @@ def cli():
     help="Read config data from file",
 )
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
-@click.option(
-    "--force", is_flag=True, help="Replace existing config if it exists"
-)
+@click.option("--force", is_flag=True, help="Replace existing config if it exists")
 def set_config(
     url: str,
     name: str,
@@ -57,13 +62,13 @@ def set_config(
     Examples:
 
         # Create from inline data
-        ptctools config set -u https://portainer.example.com -n my-config -d "config content"
+        ptctools docker config set -u https://portainer.example.com -n my-config -d "config content"
 
         # Create from file
-        ptctools config set -u https://portainer.example.com -n nginx.conf -f ./nginx.conf
+        ptctools docker config set -u https://portainer.example.com -n nginx.conf -f ./nginx.conf
 
         # Replace existing config
-        ptctools config set -u https://portainer.example.com -n my-config -d "new content" --force
+        ptctools docker config set -u https://portainer.example.com -n my-config -d "new content" --force
     """
     # Validate that exactly one of --data or --file is provided
     if data is None and file_path is None:
@@ -88,7 +93,7 @@ def set_config(
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         # Check if config already exists
         existing = None
         for config in client.configs.list():
@@ -119,7 +124,13 @@ def set_config(
 
 
 @cli.command("get")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--name", "-n", required=True, help="Config name")
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
 def get_config_cmd(url: str, name: str, endpoint_id: int):
@@ -138,7 +149,7 @@ def get_config_cmd(url: str, name: str, endpoint_id: int):
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         config = None
         for c in client.configs.list():
             if c.name == name:
@@ -158,7 +169,13 @@ def get_config_cmd(url: str, name: str, endpoint_id: int):
 
 
 @cli.command("list")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
 def list_configs_cmd(url: str, endpoint_id: int):
     """List all Docker Swarm configs."""
@@ -195,7 +212,13 @@ def list_configs_cmd(url: str, endpoint_id: int):
 
 
 @cli.command("delete")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--name", "-n", required=True, help="Config name")
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
 def delete_config_cmd(url: str, name: str, endpoint_id: int):
@@ -211,7 +234,7 @@ def delete_config_cmd(url: str, name: str, endpoint_id: int):
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         config = None
         for c in client.configs.list():
             if c.name == name: