py-docker-admin 0.6.2

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 Folder Configuration

The persistent_folder feature allows you to automatically set up and manage persistent storage for Docker containers. This is particularly useful for databases, application data, or any service that requires data persistence across container restarts and updates.

How It Works

1. Creates host directory - Ensures the specified host directory exists (creates it if it doesn't)
2. Copies initial content - Optionally copies files or directories to the host directory before deployment
3. Mounts to container - The directory is mounted as a volume in the Docker container

Configuration

Add persistent_folder to your stack configuration in config.yaml:

stacks:
  - name: myapp
    compose_file: ./docker-compose.yml
    env_file: ./docker-compose.env
    persistent_folder:
      mount_name: app_data          # Must match volume name in docker-compose.yml
      host_directory: /var/app_data  # Absolute path on host system
      contents: ./initial_data      # Optional: file/dir to copy to host_directory

Docker Compose Integration

The mount_name must match a volume name defined in your docker-compose.yml:

version: '3.8'

services:
  myapp:
    image: myapp:latest
    volumes:
      - app_data:/app/data  # This matches the mount_name in config

volumes:
  app_data:  # Volume name that matches mount_name
    driver: local

Configuration Options

• mount_name (required): Name of the volume in your docker-compose.yml file
• host_directory (required): Absolute path on the host system where data will be stored
• contents (optional): Path to files or directories to copy to the host_directory before deployment

Example Use Cases

Database persistence:

stacks:
  - name: postgres-db
    compose_file: ./postgres-compose.yml
    persistent_folder:
      mount_name: pg_data
      host_directory: /var/persistent/postgres
      contents: ./initial_db_setup

Application data:

stacks:
  - name: web-app
    compose_file: ./webapp-compose.yml
    persistent_folder:
      mount_name: app_storage
      host_directory: /var/www/app_data

This ensures your container data persists even when containers are recreated or updated, providing reliable data storage across deployments.

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.