Metadata-Version: 2.4
Name: py-docker-admin
Version: 0.6.1
Summary: A Python package for automating Docker and Portainer installation
Project-URL: Repository, https://gitlab.com/grenzfall/py-docker-admin
Project-URL: Issues, https://gitlab.com/grenzfall/py-docker-admin/-/issues
Project-URL: Documentation, https://gitlab.com/grenzfall/py-docker-admin/-/wikis/home
Author-email: GreenQuark <greenquark@gmx.de>
License: GNU General Public License v3.0
License-File: AUTHORS
License-File: LICENSE
Keywords: automation,cli,devops,docker,portainer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Installation/Setup
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: jinja2>=3.1.6
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Description-Content-Type: text/markdown

# py-docker-admin

[![PyPI version](https://badge.fury.io/py/py-docker-admin.svg)](https://badge.fury.io/py/py-docker-admin)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

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)

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

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

### Development Installation

```bash
# 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

```bash
# 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`):

```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:

```yaml
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.

```yaml
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

```bash
# Create virtual environment
uv venv

# Activate environment
source .venv/bin/activate

# Install development dependencies
uv add pytest ruff
```

### Running Tests

```bash
pytest tests/
```

### Code Style

```bash
# 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](LICENSE) file for the full license text.

Copyright © 2026 GreenQuark <greenquark@gmx.de>

## Contributing

Contributions are welcome! Please open an issue or submit a merge request on our [GitLab repository](https://gitlab.com/grenzfall/py-docker-admin).

## Support

For issues and questions, please use the [GitLab issue tracker](https://gitlab.com/grenzfall/py-docker-admin/-/issues).