py-docker-admin 0.6.1

A Python package for automating Docker and Portainer installation

py-docker-admin

A Python package for automating Docker and Portainer installation and stack deployment.

Features

• ✅ Install Docker on Debian-based systems
• ✅ Install Portainer CE as a Docker container with auto-restart policy
• ✅ Create admin user in Portainer via API
• ✅ Deploy Docker stacks from compose files
• ✅ YAML configuration with Pydantic validation
• ✅ Command-line interface with Typer
• ✅ Comprehensive error handling
• ✅ Rich logging with color output
• ✅ Automatic startup: Portainer container starts automatically on system boot
• ✅ Reverse proxy support: Configure base URL for Portainer behind reverse proxy

Installation

Recommended: Install via pipx (for end users)

# Install using pipx (recommended for CLI usage)
pipx install py-docker-admin

# Or install using pip
pip install py-docker-admin

Development Installation

# Clone the repository from GitLab
git clone https://gitlab.com/grenzfall/py-docker-admin.git
cd py-docker-admin

# Install using uv (recommended)
uv add .

# Or install using pip in development mode
pip install -e .

Usage

Basic Usage

# Run with default configuration
py-docker-admin

# Or use the short alias
pda

# Use a configuration file
py-docker-admin --config my_config.yaml

# Override admin credentials
py-docker-admin --username admin --password mypassword

# Enable verbose logging
py-docker-admin --verbose

Configuration

Create a YAML configuration file (see example_config.yaml):

docker:
  install: true
  restart_service: true
  add_user_to_group: true

portainer:
  container_name: portainer
  port: 9000
  admin_username: admin
  admin_password: securepassword123
  volume: /var/run/docker.sock:/var/run/docker.sock
  remove_existing: false
  # base_url: /portainer  # Uncomment for reverse proxy support

stacks:
  - name: myapp
    compose_file: ./docker-compose.yml
    env_file: ./docker-compose.env

Reverse Proxy Support

For running Portainer behind a reverse proxy (e.g., Nginx, Apache), use the base_url option:

portainer:
  base_url: /portainer  # Portainer will be accessible at http://your-domain.com/portainer

The base_url must start with a forward slash (e.g., /portainer, /docker-admin). When configured, Portainer container will be started with the --base-url parameter, ensuring proper path handling behind reverse proxies.

--- Persistent Data Management ---

For services that require persistent data storage outside of standard Docker volumes, use the persistent_folder option within a stack configuration. This allows you to map a specific host directory to a service's data volume.

service_name: my_service
persistent_folder:
  mount_name: my_data_volume
  host_directory: /mnt/persistent/my_data # Absolute path on the host machine
  contents: ./initial_data/files # Optional: Copy initial files/directories from here to host_directory

Requirements

• Python 3.12+
• Debian-based Linux system (for Docker installation)
• Docker (will be installed if not present)
• sudo privileges (for Docker installation)

Development

Setup

# Create virtual environment
uv venv

# Activate environment
source .venv/bin/activate

# Install development dependencies
uv add pytest ruff

Running Tests

pytest tests/

Code Style

# Run Ruff linter
ruff check src/

# Format code
ruff format src/

Architecture

py_docker_admin/
├── cli.py                # Command-line interface
├── models.py             # Configuration models
├── docker.py             # Docker installation
├── portainer.py          # Portainer installation & API
├── stack.py              # Stack deployment
├── utils.py              # Utility functions
└── exceptions.py         # Custom exceptions

License

GNU General Public License v3.0 (GPL-3.0)

This project is licensed under the GNU General Public License version 3.0. See the LICENSE file for the full license text.

Copyright © 2026 GreenQuark [e-mail]

Contributing

Contributions are welcome! Please open an issue or submit a merge request on our GitLab repository.

Support

For issues and questions, please use the GitLab issue tracker.