Skip to content

wahl-dev/wrpt

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

59 Commits
.github/workflows
.github/workflows
 
 
docker
docker
 
 
src
src
 
 
.gitignore
.gitignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
CLAUDE.md
CLAUDE.md
 
 
Cargo.lock
Cargo.lock
 
 
Cargo.toml
Cargo.toml
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
cog.toml
cog.toml
 
 

Repository files navigation

WRPT

A minimal Portainer cli built with Rust

About • Roadmap • Installation • Quick Start • Available Commands • Docker • CI/CD Integration • Changelog • License

About

WRPT is a lightweight command-line interface designed to streamline the deployment of Docker-Compose stacks on Portainer.

While its primary focus is on stack deployment, it also provides additional features such as stack/endpoint listing and access control management (wip). WRPT is designed not only for manual usage but also for integration into CI/CD pipelines, making it a versatile tool for automating deployment workflows.

This project draws inspiration from @tortuetorche's work on psuapp/psy.

It is also my first project written in Rust and is under active development, so contributions and feedback are welcome! Stay tuned for new features and improvements.

Roadmap

Here are the planned enhancements and features for WRPT:

  • 🚧 Access Control Management: Enable stack deployments with fine-grained access control, allowing assignment to specific users and/or groups.
  • ✅ Comprehensive Documentation: Write detailed usage guides, including setup instructions for integration into CI/CD pipelines on GitLab and GitHub.
  • ✅ Automated Testing: Write tests to ensure the reliability and stability of the tool.
  • 💭 Kubernetes Compatibility: Extend the tool to support Portainer deployments on Kubernetes environment.
  • ✅ Automated Release Process: Implement CI pipelines to generate changelogs and releases automatically based on versioning and commit history.
  • ✅ Docker Image: Create a Docker image.

Legend

  • ✅ : Completed
  • 🚧 : In progress
  • ⏳ : Pending
  • 💭 : In reflection
  • ❌ : Abandoned

Installation

From crates.io

cargo install wrpt

Docker

docker pull wahl/wrpt:latest

From source

git clone https://github.com/wahl-dev/wrpt.git
cd wrpt
cargo build --release
# Binary available at ./target/release/wrpt

Quick Start

1. Generate a Portainer access token

In your Portainer instance, go to My Account > Access tokens > Add access token.

See the Portainer documentation for more details.

2. Set your environment variables

export PORTAINER_URL="https://portainer.example.com"
export PORTAINER_ACCESS_TOKEN="your-access-token"

3. List your endpoints

wrpt endpoint list

4. List your stacks

wrpt stack list

5. Deploy a stack

wrpt stack deploy my-stack \
  --endpoint 1 \
  --compose-file docker-compose.yml

You can also pass environment variables to the stack:

wrpt stack deploy my-stack \
  --endpoint 1 \
  --compose-file docker-compose.yml \
  --env-file .env

Available Commands

Name Description
stack deploy Deploy/update a stack.
stack remove Remove a stack.
stack list List all stacks based on the current user authorizations.
stack resource-control Display the ResourceControl details of a specific stack.
stack start Starts a stack.
stack stop Stops a stack.
endpoint list List endpoints.
team list List teams.
user list List users.
help Display help message.

Global options

Flag Option Description
-l --url <URL> URL of the Portainer instance.
-A --access-token <ACCESS_TOKEN> Access token of the Portainer instance. Learn how to generate an access token here.
--color <COLOR> When to use terminal colours [default: auto] [possible values: auto, always, never].
--insecure Skip the host's SSL certificate verification, use at your own risk.
-v... Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace.
-q --quiet Do not output any message.
-h --help Print help.

Available environment variables

Environment variable Description
PORTAINER_URL=URL URL of the Portainer instance.
PORTAINER_ACCESS_TOKEN=TOKEN Access token of the Portainer instance.

Commands in details

Stack

Stack deploy
Deploy a stack

Usage: wrpt stack deploy [OPTIONS] --endpoint <ENDPOINT> --compose-file <COMPOSE_FILE> <STACK_NAME>

Arguments:
  <STACK_NAME>  Name of the stack

Options:
  -E, --endpoint <ENDPOINT>          Id of the environment (endpoint) that will be used
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -c, --compose-file <COMPOSE_FILE>  Path to docker compose/stack file
  -e, --env-file <ENV_FILE>          Path to a file of environment variables, to be used by the stack
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
      --prune                        Whether to prune unused containers or not
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
      --pull-image                   Force a pulling to current image with the original tag though the image is already the latest
  -h, --help                         Print help
Stack remove
Remove a stack

Usage: wrpt stack remove [OPTIONS] --endpoint <ENDPOINT> <STACK_NAME>

Arguments:
  <STACK_NAME>  Name of the stack

Options:
  -E, --endpoint <ENDPOINT>          Id of the environment (endpoint) that will be used
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help
Stack resource-control
Display the ResourceControl details of a specific stack

Usage: wrpt stack resource-control [OPTIONS] --endpoint <ENDPOINT> <STACK_NAME>

