ptctools 0.1.0__tar.gz → 0.2.0__tar.gz

{ptctools-0.1.0 → ptctools-0.2.0}/.gitignore

@@ -206,4 +206,4 @@ marimo/_static/
 marimo/_lsp/
 __marimo__/
 
-portainer_openapi.yml
+.DS_Store

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.