# 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.