Skip to content

base system

Jump to bottom
Bibo Hao edited this page Jul 2, 2026 · 1 revision

Base System Image Setup (Atom & Base)

This module describes the core OS setup (atom) and the basic runtime and environment manager setup (base).

1. Atom Image (docker_atom)

The atom image is the foundational layer for all images. It performs minimal OS configuration and sets up general shell utilities.

Dockerfile Highlights

  • Base Image: ubuntu:noble (Ubuntu 24.04 LTS).
  • Environment:
    • DEBIAN_FRONTEND=noninteractive to suppress interactive prompts during package installs.
    • Sane default locale exports (LC_CTYPE=C.UTF-8, LANG=en_US.UTF-8, etc.).
  • Shell Wrapper: By default, commands are run in /bin/bash --login -c.
  • System Profile Hook: Ensures that system profiles in /etc/profile are sourced appropriately and sets check flags (ENTER_PROFILE) to avoid duplicate profiles load cycles.

2. Regional Optimization & Mirroring (script-localize.sh)

To improve build performance in regions with restricted access to global mirrors (e.g. China), the build system provides localization routing scripts under /opt/utils/localize/.

Localization Router (script-localize.sh)

  • Evaluates $1 (first argument) or looks for the $PROFILE_LOCALIZE environment variable. Defaults to "default".
  • Dynamically sources the matching mirror configuration script: /opt/utils/localize/run-config-mirror-${PROFILE_LOCALIZE}.sh.

Available Mirror Profiles:

  • default: Sane defaults; updates local timezone (Asia/Shanghai) and displays standard package manager registries (Apt, Pip, Npm, Go, R).
  • tsinghua: Sets up mirrors hosted by Tsinghua University (TUNA):
    • Apt: Replaces archive/security mirror endpoints with mirrors.tuna.tsinghua.edu.cn.
    • Pip: Configures /etc/pip.conf to target https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/.
    • Node/NPM: Sets registry mirror to https://registry.npmmirror.com for npm, pnpm, yarn, and bun.
    • Go: Exports GOPROXY=https://goproxy.cn.
    • R: Configures CRAN repository target in /etc/R/Rprofile.site.
  • aliyun-pub / aliyun-vpc: Configures Alibaba Cloud public/private mirrors for Apt, Pip, Npm, and Go.
  • tencent-pub / tencent-vpc: Configures Tencent Cloud public/private mirrors for Apt, Pip, Npm, and Go.

3. Utility Scripts (script-utils.sh)

Located at /opt/utils/script-utils.sh inside the container, this library contains functions used for dependency resolution and system cleaning.

Key functions:

  • install_apt <file>: Resolves package list from file, cuts any comments (denoted by %), and runs apt-get install without recommended packages.
  • install_pip <file> / install_conda <file> / install_mamba <file>: Installs libraries using corresponding CLI from clean package list inputs.
  • install__clean: Removes all temporary files, cleans apt-get cache and autoremoves unused dependencies, purges npm cache, runs conda/mamba cleanups, deletes python compiled cache (__pycache__ and *.py[co]), and clears /tmp/. Always invoke this at the end of any setup run.
  • fix_permission <group_id> <directories...>: Recursively grants read-write-execute permissions to a given group ID (default 0 for root/admin processes) to allow multi-user container access.

4. Base Image (docker_base)

The base image inherits from atom and installs tini, micromamba, conda, pip, python, and uv.

Tini Setup (setup_tini)

Downloads the designated architecture-specific tini binary from GitHub and installs it at /usr/bin/tini. It functions as PID 1 to handle signal forwarding and orphan reaping.

Mamba & Conda Bootstrapping

  • setup_mamba: Downloads micromamba from Snakepit and configures /etc/conda/.condarc with the conda-forge channel.
  • setup_conda_with_mamba <version>: Standardizes Python base package installation. It installs conda, pip, and the requested python version directly.

Python Redirection & Replacement (SYS_PY_REPLACE)

If SYS_PY_REPLACE is set to true, the installation script replaces the system's python default to target conda's python:

  1. Locates default OS Python via py3versions.
  2. Replaces the default Python string in /usr/share/python3/debian_defaults.
  3. Injects a .pth file (usr_share.pth) into python's site-packages referencing /usr/share/pyshared and /usr/share/python3/ directories.
  4. Moves OS default dist-packages to root, deletes old system Python directories, and symlinks /usr/lib/python<VER> to Conda's library prefix.
  5. Symlinks /usr/bin/python, /usr/bin/python3, /usr/bin/pip to target Conda's bin folders.

Clone this wiki locally