<br /> <div align="center">  <h3 align="center">PeiDocker (配 docker)</h3> <p align="center"> Easily automate docker building process without learning much about Dockerfiles.  </p> </div>

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

Custom Script Hooks: Run custom scripts during image build, first run, each time the container starts or when you SSH into the container, without knowing Dockerfiles
Painless Configuration: Quickly setup SSH configurations for multiple users and authentication methods, changing apt repositories, pip repositories, mounts using docker volumes, system-wide proxy, etc.
Dynamic Storage Support: Use external storage in development, and transparently switch to internal storage in deployment
Configure With GUI: Use the modern web interface to create your reusable docker building files without writing Dockerfiles

Examples

Given the below user_config.yml file, PeiDocker will generate a docker-compose.yml file for you, using which you will build two docker images pei-cn-demo:stage-1 and pei-cn-demo:stage-2 with many useful features.

# pei-docker configuration file as demo
# in-container paths are relative to /installation directory

stage_1:
  # input/output image settings
  image:
    base: ubuntu:24.04
    output: pei-cn-demo:stage-1

  # ssh settings
  ssh:
    enable: true

    # you can configure ssh port in container (default is 22 if not set)
    # useful if you want to use network-mode=host, avoid conflicting with host services
    port: 333

    # mapped port on host machine, if given, this port will be mapped to the container SSH port
    host_port: 2222

    # ssh users, the key is user name
    users:
      me:
        password: '123456'

        # using this will add your public key to the container as authorized key, you can also specify a file path
        # pubkey_file: '~' 

        # you can also use inline public key text
        # pubkey_text: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQC...'
        
      root: # allow you to ssh as root
        password: root

  # apt settings
  apt:
    # use 'tuna' or 'aliyun' apt mirror for faster downloads in China
    repo_source: 'aliyun'
    keep_repo_after_build: true # keep the apt source file after build

  # custom scripts
  custom:
    # scripts run during build
    # Scripts can include parameters: 'script.sh --param1=value1 --param2="value with spaces"'
    on_build: 
      - 'stage-1/custom/install-dev-tools.sh' # just an example, you can safely remove this
    
stage_2:

  # input/output image settings
  image:
    output: pei-cn-demo:stage-2

  # dynamic storage settings
  # they define the physical location of `/soft/app`, `/soft/data` and `/soft/workspace` point to, your these paths can be switched among different storage locations, so that you can use external storage in development, and move them to internal storage in deployment
  storage:
    app:  # /soft/app will be kept as part of the image
      type: image
    data: # mounting /your/data/path to /soft/data in container
      type: host
      host_path: /your/data/path
    workspace: # /soft/workspace will be mounted to a docker automatic volume
      type: auto-volume

  # mount external volumes to container
  mount:
    # mounting docker automatic volume to /home/me
    # so that you do not have to commit your docker image everytime some configuration changes
    home_me:
      type: auto-volume   # auto-volume, manual-volume, host
      dst_path: /home/me

  custom:
    # scripts run during build
    # Scripts can include parameters: 'script.sh --param1=value1 --param2="value with spaces"'
    on_build: 
      # install pixi, a lightweight python package manager
      # configure pixi to use tuna mirror in China
      - 'stage-2/system/pixi/install-pixi.bash --pypi-repo=tuna --conda-repo=tuna'

After you build the images, if you start pei-cn-demo:stage-1 or pei-cn-demo:stage-2 with docker compose, you will have fully functional docker containers with the following features:

pei-cn-demo:stage-1 container features

SSH server running on port 333 inside container, mapped to port 2222 on host, with a user me and password 123456, you can also login as root with password root
apt source is switched to aliyun mirror for faster downloads in China
development tools installed via install-dev-tools.sh script, into system dirs

pei-cn-demo:stage-2 container features

includes all features of stage-1
/soft/data is mounted to /your/data/path on host, so you can use external storage in development
/soft/workspace is mounted to a docker automatic volume, so you can use it as a persistent workspace
/home/me is mounted to a docker automatic volume, so during use of the container you can persist your user-specific settings without committing the image
pixi package manager installed, with tuna mirror configured, so you can install python packages easily, via the on_build scripts

You can further customize the user_config.yml file to add more features, mainly using the custom section to run your own scripts during build, first run, container starts or login, so you ONLY need to master bash scripting to maintain your docker images build process, no need to learn Dockerfiles!

For details, please refer to the Documentation

Getting Started

Installation

Option 1: Install via uv (Recommended)

# If you don't have uv yet, see https://docs.astral.sh/uv/getting-started/install/
# Install the pei-docker CLI as a global tool
uv tool install pei-docker

# Upgrade later
uv tool upgrade pei-docker

Alternative (pip/pipx):

# System / virtualenv install
pip install pei-docker

# Isolated user install
pipx 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 (Deprecated in 2.0)

The modern web interface provided an intuitive way to manage PeiDocker projects, but it is not available in 2.0.

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

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

PeiDocker

Install / Use

README