Metadata-Version: 2.4
Name: py-docker-admin
Version: 0.6.2
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 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`:

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

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

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