pei-docker 1.0.0

A sophisticated Docker automation framework that transforms YAML configurations into reproducible containerized environments

PeiDocker (配 docker)

Easily automate docker building process without learning much about Dockerfiles.

About The Project

You don't have time to learn Dockerfiles, we get it.

But don't keep your docker images around, they will be messed up eventually. If you ever want to make reproducible docker images but have no patience to learn Dockerfiles and docker-compose, PeiDocker is for you.

PeiDocker (配 docker) helps you script and organize your docker image building process with both CLI and Web GUI interfaces. It streamlines the building process and allows you to customize the image building and running behaviours using shell scripts.

With PeiDocker, you can:

• Use the intuitive Web GUI for visual project configuration
• Build images with SSH support (currently only Ubuntu-based images are supported)
• Configure separate port mappings for system services (stage-1) and applications (stage-2)
• Install packages from public repository mirrors, or via proxy
• Install apps for your container, during or after building, into places such as docker volumes, bind mounts or in-image directory
• Run custom commands during image building, when the container starts, or when you SSH into the container
• Use environment variables with fallback values in configuration files for flexible deployments across different environments
• Export/import projects as ZIP files for easy sharing

For details, please refer to the Documentation

(back to top)

Getting Started

Installation

Option 1: Install from PyPI (Recommended)

pip install pei-docker

Option 2: Install from Source

git clone https://github.com/igamenovoer/PeiDocker.git
cd PeiDocker
pip install -e .

Prerequisites

• Docker and docker-compose installed on your machine
• Python 3.11 or higher

Usage

Web GUI (Recommended for beginners)

Start the web interface for visual project configuration:

# Start GUI on auto-selected port
pei-docker-gui start

# Or specify a custom port
pei-docker-gui start --port 8080

# Load an existing project
pei-docker-gui start --project-dir /path/to/my/project

The web interface provides:

• Visual project configuration with organized tabs
• Real-time validation and error checking
• Project import/export functionality
• Interactive help and tooltips

Command Line Interface

Create a new project:

# Create a new project in ./build or any other directory
pei-docker-cli create -p ./build

# Optional: Create without examples or contrib files
pei-docker-cli create -p ./build --no-with-examples --no-with-contrib

Edit the configuration file user_config.yml in the project directory (e.g.,./build) according to your needs. Generate the docker-compose.yml file in the project directory:

# From within the project directory
cd ./build
pei-docker-cli configure

# Or specify project directory explicitly
pei-docker-cli configure -p ./build

# Optional: Use a different config file
pei-docker-cli configure -p ./build -c my-custom-config.yml

# Optional: Generate full compose file with extended sections
pei-docker-cli configure -p ./build -f

Build the docker images. There are two images to be built, namely stage-1 and stage-2. stage-1 is intended to be a base image, installing system apps using apt install, stage-2 is intended to be a final image based on stage-1, installing custom apps using downloaded packages like .deb. External storage is only available in stage-2.

cd ./build

# Using docker compose to build the images. 
# To see all the output, use --progress=plain
# To cleanly rebuild the images, use --no-cache

# Build the stage-1 image
# By default, the image is named pei-image:stage-1, you can change it in user_config.yml
docker compose build stage-1 --progress=plain

# Build the stage-2 image
# By default, the image is named pei-image:stage-2
docker compose build stage-2 --progress=plain

Run the docker container:

# inside project directory, such as ./build

# Typically you will run the stage-2 container
# You can also up the stage-1 container as well.
docker compose up stage-2

If you have setup SSH in user_config.yml, now you can SSH into the container:

# by default, it will create a user named `me` with password '123456'
# and map the port 2222 to the container's port 22

ssh me@127.0.0.1 -p 2222

That's it, you are good to go.

For more examples, please refer to the Documentation

(back to top)