From c1ffc080087a87252f505051179a6afbb80fc245 Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 20:24:18 +0800
Subject: [PATCH 1/8] re-org folders

---
 .github/workflows/build.yml                   |   6 +-
 app/README.md                                 | 179 -----------------
 pkg/README.md                                 |  35 ++++
 {src => pkg}/aloha/__init__.py                |   0
 {src => pkg}/aloha/_version.py                |   0
 {src => pkg}/aloha/base.py                    |   0
 .../aloha/config}/__init__.py                 |   0
 {src => pkg}/aloha/config/hocon.py            |   0
 {src => pkg}/aloha/config/paths.py            |   0
 .../api => pkg/aloha/db}/__init__.py          |   0
 {src => pkg}/aloha/db/base.py                 |   0
 {src => pkg}/aloha/db/duckdb.py               |   0
 {src => pkg}/aloha/db/elasticsearch.py        |   0
 {src => pkg}/aloha/db/kafka.py                |   0
 {src => pkg}/aloha/db/mongo.py                |   0
 {src => pkg}/aloha/db/mysql.py                |   0
 {src => pkg}/aloha/db/oracle.py               |   0
 {src => pkg}/aloha/db/postgres.py             |   0
 {src => pkg}/aloha/db/redis.py                |   0
 {src => pkg}/aloha/db/sqlite.py               |   0
 .../config => pkg/aloha/encrypt}/__init__.py  |   0
 {src => pkg}/aloha/encrypt/aes.py             |   0
 {src => pkg}/aloha/encrypt/hash.py            |   0
 {src => pkg}/aloha/encrypt/jwt.py             |   0
 {src => pkg}/aloha/encrypt/rsa.py             |   0
 {src => pkg}/aloha/encrypt/vault/__init__.py  |   0
 {src => pkg}/aloha/encrypt/vault/base.py      |   0
 {src => pkg}/aloha/encrypt/vault/cyberark.py  |   0
 {src => pkg}/aloha/encrypt/vault/plain.py     |   0
 {src => pkg}/aloha/logger/__init__.py         |   0
 {src => pkg}/aloha/logger/handler.py          |   0
 {src => pkg}/aloha/logger/logger.py           |   0
 .../aloha/db => pkg/aloha/script}/__init__.py |   0
 {src => pkg}/aloha/script/base.py             |   0
 {src => pkg}/aloha/script/compile.py          |   0
 {src => pkg}/aloha/script/info.py             |   0
 {src => pkg}/aloha/script/start.py            |   0
 {src => pkg}/aloha/service/__init__.py        |   0
 .../aloha/service/api}/__init__.py            |   0
 {src => pkg}/aloha/service/api/v0.py          |   0
 {src => pkg}/aloha/service/api/v1.py          |   0
 {src => pkg}/aloha/service/api/v2.py          |   0
 {src => pkg}/aloha/service/app.py             |   0
 {src => pkg}/aloha/service/http/__init__.py   |   0
 .../aloha/service/http/base_api_client.py     |   0
 .../aloha/service/http/base_api_handler.py    |   0
 {src => pkg}/aloha/service/http/files.py      |   0
 .../aloha/service/http/plain_http_handler.py  |   0
 .../aloha/service/openapi/__init__.py         |   0
 {src => pkg}/aloha/service/openapi/client.py  |   0
 {src => pkg}/aloha/service/web.py             |   0
 {src => pkg}/aloha/settings.py                |   0
 .../script => pkg/aloha/testing}/__init__.py  |   0
 {src => pkg}/aloha/testing/service_v1.py      |   0
 {src => pkg}/aloha/testing/service_v2.py      |   0
 {src => pkg}/aloha/testing/unit.py            |   0
 .../api => pkg/aloha/time}/__init__.py        |   0
 {src => pkg}/aloha/time/timeout_async.py      |   0
 {src => pkg}/aloha/time/timeout_asyncio.py    |   0
 {src => pkg}/aloha/time/timeout_signal.py     |   0
 .../testing => pkg/aloha/util}/__init__.py    |   0
 {src => pkg}/aloha/util/html.py               |   0
 {src => pkg}/aloha/util/json.py               |   0
 {src => pkg}/aloha/util/random.py             |   0
 {src => pkg}/aloha/util/sys_cuda.py           |   0
 {src => pkg}/aloha/util/sys_gpu.py            |   0
 {src => pkg}/aloha/util/sys_info.py           |   0
 {src => pkg}/setup.py                         |   0
 src/README.md                                 | 188 ++++++++++++++++--
 src/{aloha/time => app_common}/__init__.py    |   0
 .../util => app_common/api}/__init__.py       |   0
 .../api/api_common_query_postgres.py          |   0
 .../app_common/api/api_common_sys_info.py     |   0
 {app => src}/app_common/api/api_multipart.py  |   0
 {app => src}/app_common/debug.py              |   0
 {app => src}/app_common/main.py               |   0
 {app => src}/main.py                          |   0
 {app => src}/requirements.txt                 |   0
 {app => src}/resource/config/deploy-DEV.conf  |   0
 {app => src}/resource/config/main.conf        |   0
 tool/app-demo.Dockerfile                      |   3 +-
 tool/cicd/docker-compose.app-demo.DEV.yml     |   9 +-
 tool/dev-demo.Dockerfile                      |   2 +-
 83 files changed, 209 insertions(+), 213 deletions(-)
 delete mode 100644 app/README.md
 create mode 100644 pkg/README.md
 rename {src => pkg}/aloha/__init__.py (100%)
 rename {src => pkg}/aloha/_version.py (100%)
 rename {src => pkg}/aloha/base.py (100%)
 rename {app/app_common => pkg/aloha/config}/__init__.py (100%)
 rename {src => pkg}/aloha/config/hocon.py (100%)
 rename {src => pkg}/aloha/config/paths.py (100%)
 rename {app/app_common/api => pkg/aloha/db}/__init__.py (100%)
 rename {src => pkg}/aloha/db/base.py (100%)
 rename {src => pkg}/aloha/db/duckdb.py (100%)
 rename {src => pkg}/aloha/db/elasticsearch.py (100%)
 rename {src => pkg}/aloha/db/kafka.py (100%)
 rename {src => pkg}/aloha/db/mongo.py (100%)
 rename {src => pkg}/aloha/db/mysql.py (100%)
 rename {src => pkg}/aloha/db/oracle.py (100%)
 rename {src => pkg}/aloha/db/postgres.py (100%)
 rename {src => pkg}/aloha/db/redis.py (100%)
 rename {src => pkg}/aloha/db/sqlite.py (100%)
 rename {src/aloha/config => pkg/aloha/encrypt}/__init__.py (100%)
 rename {src => pkg}/aloha/encrypt/aes.py (100%)
 rename {src => pkg}/aloha/encrypt/hash.py (100%)
 rename {src => pkg}/aloha/encrypt/jwt.py (100%)
 rename {src => pkg}/aloha/encrypt/rsa.py (100%)
 rename {src => pkg}/aloha/encrypt/vault/__init__.py (100%)
 rename {src => pkg}/aloha/encrypt/vault/base.py (100%)
 rename {src => pkg}/aloha/encrypt/vault/cyberark.py (100%)
 rename {src => pkg}/aloha/encrypt/vault/plain.py (100%)
 rename {src => pkg}/aloha/logger/__init__.py (100%)
 rename {src => pkg}/aloha/logger/handler.py (100%)
 rename {src => pkg}/aloha/logger/logger.py (100%)
 rename {src/aloha/db => pkg/aloha/script}/__init__.py (100%)
 rename {src => pkg}/aloha/script/base.py (100%)
 rename {src => pkg}/aloha/script/compile.py (100%)
 rename {src => pkg}/aloha/script/info.py (100%)
 rename {src => pkg}/aloha/script/start.py (100%)
 rename {src => pkg}/aloha/service/__init__.py (100%)
 rename {src/aloha/encrypt => pkg/aloha/service/api}/__init__.py (100%)
 rename {src => pkg}/aloha/service/api/v0.py (100%)
 rename {src => pkg}/aloha/service/api/v1.py (100%)
 rename {src => pkg}/aloha/service/api/v2.py (100%)
 rename {src => pkg}/aloha/service/app.py (100%)
 rename {src => pkg}/aloha/service/http/__init__.py (100%)
 rename {src => pkg}/aloha/service/http/base_api_client.py (100%)
 rename {src => pkg}/aloha/service/http/base_api_handler.py (100%)
 rename {src => pkg}/aloha/service/http/files.py (100%)
 rename {src => pkg}/aloha/service/http/plain_http_handler.py (100%)
 rename {src => pkg}/aloha/service/openapi/__init__.py (100%)
 rename {src => pkg}/aloha/service/openapi/client.py (100%)
 rename {src => pkg}/aloha/service/web.py (100%)
 rename {src => pkg}/aloha/settings.py (100%)
 rename {src/aloha/script => pkg/aloha/testing}/__init__.py (100%)
 rename {src => pkg}/aloha/testing/service_v1.py (100%)
 rename {src => pkg}/aloha/testing/service_v2.py (100%)
 rename {src => pkg}/aloha/testing/unit.py (100%)
 rename {src/aloha/service/api => pkg/aloha/time}/__init__.py (100%)
 rename {src => pkg}/aloha/time/timeout_async.py (100%)
 rename {src => pkg}/aloha/time/timeout_asyncio.py (100%)
 rename {src => pkg}/aloha/time/timeout_signal.py (100%)
 rename {src/aloha/testing => pkg/aloha/util}/__init__.py (100%)
 rename {src => pkg}/aloha/util/html.py (100%)
 rename {src => pkg}/aloha/util/json.py (100%)
 rename {src => pkg}/aloha/util/random.py (100%)
 rename {src => pkg}/aloha/util/sys_cuda.py (100%)
 rename {src => pkg}/aloha/util/sys_gpu.py (100%)
 rename {src => pkg}/aloha/util/sys_info.py (100%)
 rename {src => pkg}/setup.py (100%)
 rename src/{aloha/time => app_common}/__init__.py (100%)
 rename src/{aloha/util => app_common/api}/__init__.py (100%)
 rename {app => src}/app_common/api/api_common_query_postgres.py (100%)
 rename {app => src}/app_common/api/api_common_sys_info.py (100%)
 rename {app => src}/app_common/api/api_multipart.py (100%)
 rename {app => src}/app_common/debug.py (100%)
 rename {app => src}/app_common/main.py (100%)
 rename {app => src}/main.py (100%)
 rename {app => src}/requirements.txt (100%)
 rename {app => src}/resource/config/deploy-DEV.conf (100%)
 rename {app => src}/resource/config/main.conf (100%)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index cd68bc9..1b5aff6 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -27,7 +27,7 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: "3.13"