Arguments:
  <STACK_NAME>  Name of the stack

Options:
  -E, --endpoint <ENDPOINT>          Id of the environment (endpoint) that will be used
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help
Stack start
Starts a stack

Usage: wrpt stack start [OPTIONS] --endpoint <ENDPOINT> <STACK_NAME>

Arguments:
  <STACK_NAME>  Name of the stack

Options:
  -E, --endpoint <ENDPOINT>          Id of the environment (endpoint) that will be used
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help
Stack stop
Stops a stack

Usage: wrpt stack stop [OPTIONS] --endpoint <ENDPOINT> <STACK_NAME>

Arguments:
  <STACK_NAME>  Name of the stack

Options:
  -E, --endpoint <ENDPOINT>          Id of the environment (endpoint) that will be used
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help
Stack list
List all stacks based on the current user authorizations

Usage: wrpt stack list [OPTIONS]

Options:
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help

Endpoint

Endpoint list
List endpoints

Usage: wrpt endpoint list [OPTIONS]

Options:
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help

Team

Team list
List teams

Usage: wrpt team list [OPTIONS]

Options:
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help

User

User list
List users

Usage: wrpt user list [OPTIONS]

Options:
  -l, --url <URL>                    URL of the Portainer instance
  -A, --access-token <ACCESS_TOKEN>  Access token of the Portainer instance
  -v...                              Increase the verbosity of messages: 1 for normal output, 2 for more verbose output, 3 for debug and 4 for trace
  -q, --quiet                        Do not output any message
      --color <COLOR>                When to use terminal colours [default: auto] [possible values: auto, always, never]
  -h, --help                         Print help

Docker

WRPT is also available as a Docker image for easier usage and integration. The image is hosted on Docker Hub: wahl/wrpt.

Available Tags

The available tags for the Docker image can be found here.

Pull the Docker image

docker pull wahl/wrpt:latest

Example usage

Below is an example of using the Docker image to list stacks:

docker run -it --rm \
  -e PORTAINER_URL="$PORTAINER_URL" \
  -e PORTAINER_ACCESS_TOKEN="$PORTAINER_ACCESS_TOKEN" \
  wahl/wrpt:latest stack list

Notes

  • Replace $PORTAINER_URL and $PORTAINER_ACCESS_TOKEN with your Portainer instance details.

CI/CD Integration

WRPT's Docker image makes it easy to integrate stack deployments into your CI/CD pipelines.

GitHub Actions

Add this workflow to .github/workflows/deploy.yml:

name: Deploy Stack

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    container:
      image: wahl/wrpt:latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Deploy stack
        env:
          PORTAINER_URL: ${{ secrets.PORTAINER_URL }}
          PORTAINER_ACCESS_TOKEN: ${{ secrets.PORTAINER_ACCESS_TOKEN }}
        run: |
          wrpt stack deploy my-stack \
            --endpoint ${{ vars.PORTAINER_ENDPOINT }} \
            --compose-file docker-compose.yml

Required secrets (Settings > Secrets and variables > Actions):

Secret Description
PORTAINER_URL URL of your Portainer instance (e.g. https://portainer.example.com)
PORTAINER_ACCESS_TOKEN Portainer API access token

Required variables (Settings > Secrets and variables > Actions > Variables):

Variable Description
PORTAINER_ENDPOINT ID of the Portainer endpoint to deploy to

GitLab CI

Add this to your .gitlab-ci.yml:

stages:
  - deploy

deploy-stack:
  stage: deploy
  image: wahl/wrpt:latest
  only:
    - main
  script:
    - wrpt stack deploy my-stack
        --endpoint $PORTAINER_ENDPOINT
        --compose-file docker-compose.yml
  variables:
    PORTAINER_URL: $PORTAINER_URL
    PORTAINER_ACCESS_TOKEN: $PORTAINER_ACCESS_TOKEN

Required CI/CD variables (Settings > CI/CD > Variables):

Variable Protected Masked Description
PORTAINER_URL Yes No URL of your Portainer instance
PORTAINER_ACCESS_TOKEN Yes Yes Portainer API access token
PORTAINER_ENDPOINT Yes No ID of the Portainer endpoint

CI/CD Best Practices

  • Never hardcode tokens in your pipeline files. Always use secrets/protected variables.
  • Use --insecure only if necessary (e.g. self-signed certificates in internal environments). Prefer proper SSL certificates.
  • Use -vv for debugging pipeline failures — it enables verbose output to help diagnose issues.
  • Verify your endpoint first by running wrpt endpoint list as a preliminary step to confirm connectivity.
  • Pin the Docker image tag to a specific version (e.g. wahl/wrpt:0.6.3) in production pipelines for reproducible deployments.

Changelog

The changelog is available in the CHANGELOG.md file.

License

The source code of this project is licensed under the MIT license.

See LICENSE file for reference.

About

Wahib's Rust Portainer Toolbox - WRPT

Topics

docker rust cli deployment swarm portainer

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

4 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 11

v0.6.4 Latest
Mar 19, 2026
+ 10 releases

Contributors

Languages