-      - run: pip install ruff && ruff check ./src
+      - run: pip install ruff && ruff check ./pkg ./src
 
   job-semgrep:
     runs-on: ubuntu-latest
@@ -56,7 +56,7 @@ jobs:
       - name: pip-install-test
         run: |
           sudo pip3 install -UI pip && sudo pip3 install -UI build setuptools wheel twine pyOpenSSL
-          cd src
+          cd pkg
           sudo python3 -m build
           pip3 install ./dist/*.tar.gz
           aloha info
@@ -67,7 +67,7 @@ jobs:
           TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
           TWINE_PASSWORD_TEST: ${{ secrets.TWINE_PASSWORD_TEST }}
         run: |
-          env | sort -f && cd src && ls -alh
+          env | sort -f && cd pkg && ls -alh
           sudo python3 -c "import fcntl; fcntl.fcntl(1, fcntl.F_SETFL, 0)"
           sudo python3 -m build
           ls -alh ./dist
diff --git a/app/README.md b/app/README.md
deleted file mode 100644
index 3032011..0000000
--- a/app/README.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# App Demo
-
-Using `aloha` to develop your project - a boilerplate/template project.
-
-## Overview
-
-This project provides a containerized development environment using Docker and Docker Compose. It sets up a complete development workspace with all necessary dependencies pre-installed, allowing you to focus on writing code rather than configuring your environment.
-
-### Key Components
-
-- **Docker**: Containerization platform that packages applications with all their dependencies
-- **Docker Compose**: Tool for defining and running multi-container Docker applications
-- **Development Container**: A pre-configured environment with Python, Node.js, and database clients
-
-## How to quickly setup and start DEV environment
-
-### Prerequisites
-
-Before getting started, ensure you have the following installed:
-
-- Docker Engine
-- Docker Compose
-- Git (for cloning the repository)
-
-You can verify Docker installation by running:
-
-```bash
-docker --version
-docker-compose --version
-```
-
-### Step 1: Launch the Development Environment
-
-Run this command in your terminal:
-
-```bash
-./tool/cicd/run-dev.sh up
-```
-
-**What happens when you run this command:**
-
-1. **Port Availability Check**: The script first verifies that the required ports are not already in use on your system. The ports are dynamically assigned based on your user ID (UID) to avoid conflicts with other developers.
-
-2. **Docker Image Build**: If the Docker image doesn't exist yet, Docker Compose will build it using:
-   - `tool/cicd/docker-compose.app-demo.DEV.yml`: Defines the container configuration
-   - `tool/dev-demo.Dockerfile`: Specifies how to build the Docker image
-
-   The build process includes:
-   - Installing Node.js package manager (pnpm)
-   - Setting up Python with JupyterLab
-   - Installing project dependencies from `app/requirements.txt`
-   - Adding PostgreSQL database client tools
-
-3. **Container Start**: Docker Compose starts the container with the following features:
-   - **Volume Mounts**: Your local code directories are mounted into the container, enabling live development (changes on your host are immediately visible in the container):
-     - `doc/` → `/root/doc`
-     - `notebook/` → `/root/notebook`
-     - `src/` → `/root/src`
-     - `app/` → `/root/app`
-   - **Port Forwarding**: Exposes ports for your application and web interface
-   - **Persistent Process**: The container runs `tail -f /dev/null` to stay active
-
-### Step 2: Enter the Development Container
-
-Once the environment is running, execute:
-
-```bash
-./tool/cicd/run-dev.sh enter
-```
-
-**What this command does:**
-
-- Uses `docker exec -it` to create an interactive terminal session
-- Attaches you to the running container with a bash shell
-- You'll be logged in as the root user inside the container
-- Your working directory will be `/root`
-
-**What you can do inside the container:**
-
-- Run Python scripts and applications
-- Use JupyterLab for interactive development
-- Install additional packages with pip or npm
-- Access the PostgreSQL database using the client tools
-- Edit files (changes will be reflected on your host machine)
-
-### Step 3: Manage the Environment
-
-The `run-dev.sh` script provides several commands to manage your development environment:
-
-| Command                          | Description                                 |
-| -------------------------------- | ------------------------------------------- |
-| `./tool/cicd/run-dev.sh up`      | Start or create the development environment |
-| `./tool/cicd/run-dev.sh restart` | Restart the running container               |
-| `./tool/cicd/run-dev.sh logs`    | View and follow container logs              |
-| `./tool/cicd/run-dev.sh enter`   | Access the container's bash shell           |
-| `./tool/cicd/run-dev.sh down`    | Stop and remove the container               |
-
-### Understanding the Port Assignment
-
-The script dynamically assigns ports to avoid conflicts:
-
-- **Base App Port**: 30000 (as specified in the `run-dev.sh`)+ your UID
-- **Base Web Port**: 33000 (as specified in the `run-dev.sh`)+ your UID
-
-Your specific ports will be displayed when you run any `run-dev.sh` command:
-
-```
-----------------------------------------
-User:            yourusername (UID: 1000)
-Project Name:    dev-app-demo-yourusername
-Container:       dev-app-demo-yourusername
-App Port Expose: 31000
-Web Port Expose: 34000
-Action:          up
-Compose:         /path/to/docker-compose.app-demo.DEV.yml
-----------------------------------------
-```
-
-### Tearing Down the Environment
-
-When you're done working, you can stop and remove the container:
-
-```bash
-./tool/cicd/run-dev.sh down
-```
-
-**Note:** This command only removes the container, not the Docker image. If you want to reclaim disk space by removing the image as well, run:
-
-```bash
-docker rmi $(docker images | grep dev-app-demo | awk '{print $3}')
-```
-
-## Project Structure
-
-```
-aloha-python/
-├── app/                    # Application code
-│   ├── main.py            # Main application entry point
-│   ├── requirements.txt   # Python dependencies
-│   └── app_common/        # Common application utilities
-├── src/                    # Source code for the aloha library
-├── doc/                    # Documentation files
-├── notebook/               # Jupyter notebooks
-└── tool/                   # Development tools
-    ├── cicd/              # CI/CD scripts and configs
-    │   ├── run-dev.sh     # Main development environment script
-    │   └── docker-compose.app-demo.DEV.yml
-    ├── dev-demo.Dockerfile
-    └── app-demo.Dockerfile
-```
-
-## Troubleshooting
-
-### "Port is already in use" error
-
-If you see this error, another process is using the assigned ports. You can:
-
-1. Identify and stop the conflicting process
-2. Work with a system administrator to free up the ports
-
-### Container won't start
-
-- Check Docker logs: `./tool/cicd/run-dev.sh logs`
-- Ensure Docker service is running: `systemctl status docker` (Linux) or check Docker Desktop (Windows/macOS)
-
-### Changes not reflecting
-
-- Verify your files are in the mounted directories
-- Check that you're editing files on your host machine (not just inside the container)
-- Restart any running services inside the container if needed
-
-## Next Steps
-
-Once inside the container, you can:
-
-1. Explore the `app/` directory to understand the application structure
-2. Check out the Jupyter notebooks in the `notebook/` directory
-3. Review the documentation in the `doc/` directory
-4. Start developing your application!
diff --git a/pkg/README.md b/pkg/README.md
new file mode 100644
index 0000000..10342a5
--- /dev/null
+++ b/pkg/README.md
@@ -0,0 +1,35 @@
+# Aloha
+
+## What is it?
+
+`aloha` is a versatile Python utility package for building microservices.
+
+[![License](https://img.shields.io/github/license/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/blob/main/LICENSE)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/LabNow-ai/aloha-python/build.yml?branch=main)](https://github.com/LabNow-ai/aloha-python/actions)
+[![Join the Gitter Chat](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/LabNow-ai/)
+[![PyPI version](https://img.shields.io/pypi/v/aloha)](https://pypi.python.org/pypi/aloha/)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/aloha)](https://pepy.tech/badge/aloha/)
+[![Code Activity](https://img.shields.io/github/commit-activity/m/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/pulse)
+[![Recent Code Update](https://img.shields.io/github/last-commit/LabNow-ai/aloha-python.svg)](https://github.com/LabNow-ai/aloha-python/stargazers)
+
+Please generously STAR★ our project or donate to us!
+[![GitHub Starts](https://img.shields.io/github/stars/LabNow-ai/aloha-python.svg?label=Stars&style=social)](https://github.com/LabNow-ai/aloha-python/stargazers)
+
+- For questions, try DeepWiki: [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/LabNow-ai/aloha-python)
+
+- To contribute or talk to a human: [![Open an Issue on GitHub](https://img.shields.io/github/issues/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/issues) [![Join the Discord Chat](https://img.shields.io/badge/Discuss_on-Discord-green)](https://discord.gg/kHUzgQxgbJ)
+
+## Getting started
+
+Refer to 📚 [Document](https://aloha-python.readthedocs.io/) & [中文文档](https://aloha-python.readthedocs.io/zh-cn/main/) for detailed introduction.
+
+```shell
+pip install aloha[all]
+```
+
+And then:
+
+```python
+from aloha.logger import LOG
+from aloha.settings import SETTINGS as S
+```
diff --git a/src/aloha/__init__.py b/pkg/aloha/__init__.py
similarity index 100%
rename from src/aloha/__init__.py
rename to pkg/aloha/__init__.py
diff --git a/src/aloha/_version.py b/pkg/aloha/_version.py
similarity index 100%
rename from src/aloha/_version.py
rename to pkg/aloha/_version.py
diff --git a/src/aloha/base.py b/pkg/aloha/base.py
similarity index 100%
rename from src/aloha/base.py
rename to pkg/aloha/base.py
diff --git a/app/app_common/__init__.py b/pkg/aloha/config/__init__.py
similarity index 100%
rename from app/app_common/__init__.py
rename to pkg/aloha/config/__init__.py
diff --git a/src/aloha/config/hocon.py b/pkg/aloha/config/hocon.py
similarity index 100%
rename from src/aloha/config/hocon.py
rename to pkg/aloha/config/hocon.py
diff --git a/src/aloha/config/paths.py b/pkg/aloha/config/paths.py
similarity index 100%
rename from src/aloha/config/paths.py
rename to pkg/aloha/config/paths.py
diff --git a/app/app_common/api/__init__.py b/pkg/aloha/db/__init__.py
similarity index 100%
rename from app/app_common/api/__init__.py
rename to pkg/aloha/db/__init__.py
diff --git a/src/aloha/db/base.py b/pkg/aloha/db/base.py
similarity index 100%
rename from src/aloha/db/base.py
rename to pkg/aloha/db/base.py
diff --git a/src/aloha/db/duckdb.py b/pkg/aloha/db/duckdb.py
similarity index 100%
rename from src/aloha/db/duckdb.py
rename to pkg/aloha/db/duckdb.py
diff --git a/src/aloha/db/elasticsearch.py b/pkg/aloha/db/elasticsearch.py
similarity index 100%
rename from src/aloha/db/elasticsearch.py
rename to pkg/aloha/db/elasticsearch.py
diff --git a/src/aloha/db/kafka.py b/pkg/aloha/db/kafka.py
similarity index 100%
rename from src/aloha/db/kafka.py
rename to pkg/aloha/db/kafka.py
diff --git a/src/aloha/db/mongo.py b/pkg/aloha/db/mongo.py
similarity index 100%
rename from src/aloha/db/mongo.py
rename to pkg/aloha/db/mongo.py
diff --git a/src/aloha/db/mysql.py b/pkg/aloha/db/mysql.py
similarity index 100%
rename from src/aloha/db/mysql.py
rename to pkg/aloha/db/mysql.py
diff --git a/src/aloha/db/oracle.py b/pkg/aloha/db/oracle.py
similarity index 100%
rename from src/aloha/db/oracle.py
rename to pkg/aloha/db/oracle.py
diff --git a/src/aloha/db/postgres.py b/pkg/aloha/db/postgres.py
similarity index 100%
rename from src/aloha/db/postgres.py
rename to pkg/aloha/db/postgres.py
diff --git a/src/aloha/db/redis.py b/pkg/aloha/db/redis.py
similarity index 100%
rename from src/aloha/db/redis.py
rename to pkg/aloha/db/redis.py
diff --git a/src/aloha/db/sqlite.py b/pkg/aloha/db/sqlite.py
similarity index 100%
rename from src/aloha/db/sqlite.py
rename to pkg/aloha/db/sqlite.py
diff --git a/src/aloha/config/__init__.py b/pkg/aloha/encrypt/__init__.py
similarity index 100%
rename from src/aloha/config/__init__.py
rename to pkg/aloha/encrypt/__init__.py
diff --git a/src/aloha/encrypt/aes.py b/pkg/aloha/encrypt/aes.py
similarity index 100%
rename from src/aloha/encrypt/aes.py
rename to pkg/aloha/encrypt/aes.py
diff --git a/src/aloha/encrypt/hash.py b/pkg/aloha/encrypt/hash.py
similarity index 100%
rename from src/aloha/encrypt/hash.py
rename to pkg/aloha/encrypt/hash.py
diff --git a/src/aloha/encrypt/jwt.py b/pkg/aloha/encrypt/jwt.py
similarity index 100%
rename from src/aloha/encrypt/jwt.py
rename to pkg/aloha/encrypt/jwt.py
diff --git a/src/aloha/encrypt/rsa.py b/pkg/aloha/encrypt/rsa.py
similarity index 100%
rename from src/aloha/encrypt/rsa.py
rename to pkg/aloha/encrypt/rsa.py
diff --git a/src/aloha/encrypt/vault/__init__.py b/pkg/aloha/encrypt/vault/__init__.py
similarity index 100%
rename from src/aloha/encrypt/vault/__init__.py
rename to pkg/aloha/encrypt/vault/__init__.py
diff --git a/src/aloha/encrypt/vault/base.py b/pkg/aloha/encrypt/vault/base.py
similarity index 100%
rename from src/aloha/encrypt/vault/base.py
rename to pkg/aloha/encrypt/vault/base.py
diff --git a/src/aloha/encrypt/vault/cyberark.py b/pkg/aloha/encrypt/vault/cyberark.py
similarity index 100%
rename from src/aloha/encrypt/vault/cyberark.py
rename to pkg/aloha/encrypt/vault/cyberark.py
diff --git a/src/aloha/encrypt/vault/plain.py b/pkg/aloha/encrypt/vault/plain.py
similarity index 100%
rename from src/aloha/encrypt/vault/plain.py
rename to pkg/aloha/encrypt/vault/plain.py
diff --git a/src/aloha/logger/__init__.py b/pkg/aloha/logger/__init__.py
similarity index 100%
rename from src/aloha/logger/__init__.py
rename to pkg/aloha/logger/__init__.py
diff --git a/src/aloha/logger/handler.py b/pkg/aloha/logger/handler.py
similarity index 100%
rename from src/aloha/logger/handler.py
rename to pkg/aloha/logger/handler.py
diff --git a/src/aloha/logger/logger.py b/pkg/aloha/logger/logger.py
similarity index 100%
rename from src/aloha/logger/logger.py
rename to pkg/aloha/logger/logger.py
diff --git a/src/aloha/db/__init__.py b/pkg/aloha/script/__init__.py
similarity index 100%
rename from src/aloha/db/__init__.py
rename to pkg/aloha/script/__init__.py
diff --git a/src/aloha/script/base.py b/pkg/aloha/script/base.py
similarity index 100%
rename from src/aloha/script/base.py
rename to pkg/aloha/script/base.py
diff --git a/src/aloha/script/compile.py b/pkg/aloha/script/compile.py
similarity index 100%
rename from src/aloha/script/compile.py
rename to pkg/aloha/script/compile.py
diff --git a/src/aloha/script/info.py b/pkg/aloha/script/info.py
similarity index 100%
rename from src/aloha/script/info.py
rename to pkg/aloha/script/info.py
diff --git a/src/aloha/script/start.py b/pkg/aloha/script/start.py
similarity index 100%
rename from src/aloha/script/start.py
rename to pkg/aloha/script/start.py
diff --git a/src/aloha/service/__init__.py b/pkg/aloha/service/__init__.py
similarity index 100%
rename from src/aloha/service/__init__.py
rename to pkg/aloha/service/__init__.py
diff --git a/src/aloha/encrypt/__init__.py b/pkg/aloha/service/api/__init__.py
similarity index 100%
rename from src/aloha/encrypt/__init__.py
rename to pkg/aloha/service/api/__init__.py
diff --git a/src/aloha/service/api/v0.py b/pkg/aloha/service/api/v0.py
similarity index 100%
rename from src/aloha/service/api/v0.py
rename to pkg/aloha/service/api/v0.py
diff --git a/src/aloha/service/api/v1.py b/pkg/aloha/service/api/v1.py
similarity index 100%
rename from src/aloha/service/api/v1.py
rename to pkg/aloha/service/api/v1.py
diff --git a/src/aloha/service/api/v2.py b/pkg/aloha/service/api/v2.py
similarity index 100%
rename from src/aloha/service/api/v2.py
rename to pkg/aloha/service/api/v2.py
diff --git a/src/aloha/service/app.py b/pkg/aloha/service/app.py
similarity index 100%
rename from src/aloha/service/app.py
rename to pkg/aloha/service/app.py
diff --git a/src/aloha/service/http/__init__.py b/pkg/aloha/service/http/__init__.py
similarity index 100%
rename from src/aloha/service/http/__init__.py
rename to pkg/aloha/service/http/__init__.py
diff --git a/src/aloha/service/http/base_api_client.py b/pkg/aloha/service/http/base_api_client.py
similarity index 100%
rename from src/aloha/service/http/base_api_client.py
rename to pkg/aloha/service/http/base_api_client.py
diff --git a/src/aloha/service/http/base_api_handler.py b/pkg/aloha/service/http/base_api_handler.py
similarity index 100%
rename from src/aloha/service/http/base_api_handler.py
rename to pkg/aloha/service/http/base_api_handler.py
diff --git a/src/aloha/service/http/files.py b/pkg/aloha/service/http/files.py
similarity index 100%
rename from src/aloha/service/http/files.py
rename to pkg/aloha/service/http/files.py
diff --git a/src/aloha/service/http/plain_http_handler.py b/pkg/aloha/service/http/plain_http_handler.py
similarity index 100%
rename from src/aloha/service/http/plain_http_handler.py
rename to pkg/aloha/service/http/plain_http_handler.py
diff --git a/src/aloha/service/openapi/__init__.py b/pkg/aloha/service/openapi/__init__.py
similarity index 100%
rename from src/aloha/service/openapi/__init__.py
rename to pkg/aloha/service/openapi/__init__.py
diff --git a/src/aloha/service/openapi/client.py b/pkg/aloha/service/openapi/client.py
similarity index 100%
rename from src/aloha/service/openapi/client.py
rename to pkg/aloha/service/openapi/client.py
diff --git a/src/aloha/service/web.py b/pkg/aloha/service/web.py
similarity index 100%
rename from src/aloha/service/web.py
rename to pkg/aloha/service/web.py
diff --git a/src/aloha/settings.py b/pkg/aloha/settings.py
similarity index 100%
rename from src/aloha/settings.py
rename to pkg/aloha/settings.py
diff --git a/src/aloha/script/__init__.py b/pkg/aloha/testing/__init__.py
similarity index 100%
rename from src/aloha/script/__init__.py
rename to pkg/aloha/testing/__init__.py
diff --git a/src/aloha/testing/service_v1.py b/pkg/aloha/testing/service_v1.py
similarity index 100%
rename from src/aloha/testing/service_v1.py
rename to pkg/aloha/testing/service_v1.py
diff --git a/src/aloha/testing/service_v2.py b/pkg/aloha/testing/service_v2.py
similarity index 100%
rename from src/aloha/testing/service_v2.py
rename to pkg/aloha/testing/service_v2.py
diff --git a/src/aloha/testing/unit.py b/pkg/aloha/testing/unit.py
similarity index 100%
rename from src/aloha/testing/unit.py
rename to pkg/aloha/testing/unit.py
diff --git a/src/aloha/service/api/__init__.py b/pkg/aloha/time/__init__.py
similarity index 100%
rename from src/aloha/service/api/__init__.py
rename to pkg/aloha/time/__init__.py
diff --git a/src/aloha/time/timeout_async.py b/pkg/aloha/time/timeout_async.py
similarity index 100%
rename from src/aloha/time/timeout_async.py
rename to pkg/aloha/time/timeout_async.py
diff --git a/src/aloha/time/timeout_asyncio.py b/pkg/aloha/time/timeout_asyncio.py
similarity index 100%
rename from src/aloha/time/timeout_asyncio.py
rename to pkg/aloha/time/timeout_asyncio.py
diff --git a/src/aloha/time/timeout_signal.py b/pkg/aloha/time/timeout_signal.py
similarity index 100%
rename from src/aloha/time/timeout_signal.py
rename to pkg/aloha/time/timeout_signal.py
diff --git a/src/aloha/testing/__init__.py b/pkg/aloha/util/__init__.py
similarity index 100%
rename from src/aloha/testing/__init__.py
rename to pkg/aloha/util/__init__.py
diff --git a/src/aloha/util/html.py b/pkg/aloha/util/html.py
similarity index 100%
rename from src/aloha/util/html.py
rename to pkg/aloha/util/html.py
diff --git a/src/aloha/util/json.py b/pkg/aloha/util/json.py
similarity index 100%
rename from src/aloha/util/json.py
rename to pkg/aloha/util/json.py
diff --git a/src/aloha/util/random.py b/pkg/aloha/util/random.py
similarity index 100%
rename from src/aloha/util/random.py
rename to pkg/aloha/util/random.py
diff --git a/src/aloha/util/sys_cuda.py b/pkg/aloha/util/sys_cuda.py
similarity index 100%
rename from src/aloha/util/sys_cuda.py
rename to pkg/aloha/util/sys_cuda.py
diff --git a/src/aloha/util/sys_gpu.py b/pkg/aloha/util/sys_gpu.py
similarity index 100%
rename from src/aloha/util/sys_gpu.py
rename to pkg/aloha/util/sys_gpu.py
diff --git a/src/aloha/util/sys_info.py b/pkg/aloha/util/sys_info.py
similarity index 100%
rename from src/aloha/util/sys_info.py
rename to pkg/aloha/util/sys_info.py
diff --git a/src/setup.py b/pkg/setup.py
similarity index 100%
rename from src/setup.py
rename to pkg/setup.py
diff --git a/src/README.md b/src/README.md
index 10342a5..3032011 100644
--- a/src/README.md
+++ b/src/README.md
@@ -1,35 +1,179 @@
-# Aloha
+# App Demo
 
-## What is it?
+Using `aloha` to develop your project - a boilerplate/template project.
 
-`aloha` is a versatile Python utility package for building microservices.
+## Overview
 
-[![License](https://img.shields.io/github/license/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/blob/main/LICENSE)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/LabNow-ai/aloha-python/build.yml?branch=main)](https://github.com/LabNow-ai/aloha-python/actions)
-[![Join the Gitter Chat](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/LabNow-ai/)
-[![PyPI version](https://img.shields.io/pypi/v/aloha)](https://pypi.python.org/pypi/aloha/)
-[![PyPI Downloads](https://img.shields.io/pypi/dm/aloha)](https://pepy.tech/badge/aloha/)
-[![Code Activity](https://img.shields.io/github/commit-activity/m/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/pulse)
-[![Recent Code Update](https://img.shields.io/github/last-commit/LabNow-ai/aloha-python.svg)](https://github.com/LabNow-ai/aloha-python/stargazers)
+This project provides a containerized development environment using Docker and Docker Compose. It sets up a complete development workspace with all necessary dependencies pre-installed, allowing you to focus on writing code rather than configuring your environment.
 
-Please generously STAR★ our project or donate to us!
-[![GitHub Starts](https://img.shields.io/github/stars/LabNow-ai/aloha-python.svg?label=Stars&style=social)](https://github.com/LabNow-ai/aloha-python/stargazers)
+### Key Components
 
-- For questions, try DeepWiki: [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/LabNow-ai/aloha-python)
+- **Docker**: Containerization platform that packages applications with all their dependencies
+- **Docker Compose**: Tool for defining and running multi-container Docker applications
+- **Development Container**: A pre-configured environment with Python, Node.js, and database clients
 
-- To contribute or talk to a human: [![Open an Issue on GitHub](https://img.shields.io/github/issues/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/issues) [![Join the Discord Chat](https://img.shields.io/badge/Discuss_on-Discord-green)](https://discord.gg/kHUzgQxgbJ)
+## How to quickly setup and start DEV environment
 
-## Getting started
+### Prerequisites
 
-Refer to 📚 [Document](https://aloha-python.readthedocs.io/) & [中文文档](https://aloha-python.readthedocs.io/zh-cn/main/) for detailed introduction.
+Before getting started, ensure you have the following installed:
 
-```shell
-pip install aloha[all]
+- Docker Engine
+- Docker Compose
+- Git (for cloning the repository)
+
+You can verify Docker installation by running:
+
+```bash
+docker --version
+docker-compose --version
+```
+
+### Step 1: Launch the Development Environment
+
+Run this command in your terminal:
+
+```bash
+./tool/cicd/run-dev.sh up
+```
+
+**What happens when you run this command:**
+
+1. **Port Availability Check**: The script first verifies that the required ports are not already in use on your system. The ports are dynamically assigned based on your user ID (UID) to avoid conflicts with other developers.
+
+2. **Docker Image Build**: If the Docker image doesn't exist yet, Docker Compose will build it using:
+   - `tool/cicd/docker-compose.app-demo.DEV.yml`: Defines the container configuration
+   - `tool/dev-demo.Dockerfile`: Specifies how to build the Docker image
+
+   The build process includes:
+   - Installing Node.js package manager (pnpm)
+   - Setting up Python with JupyterLab
+   - Installing project dependencies from `app/requirements.txt`
+   - Adding PostgreSQL database client tools
+
+3. **Container Start**: Docker Compose starts the container with the following features:
+   - **Volume Mounts**: Your local code directories are mounted into the container, enabling live development (changes on your host are immediately visible in the container):
+     - `doc/` → `/root/doc`
+     - `notebook/` → `/root/notebook`
+     - `src/` → `/root/src`
+     - `app/` → `/root/app`
+   - **Port Forwarding**: Exposes ports for your application and web interface
+   - **Persistent Process**: The container runs `tail -f /dev/null` to stay active
+
+### Step 2: Enter the Development Container
+
+Once the environment is running, execute:
+
+```bash
+./tool/cicd/run-dev.sh enter
+```
+
+**What this command does:**
+
+- Uses `docker exec -it` to create an interactive terminal session
+- Attaches you to the running container with a bash shell
+- You'll be logged in as the root user inside the container
+- Your working directory will be `/root`
+
+**What you can do inside the container:**
+
+- Run Python scripts and applications
+- Use JupyterLab for interactive development
+- Install additional packages with pip or npm
+- Access the PostgreSQL database using the client tools
+- Edit files (changes will be reflected on your host machine)
+
+### Step 3: Manage the Environment
+
+The `run-dev.sh` script provides several commands to manage your development environment:
+
+| Command                          | Description                                 |
+| -------------------------------- | ------------------------------------------- |
+| `./tool/cicd/run-dev.sh up`      | Start or create the development environment |
+| `./tool/cicd/run-dev.sh restart` | Restart the running container               |
+| `./tool/cicd/run-dev.sh logs`    | View and follow container logs              |
+| `./tool/cicd/run-dev.sh enter`   | Access the container's bash shell           |
+| `./tool/cicd/run-dev.sh down`    | Stop and remove the container               |
+
+### Understanding the Port Assignment
+
+The script dynamically assigns ports to avoid conflicts:
+
+- **Base App Port**: 30000 (as specified in the `run-dev.sh`)+ your UID
+- **Base Web Port**: 33000 (as specified in the `run-dev.sh`)+ your UID
+
+Your specific ports will be displayed when you run any `run-dev.sh` command:
+
+```
+----------------------------------------
+User:            yourusername (UID: 1000)
+Project Name:    dev-app-demo-yourusername
+Container:       dev-app-demo-yourusername
+App Port Expose: 31000
+Web Port Expose: 34000
+Action:          up
+Compose:         /path/to/docker-compose.app-demo.DEV.yml
+----------------------------------------
+```
+
+### Tearing Down the Environment
+
+When you're done working, you can stop and remove the container:
+
+```bash
+./tool/cicd/run-dev.sh down
+```
+
+**Note:** This command only removes the container, not the Docker image. If you want to reclaim disk space by removing the image as well, run:
+
+```bash
+docker rmi $(docker images | grep dev-app-demo | awk '{print $3}')
 ```
 
-And then:
+## Project Structure
 
-```python
-from aloha.logger import LOG
-from aloha.settings import SETTINGS as S
 ```
+aloha-python/
+├── app/                    # Application code
+│   ├── main.py            # Main application entry point
+│   ├── requirements.txt   # Python dependencies
+│   └── app_common/        # Common application utilities
+├── src/                    # Source code for the aloha library
+├── doc/                    # Documentation files
+├── notebook/               # Jupyter notebooks
+└── tool/                   # Development tools
+    ├── cicd/              # CI/CD scripts and configs
+    │   ├── run-dev.sh     # Main development environment script
+    │   └── docker-compose.app-demo.DEV.yml
+    ├── dev-demo.Dockerfile
+    └── app-demo.Dockerfile
+```
+
+## Troubleshooting
+
+### "Port is already in use" error
+
+If you see this error, another process is using the assigned ports. You can:
+
+1. Identify and stop the conflicting process
+2. Work with a system administrator to free up the ports
+
+### Container won't start
+
+- Check Docker logs: `./tool/cicd/run-dev.sh logs`
+- Ensure Docker service is running: `systemctl status docker` (Linux) or check Docker Desktop (Windows/macOS)
+
+### Changes not reflecting
+
+- Verify your files are in the mounted directories
+- Check that you're editing files on your host machine (not just inside the container)
+- Restart any running services inside the container if needed
+
+## Next Steps
+
+Once inside the container, you can:
+
+1. Explore the `app/` directory to understand the application structure
+2. Check out the Jupyter notebooks in the `notebook/` directory
+3. Review the documentation in the `doc/` directory
+4. Start developing your application!
diff --git a/src/aloha/time/__init__.py b/src/app_common/__init__.py
similarity index 100%
rename from src/aloha/time/__init__.py
rename to src/app_common/__init__.py
diff --git a/src/aloha/util/__init__.py b/src/app_common/api/__init__.py
similarity index 100%
rename from src/aloha/util/__init__.py
rename to src/app_common/api/__init__.py
diff --git a/app/app_common/api/api_common_query_postgres.py b/src/app_common/api/api_common_query_postgres.py
similarity index 100%
rename from app/app_common/api/api_common_query_postgres.py
rename to src/app_common/api/api_common_query_postgres.py
diff --git a/app/app_common/api/api_common_sys_info.py b/src/app_common/api/api_common_sys_info.py
similarity index 100%
rename from app/app_common/api/api_common_sys_info.py
rename to src/app_common/api/api_common_sys_info.py
diff --git a/app/app_common/api/api_multipart.py b/src/app_common/api/api_multipart.py
similarity index 100%
rename from app/app_common/api/api_multipart.py
rename to src/app_common/api/api_multipart.py
diff --git a/app/app_common/debug.py b/src/app_common/debug.py
similarity index 100%
rename from app/app_common/debug.py
rename to src/app_common/debug.py
diff --git a/app/app_common/main.py b/src/app_common/main.py
similarity index 100%
rename from app/app_common/main.py
rename to src/app_common/main.py
diff --git a/app/main.py b/src/main.py
similarity index 100%
rename from app/main.py
rename to src/main.py
diff --git a/app/requirements.txt b/src/requirements.txt
similarity index 100%
rename from app/requirements.txt
rename to src/requirements.txt
diff --git a/app/resource/config/deploy-DEV.conf b/src/resource/config/deploy-DEV.conf
similarity index 100%
rename from app/resource/config/deploy-DEV.conf
rename to src/resource/config/deploy-DEV.conf
diff --git a/app/resource/config/main.conf b/src/resource/config/main.conf
similarity index 100%
rename from app/resource/config/main.conf
rename to src/resource/config/main.conf
diff --git a/tool/app-demo.Dockerfile b/tool/app-demo.Dockerfile
index 5b3d805..2cc98e4 100644
--- a/tool/app-demo.Dockerfile
+++ b/tool/app-demo.Dockerfile
@@ -18,8 +18,7 @@ COPY . /tmp/app
 RUN set -ex && cd /tmp/app && mkdir -pv ${DIR_APP} \
  && source /opt/utils/script-localize.sh ${PROFILE_LOCALIZE} \
  && if [[ "$ENABLE_CODE_BUILD" = "true" ]] ; then \
-      echo "-> Building src to binary..." && pip install -U aloha[build] && \
-      aloha compile --base=./src --dist=${DIR_APP}/ ; \
+      echo "-> Building src to binary..." && pip install -U aloha[build] && aloha compile --base=./src --dist=${DIR_APP}/ ; \
     else \
       echo "-> Not building src code!" && mv src/* ${DIR_APP} ; \
     fi \
diff --git a/tool/cicd/docker-compose.app-demo.DEV.yml b/tool/cicd/docker-compose.app-demo.DEV.yml
index 53338fe..ef39637 100644
--- a/tool/cicd/docker-compose.app-demo.DEV.yml
+++ b/tool/cicd/docker-compose.app-demo.DEV.yml
@@ -12,17 +12,14 @@ services:
         # - PROFILE_LOCALIZE=${PROFILE_LOCALIZE:-default}
       pull: true
     restart: unless-stopped
+    # env_file: ["../credentials/DEV-app-demo.env"]
     environment:
       # - ENV_PROFILE=${ENV_PROFILE:-DEV}
       - PROFILE_LOCALIZE=${PROFILE_LOCALIZE:-default}
-      - PYTHONPATH=/root/app:/root/src:/root/notebook
-      # env_file: ["../credentials/DEV-app-demo.env"]
+      - PYTHONPATH=/root/app/pkg:/root/app/src:/root/app/notebook
     user: "0:0"
     ports: [ "${PORT_APP:-9000}:9000", "${PORT_WEB:-3000}:3000" ]
     volumes:
-      - ../../doc:/root/doc:rw
-      - ../../notebook:/root/notebook:rw
-      - ../../src:/root/src:rw
-      - ../../app:/root/app:rw
+      - ../:/root/app:rw
     working_dir: /root
     command: "tail -f /dev/null"
diff --git a/tool/dev-demo.Dockerfile b/tool/dev-demo.Dockerfile
index b3e6187..80e3e3b 100644
--- a/tool/dev-demo.Dockerfile
+++ b/tool/dev-demo.Dockerfile
@@ -21,4 +21,4 @@ RUN set -eux && pwd && ls -alh \
  # ----------- install db client to connect db via terminal ------------
  && source /opt/utils/script-setup-db-clients.sh && setup_postgresql_client 17 \
  # ----------- clean up -----------
- && source /opt/utils/script-setup.sh && list_installed_packages && install__clean
+ && source /opt/utils/script-utils.sh && list_installed_packages && install__clean

From a160ca1d9ae2ebcc76c2175c0d5dfcef24149df2 Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 20:28:41 +0800
Subject: [PATCH 2/8] update README

---
 .github/workflows/build.yml | 13 +++++--------
 pkg/README.md               | 35 -----------------------------------
 2 files changed, 5 insertions(+), 43 deletions(-)
 delete mode 100644 pkg/README.md

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 1b5aff6..03ffb87 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -56,21 +56,18 @@ jobs:
       - name: pip-install-test
         run: |
           sudo pip3 install -UI pip && sudo pip3 install -UI build setuptools wheel twine pyOpenSSL
-          cd pkg
-          sudo python3 -m build
-          pip3 install ./dist/*.tar.gz
-          aloha info
-          pip3 list | sort
+          cp ./README.md ./pkg/
+          cd pkg && sudo python3 -m build & pip3 install ./dist/*.tar.gz
+          pip3 list | grep aloha && aloha info
 
       - name: pypi-publish
         env:
           TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
           TWINE_PASSWORD_TEST: ${{ secrets.TWINE_PASSWORD_TEST }}
         run: |
-          env | sort -f && cd pkg && ls -alh
+          env | sort -f && cp ./README.md ./pkg/ && cd pkg && ls -alh
           sudo python3 -c "import fcntl; fcntl.fcntl(1, fcntl.F_SETFL, 0)"
-          sudo python3 -m build
-          ls -alh ./dist
+          sudo python3 -m build && ls -alh ./dist
 
           if [ "${GITHUB_REPOSITORY}" = "LabNow-ai/aloha-python" ] && [ "${GITHUB_REF_NAME}" = "main" ] ; then
             URL_REPOSITORY="https://upload.pypi.org/legacy/" ; P=${TWINE_PASSWORD} ;
diff --git a/pkg/README.md b/pkg/README.md
deleted file mode 100644
index 10342a5..0000000
--- a/pkg/README.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Aloha
-
-## What is it?
-
-`aloha` is a versatile Python utility package for building microservices.
-
-[![License](https://img.shields.io/github/license/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/blob/main/LICENSE)
-[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/LabNow-ai/aloha-python/build.yml?branch=main)](https://github.com/LabNow-ai/aloha-python/actions)
-[![Join the Gitter Chat](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/LabNow-ai/)
-[![PyPI version](https://img.shields.io/pypi/v/aloha)](https://pypi.python.org/pypi/aloha/)
-[![PyPI Downloads](https://img.shields.io/pypi/dm/aloha)](https://pepy.tech/badge/aloha/)
-[![Code Activity](https://img.shields.io/github/commit-activity/m/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/pulse)
-[![Recent Code Update](https://img.shields.io/github/last-commit/LabNow-ai/aloha-python.svg)](https://github.com/LabNow-ai/aloha-python/stargazers)
-
-Please generously STAR★ our project or donate to us!
-[![GitHub Starts](https://img.shields.io/github/stars/LabNow-ai/aloha-python.svg?label=Stars&style=social)](https://github.com/LabNow-ai/aloha-python/stargazers)
-
-- For questions, try DeepWiki: [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/LabNow-ai/aloha-python)
-
-- To contribute or talk to a human: [![Open an Issue on GitHub](https://img.shields.io/github/issues/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/issues) [![Join the Discord Chat](https://img.shields.io/badge/Discuss_on-Discord-green)](https://discord.gg/kHUzgQxgbJ)
-
-## Getting started
-
-Refer to 📚 [Document](https://aloha-python.readthedocs.io/) & [中文文档](https://aloha-python.readthedocs.io/zh-cn/main/) for detailed introduction.
-
-```shell
-pip install aloha[all]
-```
-
-And then:
-
-```python
-from aloha.logger import LOG
-from aloha.settings import SETTINGS as S
-```

From 2daa67221352983511025af25481d321d49a3b6f Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 20:33:13 +0800
Subject: [PATCH 3/8] typo

---
 .github/workflows/build.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 03ffb87..5e9fea7 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -57,7 +57,7 @@ jobs:
         run: |
           sudo pip3 install -UI pip && sudo pip3 install -UI build setuptools wheel twine pyOpenSSL
           cp ./README.md ./pkg/
-          cd pkg && sudo python3 -m build & pip3 install ./dist/*.tar.gz
+          cd pkg && sudo python3 -m build && pip3 install ./dist/*.tar.gz
           pip3 list | grep aloha && aloha info
 
       - name: pypi-publish

From ed8d93f7a6d1fae2784cc1704016cad3f08e239b Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 20:44:25 +0800
Subject: [PATCH 4/8] fix ver

---
 pkg/aloha/_version.py                     | 2 +-
 tool/cicd/docker-compose.app-demo.DEV.yml | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/pkg/aloha/_version.py b/pkg/aloha/_version.py
index 01dc7a8..6c8e6b9 100644
--- a/pkg/aloha/_version.py
+++ b/pkg/aloha/_version.py
@@ -1 +1 @@
-__version__ = "2026.0421.2100"
+__version__ = "0.0.0"
diff --git a/tool/cicd/docker-compose.app-demo.DEV.yml b/tool/cicd/docker-compose.app-demo.DEV.yml
index ef39637..ca57b0d 100644
--- a/tool/cicd/docker-compose.app-demo.DEV.yml
+++ b/tool/cicd/docker-compose.app-demo.DEV.yml
@@ -20,6 +20,6 @@ services:
     user: "0:0"
     ports: [ "${PORT_APP:-9000}:9000", "${PORT_WEB:-3000}:3000" ]
     volumes:
-      - ../:/root/app:rw
-    working_dir: /root
+      - ../../:/root/app:rw
+    working_dir: /root/app
     command: "tail -f /dev/null"

From 305fccf2f97863fba3a067df5c1dc07e52679160 Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 21:31:21 +0800
Subject: [PATCH 5/8] fix pyhocon bug

---
 pkg/aloha/config/hocon.py | 58 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 54 insertions(+), 4 deletions(-)

diff --git a/pkg/aloha/config/hocon.py b/pkg/aloha/config/hocon.py
index 0636e4e..e3d0509 100644
--- a/pkg/aloha/config/hocon.py
+++ b/pkg/aloha/config/hocon.py
@@ -1,11 +1,61 @@
+import os
+
 from attrdict import AttrDict
 from pyhocon import ConfigFactory
+from pyhocon.config_parser import ConfigParser
+from pyhocon.config_tree import ConfigTree, ConfigValues
+from pyhocon.exceptions import ConfigSubstitutionException
+
+
+# Monkeypatch ConfigParser._fixup_self_references to prevent "OrderedDict mutated during iteration"
+# error on Python 3.13+ when resolving self-referential environment overrides.
+@classmethod
+def patched_fixup_self_references(cls, config, accept_unresolved=False):
+    if isinstance(config, ConfigTree) and config.root:
+        for key in list(config.keys()):  # Use list to avoid mutation error during iteration
+            history = config.history.get(key)
+            if not history:
+                continue
+            previous_item = history[0]
+            for current_item in history[1:]:
+                for substitution in cls._find_substitutions(current_item):
+                    prop_path = ConfigTree.parse_key(substitution.variable)
+                    if len(prop_path) > 1 and config.get(substitution.variable, None) is not None:
+                        continue
+                    if prop_path[0] == key:
+                        if isinstance(previous_item, ConfigValues) and not accept_unresolved:
+                            raise ConfigSubstitutionException(
+                                "Property {variable} cannot be substituted. Check for cycles.".format(
+                                    variable=substitution.variable
+                                )
+                            )
+                        else:
+                            value = previous_item if len(prop_path) == 1 else previous_item.get(".".join(prop_path[1:]))
+                            _, _, current_item = cls._do_substitute(substitution, value)
+                previous_item = current_item
+
+            if len(history) == 1:
+                for substitution in cls._find_substitutions(previous_item):
+                    prop_path = ConfigTree.parse_key(substitution.variable)
+                    if len(prop_path) > 1 and config.get(substitution.variable, None) is not None:
+                        continue
+                    if prop_path[0] == key:
+                        value = os.environ.get(key)
+                        if value is not None:
+                            cls._do_substitute(substitution, value)
+                            continue
+                        if substitution.optional:
+                            cls._do_substitute(substitution, None)
+
+
+# Fix: https://github.com/chimpler/pyhocon/pull/348 , the function and fix can be remove after this PR merged.
+ConfigParser._fixup_self_references = patched_fixup_self_references
 
 
 def load_config_from_hocon(config_file):
     """
     Load configuration from a single HOCON file.
-    
+
     :param config_file: Path to the HOCON configuration file
     :return: Configuration as an ordered dictionary
     """
@@ -16,10 +66,10 @@ def load_config_from_hocon(config_file):
 def load_config_from_hocon_files(config_files: list, base_dir: str):
     """
     Load configuration from multiple HOCON files.
-    
+
     Combines multiple HOCON files using include directives and returns
     the result as an AttrDict for attribute-style access.
-    
+
     :param config_files: List of HOCON configuration file names
     :param base_dir: Base directory for resolving relative paths
     :return: Configuration as an AttrDict object
@@ -28,7 +78,7 @@ def load_config_from_hocon_files(config_files: list, base_dir: str):
     for config_file in config_files:
         f = 'include required("%s")' % config_file
         s.append(f)
-    f = '\n'.join(s)
+    f = "\n".join(s)
 
     config = ConfigFactory.parse_string(content=f, basedir=base_dir).as_plain_ordered_dict()
     return AttrDict(config)

From ff6a1a38f26f1893454ef63ee37d007d3bd329ac Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 21:39:41 +0800
Subject: [PATCH 6/8] fix doc build

---
 doc/.readthedocs.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/.readthedocs.yaml b/doc/.readthedocs.yaml
index 426052d..4aaba3d 100644
--- a/doc/.readthedocs.yaml
+++ b/doc/.readthedocs.yaml
@@ -23,6 +23,6 @@ python:
   install:
     - requirements: ./doc/requirements.txt
     - method: pip
-      path: ./src
+      path: ./pkg
       extra_requirements:
         - all

From 5ea2f878789116f1c4097e45a3616b5b2db14f76 Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 21:44:50 +0800
Subject: [PATCH 7/8] debug doc build

---
 doc/.readthedocs.yaml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/.readthedocs.yaml b/doc/.readthedocs.yaml
index 4aaba3d..95ea339 100644
--- a/doc/.readthedocs.yaml
+++ b/doc/.readthedocs.yaml
@@ -12,6 +12,7 @@ build:
     pre_create_environment:
       - echo "Command run at 'pre_create_environment' step"
     pre_build:
+      - 'cp ./README.md ./pkg/'
       - 'case "${READTHEDOCS_LANGUAGE}" in zh*) cp ./doc/mkdocs.zh.yml ./doc/mkdocs.yml ;; esac'
     post_build:
       - echo "Command run at 'post_build' step $(date)"

From 0c8a185bdc96dcc320e72f9616cb006053fd3b6d Mon Sep 17 00:00:00 2001
From: Bibo Hao <haobibo@users.noreply.github.com>
Date: Tue, 23 Jun 2026 22:08:43 +0800
Subject: [PATCH 8/8] debug docs

---
 doc/.readthedocs.yaml                     | 2 +-
 tool/cicd/docker-compose.app-demo.DEV.yml | 5 +++++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/doc/.readthedocs.yaml b/doc/.readthedocs.yaml
index 95ea339..4f28b83 100644
--- a/doc/.readthedocs.yaml
+++ b/doc/.readthedocs.yaml
@@ -11,8 +11,8 @@ build:
   jobs:
     pre_create_environment:
       - echo "Command run at 'pre_create_environment' step"
-    pre_build:
       - 'cp ./README.md ./pkg/'
+    pre_build:
       - 'case "${READTHEDOCS_LANGUAGE}" in zh*) cp ./doc/mkdocs.zh.yml ./doc/mkdocs.yml ;; esac'
     post_build:
       - echo "Command run at 'post_build' step $(date)"
diff --git a/tool/cicd/docker-compose.app-demo.DEV.yml b/tool/cicd/docker-compose.app-demo.DEV.yml
index ca57b0d..d0db854 100644
--- a/tool/cicd/docker-compose.app-demo.DEV.yml
+++ b/tool/cicd/docker-compose.app-demo.DEV.yml
@@ -21,5 +21,10 @@ services:
     ports: [ "${PORT_APP:-9000}:9000", "${PORT_WEB:-3000}:3000" ]
     volumes:
       - ../../:/root/app:rw
+      # AI4Coding tools:
+      - "$HOME/.claude:/root/.claude:rw"
+      - "$HOME/.codex:/root/.codex:rw"
+      - "$HOME/.copilot:/root/.copilot:rw"
+      - "$HOME/.gemini:/root/.gemini:rw"
     working_dir: /root/app
     command: "tail -f /dev/null"