reachableceo/ReachableCEO-AI-Homedir-Public
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add organized Docker container structure with disciplined naming

Browse Source 
- Create layered container architecture: Base, Light, Full, Computational
- Implement non-root user management with UID/GID mapping
- Add Markwhen timeline tool to documentation stack
- Create wrapper scripts for environment variable handling
- Update documentation across all containers
- Establish naming convention using RCEO-AIOS-Public-Tools- prefix
- Add organizational rule to keep repository root clean
- Remove old unorganized container files
This commit is contained in:
Charles N Wyble - admin
2025-10-16 11:40:25 -05:00
parent 7fad76ea9d
commit d30f103209
24 changed files with 1055 additions and 131 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
AGENTS.md
View File

@@ -4,11 +4,15 @@ This document tracks the various agents, tools, and systems used in the AIOS-Pub
## Documentation Tools
### RCEO-AIOS-Public-Tools-DocMaker
### RCEO-AIOS-Public-Tools-DocMaker Container Family
**Purpose**: Documentation generation container with multiple document conversion tools.
**Purpose**: Documentation generation containers with multiple document conversion tools, organized in a layered architecture.
**Container/Stack Name**: RCEO-AIOS-Public-Tools-DocMaker
**Container/Stack Names**:
- RCEO-AIOS-Public-Tools-DocMaker-Base: Base documentation environment
- RCEO-AIOS-Public-Tools-DocMaker-Light: Lightweight documentation tools (fast-starting)
- RCEO-AIOS-Public-Tools-DocMaker-Full: Full documentation with LaTeX-full
- RCEO-AIOS-Public-Tools-DocMaker-Computational: All documentation tools plus computational tools (R, Python, Jupyter, Octave)
**Technology Stack**:
- Base: Debian Bookworm slim
@@ -17,46 +21,97 @@ This document tracks the various agents, tools, and systems used in the AIOS-Pub
- Node.js
- Rust (with Cargo)
- Pandoc
- LaTeX (Full)
- LaTeX (varies by container: light packages in base/full in full)
- mdBook (installed via Cargo)
- mdbook-pdf (installed via Cargo)
- Typst
- Marp CLI
- Markwhen: Interactive text-to-timeline tool
- Spell/Grammar checking:
- Hunspell (with en-US dictionary)
- Aspell (with en dictionary)
- Vale (style and grammar linter)
- Reading time estimation: mdstat
- Additional text processing tools
- Computational tools in Computational container:
- R programming language
- Python scientific stack (pandas, numpy, matplotlib, scipy)
- Jupyter notebooks
- GNU Octave
- bc (command-line calculator)
**Usage**: This container/stack should be used for projects that need to generate finished documentation in various formats (PDF, HTML, presentations, etc.).
**Usage**:
- Use Light container for quick documentation tasks (COO mode)
- Use Full container for complex document generation (COO mode)
- Use Computational container for data analysis and R&D work (CTO mode)
- Base container serves as foundation for other containers
**Docker Configuration**:
- Located in the `Docker/` directory
- Includes Dockerfile and docker-compose.yml
- Each container has its own subdirectory with Dockerfile and docker-compose.yml
- Maps the project root directory to `/workspace` inside the container
- Can be run with `docker-compose up` from the Docker directory
- Uses UID/GID mapping for proper file permissions across environments
- Can be run with `docker-compose up` from each container's directory
**Container Usage Map**:
- Light container: COO mode, quick documentation tasks (CV, proposals, governance docs)
- Full container: COO mode, complex document generation with LaTeX-full
- Computational container: CTO mode, data analysis and R&D work (R, Python, Jupyter)
**Commands to run**:
# Using the wrapper script (recommended - handles UID/GID automatically):
```bash
# Build and start the container
cd Docker
# Build and start the lightweight container (COO mode)
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Light
./docker-compose-wrapper.sh up --build
# Build and start the full documentation container (COO mode)
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Full
./docker-compose-wrapper.sh up --build
# Build and start the computational container (CTO mode)
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational
./docker-compose-wrapper.sh up --build
# Run commands in containers with automatic user mapping:
./docker-compose-wrapper.sh run docmaker-light [command] # Light container
./docker-compose-wrapper.sh run docmaker-full [command] # Full container
./docker-compose-wrapper.sh run docmaker-computational [command] # Computational container
```
# Using docker-compose directly (requires manual environment variables):
```bash
# Set environment variables for proper file permissions
export LOCAL_USER_ID=$(id -u)
export LOCAL_GROUP_ID=$(id -g)
# Build and start containers
cd Docker/RCEO-AIOS-Public-Tools-DocMaker-Light
docker-compose up --build
# Or to run commands directly
docker-compose run docmaker [command]
# Example usage of documentation tools:
# Example usage of documentation tools with wrapper script:
# Spell checking with hunspell
docker-compose run docmaker hunspell -d en_US document.md
./docker-compose-wrapper.sh run docmaker-full hunspell -d en_US document.md
# Create timeline with Markwhen
./docker-compose-wrapper.sh run docmaker-full markwhen input.mw --output output.html
# Grammar/style checking with Vale
docker-compose run docmaker vale document.md
./docker-compose-wrapper.sh run docmaker-full vale document.md
# Reading time estimation
docker-compose run docmaker python3 -m mdstat document.md
./docker-compose-wrapper.sh run docmaker-full python3 -m mdstat document.md
# Run R analysis (in computational container)
./docker-compose-wrapper.sh run docmaker-computational Rscript analysis.R
# Run Python analysis (in computational container)
./docker-compose-wrapper.sh run docmaker-computational python analysis.py
# Check spelling with aspell
docker-compose run docmaker aspell -c document.md
```
./docker-compose-wrapper.sh run docmaker-full aspell -c document.md
```
**User Management**: All containers run as non-root user `ReachableCEO-Tools` with UID/GID mapping from the host environment to ensure proper file permissions.

22
Docker/RCEO-AIOS-Public-Tools-DocMaker/Dockerfile → Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/Dockerfile
View File

@@ -14,12 +14,13 @@ RUN apt-get update && apt-get install -y \
nodejs \
npm \
build-essential \
sudo \
&& rm -rf /var/lib/apt/lists/*
# Create symbolic link for python
RUN ln -s /usr/bin/python3 /usr/bin/python
# Install Rust
# Install Rust (for root - will be accessible to user)
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
ENV PATH="/root/.cargo/bin:${PATH}"
@@ -28,13 +29,15 @@ RUN apt-get update && apt-get install -y \
pandoc \
&& rm -rf /var/lib/apt/lists/*
# Install LaTeX (full version)
# Install lightweight LaTeX
RUN apt-get update && apt-get install -y \
texlive-full \
texlive-latex-base \
texlive-fonts-recommended \
texlive-fonts-extra \
&& rm -rf /var/lib/apt/lists/*
# Install mdBook and mdbook-pdf using cargo
RUN cargo install mdbook mdbook-pdf
RUN /root/.cargo/bin/cargo install --root /usr/local mdbook mdbook-pdf
# Install Typst
RUN curl -L https://github.com/typst/typst/releases/latest/download/typst-x86_64-unknown-linux-musl.tar.xz \
@@ -43,6 +46,9 @@ RUN curl -L https://github.com/typst/typst/releases/latest/download/typst-x86_64
# Install Marp CLI
RUN npm install -g @marp-team/marp-cli
# Install Markwhen
RUN npm install -g @markwhen/cli
# Install spell/grammar checking tools
RUN apt-get update && apt-get install -y \
hunspell \
@@ -62,8 +68,12 @@ RUN apt-get update && apt-get install -y \
aspell-en \
&& rm -rf /var/lib/apt/lists/*
# Add entrypoint script
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
# Create a working directory
WORKDIR /workspace
# Default command
CMD ["/bin/bash"]
# Use the entrypoint script to handle user creation
ENTRYPOINT ["/entrypoint.sh"]

106
Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/README.md Normal file
View File

@@ -0,0 +1,106 @@
# RCEO-AIOS-Public-Tools-DocMaker-Base Container
This container is part of the AIOS-Public project and provides a base documentation generation environment.
## Overview
The RCEO-AIOS-Public-Tools-DocMaker-Base container is designed for lightweight documentation generation tasks. It includes a range of tools for creating, converting, and processing documentation in various formats without heavy dependencies like full LaTeX.
## Tools Included
### Core Tools
- **Base OS**: Debian Bookworm slim
- **Shell**: Bash
- **Programming Languages**:
- Python 3
- Node.js
- Rust (with Cargo)
### Documentation Generation
- **Pandoc**: Universal document converter
- **mdBook**: Create books from Markdown files
- **mdbook-pdf**: PDF renderer for mdBook
- **Typst**: Modern typesetting system
- **Marp CLI**: Create presentations from Markdown
- **Markwhen**: Interactive text-to-timeline tool
### LaTeX
- **TeX Live**: Lightweight LaTeX packages for basic document typesetting
### Spell and Grammar Checking
- **Hunspell**: Spell checker (with en-US dictionary)
- **Aspell**: Spell checker (with en dictionary)
- **Vale**: Syntax-aware linter for prose
### Text Analysis
- **mdstat**: Text statistics including reading time estimation
## Usage
### Building the Base Container
```bash
# From this directory
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base
# Use the wrapper script to automatically detect and set user IDs
./docker-compose-wrapper.sh build
# Or run commands in the base container with automatic user mapping
./docker-compose-wrapper.sh run docmaker-base [command]
# Example: Convert a Markdown file to PDF using pandoc
./docker-compose-wrapper.sh run docmaker-base pandoc input.md -o output.pdf
# Example: Create a timeline with Markwhen
./docker-compose-wrapper.sh run docmaker-base markwhen input.mw --output output.html
```
### Using with docker-compose directly
```bash
# Set environment variables and run docker-compose directly
LOCAL_USER_ID=$(id -u) LOCAL_GROUP_ID=$(id -g) docker-compose up --build
# Or export variables first
export LOCAL_USER_ID=$(id -u)
export LOCAL_GROUP_ID=$(id -g)
docker-compose up
```
### Using the wrapper script
```bash
# Build and start the base documentation container with automatic user mapping
./docker-compose-wrapper.sh up --build
# Start without rebuilding
./docker-compose-wrapper.sh up
# View container status
./docker-compose-wrapper.sh ps
# Stop containers
./docker-compose-wrapper.sh down
```
## User ID Mapping (For File Permissions)
The container automatically detects and uses the host user's UID and GID to ensure proper file permissions. This means:
- Files created inside the container will have the correct ownership on the host
- No more root-owned files after container operations
- Works across different environments (development, CI/CD, cloud)
The container detects the user ID from the mounted workspace volume. If needed, you can override the default values by setting environment variables:
```bash
# Set specific user ID and group ID before running docker-compose
export LOCAL_USER_ID=1000
export LOCAL_GROUP_ID=1000
docker-compose up
```
Or run with inline environment variables:
```bash
LOCAL_USER_ID=1000 LOCAL_GROUP_ID=1000 docker-compose up
```
The container runs as a non-root user named `ReachableCEO-Tools` with the detected host user's UID/GID.

74
Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/TODO.md Normal file
View File

@@ -0,0 +1,74 @@
# TODO List for RCEO-AIOS-Public-Tools-DocMaker Containers
This document tracks potential enhancements and tools to be added to the documentation generation container family.
## Container Structure
### RCEO-AIOS-Public-Tools-DocMaker-Base
- Base documentation environment with lightweight tools
- Purpose: Foundation for all other containers
### RCEO-AIOS-Public-Tools-DocMaker-Light
- Lightweight documentation tools (no heavy LaTeX)
- Purpose: Fast-starting documentation tasks (COO mode)
### RCEO-AIOS-Public-Tools-DocMaker-Full
- Full documentation environment with LaTeX-full
- Purpose: Complex document generation (COO mode)
### RCEO-AIOS-Public-Tools-DocMaker-Computational
- All documentation tools plus R, Python, Jupyter, Octave
- Purpose: Computational tasks and analysis (CTO mode)
## Tools Under Consideration
### [Tool Name Placeholder]
**Purpose**: [Purpose of the tool]
**Description**: [Detailed description of what this tool does and how it could benefit the container]
**Technical Details**:
- [Requirements]
- [Installation method]
**Benefits**:
- [How this enhances the container]
**Container**: [Base/Light/Full/Computational]
**Priority**: [High/Medium/Low]
## Completed Items
### Base Container Tools
- ✅ Core system packages (bash, curl, wget, git)
- ✅ Programming languages (Python 3, Node.js, Rust)
- ✅ Pandoc - Universal document converter
- ✅ mdBook - Create books from Markdown files
- ✅ mdbook-pdf - PDF renderer for mdBook
- ✅ Typst - Modern typesetting system
- ✅ Marp CLI - Create presentations from Markdown
- ✅ Markwhen - Interactive text-to-timeline tool
- ✅ Light LaTeX packages (texlive-latex-base)
- ✅ Spell/grammar checking tools (Hunspell, Aspell, Vale)
- ✅ Text statistics tools (mdstat)
- ✅ Non-root user management with UID/GID mapping
- ✅ Entrypoint script for runtime user creation
### Full Documentation Container Tools
- ✅ All Base Container tools included
- ✅ Full LaTeX (texlive-full) - for complex document generation
### Computational Container Tools
- ✅ All Full Documentation Container tools included
- ✅ R programming language and common packages
- ✅ Python scientific stack (pandas, numpy, matplotlib, scipy)
- ✅ Jupyter Notebooks with R kernel support
- ✅ GNU Octave
- ✅ Command-line calculator (bc)
### Organizational Improvements
- ✅ Disciplined naming convention using RCEO-AIOS-Public-Tools- prefix
- ✅ Individual directories per container type
- ✅ Proper documentation with individual README files
- ✅ Organized docker-compose files per container
- ✅ Clear separation of COO vs CTO mode containers

67
Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/docker-compose-wrapper.sh Executable file
View File

@@ -0,0 +1,67 @@
#!/bin/bash
# docker-compose-wrapper.sh - Wrapper script to detect host UID/GID and run docker-compose
set -e # Exit on any error
# Detect the UID and GID of the user that owns the workspace directory (parent directory)
WORKSPACE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
echo "Detecting user ID from workspace directory: $WORKSPACE_DIR"
if [ -d "$WORKSPACE_DIR" ]; then
DETECTED_USER_ID=$(stat -c %u "$WORKSPACE_DIR" 2>/dev/null || echo 0)
DETECTED_GROUP_ID=$(stat -c %g "$WORKSPACE_DIR" 2>/dev/null || echo 0)
# If detection failed, try current user
if [ "$DETECTED_USER_ID" = "0" ]; then
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
else
# Fallback to current user if workspace directory doesn't exist
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
echo "Detected USER_ID=$DETECTED_USER_ID and GROUP_ID=$DETECTED_GROUP_ID"
# Set environment variables for docker-compose
export LOCAL_USER_ID=$DETECTED_USER_ID
export LOCAL_GROUP_ID=$DETECTED_GROUP_ID
# Show usage information
echo ""
echo "Usage: $0 [build|up|run <service> <command>|exec <service> <command>|down|ps]"
echo ""
echo "Examples:"
echo " $0 up # Start services"
echo " $0 build # Build containers"
echo " $0 run docmaker-full bash # Run command in container"
echo " $0 down # Stop and remove containers"
echo ""
# Check if docker compose (new format) or docker-compose (old format) is available
if command -v docker &> /dev/null && docker compose version &> /dev/null; then
# Use new docker compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker compose up'..."
docker compose up
else
# Execute the provided docker compose command
echo "Running: docker compose $*"
docker compose "$@"
fi
elif command -v docker-compose &> /dev/null; then
# Fallback to old docker-compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker-compose up'..."
docker-compose up
else
# Execute the provided docker-compose command
echo "Running: docker-compose $*"
docker-compose "$@"
fi
else
echo "Error: Neither 'docker compose' nor 'docker-compose' command found."
echo "Please install Docker Compose to use this script."
exit 1
fi

18
Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/docker-compose.yml Normal file
View File

@@ -0,0 +1,18 @@
version: '3.8'
services:
docmaker-base:
build:
context: .
dockerfile: Dockerfile
container_name: RCEO-AIOS-Public-Tools-DocMaker-Base
image: rceo-aios-public-tools-docmaker-base:latest
volumes:
- ../../../:/workspace:rw
working_dir: /workspace
stdin_open: true
tty: true
environment:
- LOCAL_USER_ID=${LOCAL_USER_ID:-1000}
- LOCAL_GROUP_ID=${LOCAL_GROUP_ID:-1000}
user: "${LOCAL_USER_ID:-1000}:${LOCAL_GROUP_ID:-1000}"

49
Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/entrypoint.sh Normal file
View File

@@ -0,0 +1,49 @@
#!/bin/bash
# entrypoint.sh - Entrypoint script to handle user creation and permission setup at runtime
# Set default values if not provided
USER_ID=${LOCAL_USER_ID:-$(id -u 1000)}
GROUP_ID=${LOCAL_GROUP_ID:-$(id -g 1000)}
# In case the environment variables are not set properly, detect them from the workspace volume
if [ "$USER_ID" = "$(id -u 0)" ] || [ "$USER_ID" = "0" ]; then
# Detect the UID and GID of the user that owns the workspace directory
if [ -d "/workspace" ]; then
USER_ID=$(stat -c %u /workspace 2>/dev/null || echo 1000)
GROUP_ID=$(stat -c %g /workspace 2>/dev/null || echo 1000)
else
USER_ID=${LOCAL_USER_ID:-1000}
GROUP_ID=${LOCAL_GROUP_ID:-1000}
fi
fi
echo "Starting with USER_ID=$USER_ID and GROUP_ID=$GROUP_ID"
# Create the group with specified GID
groupadd -f -g $GROUP_ID -o ReachableCEO-Tools 2>/dev/null || groupmod -g $GROUP_ID -o ReachableCEO-Tools
# Create the user with specified UID and add to the group
useradd -f -u $USER_ID -g $GROUP_ID -m -s /bin/bash -o ReachableCEO-Tools 2>/dev/null || usermod -u $USER_ID -g $GROUP_ID -o ReachableCEO-Tools
# Add user to sudo group for any necessary operations
usermod -aG sudo ReachableCEO-Tools 2>/dev/null || true
# Make sure workspace directory exists and has proper permissions
mkdir -p /workspace
chown -R $USER_ID:$GROUP_ID /workspace
# Set up proper permissions for Rust and Cargo (if they exist)
mkdir -p /home/ReachableCEO-Tools/.cargo
chown $USER_ID:$GROUP_ID /home/ReachableCEO-Tools/.cargo
# Set up proper permissions for npm global packages (if they exist)
mkdir -p /home/ReachableCEO-Tools/.npm
chown $USER_ID:$GROUP_ID /home/ReachableCEO-Tools/.npm
# If there are additional arguments, run them as the created user
if [ $# -gt 0 ]; then
exec su -p ReachableCEO-Tools -c "$*"
else
# Otherwise start an interactive bash shell as the created user
exec su -p ReachableCEO-Tools -c "/bin/bash"
fi

42
Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational/Dockerfile Normal file
View File

@@ -0,0 +1,42 @@
FROM rceo-aios-public-tools-docmaker-full:latest
# Avoid prompts from apt
ENV DEBIAN_FRONTEND=noninteractive
# Install computational tools
RUN apt-get update && apt-get install -y \
r-base \
r-base-dev \
bc \
octave \
&& rm -rf /var/lib/apt/lists/*
# Install Python scientific packages
RUN pip3 install pandas numpy matplotlib scipy jupyter
# Install R packages (commonly used ones)
RUN R -e "install.packages(c('knitr', 'rmarkdown', 'dplyr', 'ggplot2'), repos='https://cran.rstudio.com/')"
# Install IRkernel for R in Jupyter
RUN R -e "install.packages('IRkernel', repos='https://cran.rstudio.com/')"
# Create Jupyter config directory and set up notebook directory
RUN mkdir -p /workspace/notebooks
# Create Jupyter startup script
RUN echo '#!/bin/bash' > /jupyter_start.sh && \
echo '# Install R kernel for Jupyter if R is available' >> /jupyter_start.sh && \
echo 'if command -v R &> /dev/null; then' >> /jupyter_start.sh && \
echo ' R -e "IRkernel::installspec()" 2>/dev/null || true' >> /jupyter_start.sh && \
echo 'fi' >> /jupyter_start.sh && \
echo '# Run Jupyter as the proper user' >> /jupyter_start.sh && \
echo 'exec su -p ReachableCEO-Tools -c "jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser --allow-root --notebook-dir=/workspace/notebooks"' >> /jupyter_start.sh && \
chmod +x /jupyter_start.sh
# Expose Jupyter on port 8888
EXPOSE 8888
# Create a working directory
WORKDIR /workspace
# The entrypoint from the base image handles user creation

97
Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational/README.md Normal file
View File

@@ -0,0 +1,97 @@
# RCEO-AIOS-Public-Tools-DocMaker-Computational Container
This container is part of the AIOS-Public project and provides a comprehensive documentation and computational environment.
## Overview
The RCEO-AIOS-Public-Tools-DocMaker-Computational container extends the full documentation environment with computational tools for data analysis, scientific computing, and interactive notebooks. It's designed for CTO mode operations involving R&D and computational work.
## Tools Included
Inherits all tools from:
- **RCEO-AIOS-Public-Tools-DocMaker-Full**: All documentation and LaTeX tools
### Computational Tools
- **R Programming Language**: Statistical computing and data analysis
- **Python Scientific Stack**:
- pandas - Data manipulation
- numpy - Numerical computing
- matplotlib - Visualization
- scipy - Scientific computing
- **Jupyter Notebooks**: Interactive computational environments
- **GNU Octave**: Numerical computations (MATLAB alternative)
- **bc**: Command-line calculator
## Usage
### Building the Computational Container
```bash
# From this directory
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational
# Use the wrapper script to automatically detect and set user IDs
./docker-compose-wrapper.sh build
# Or run commands in the computational container with automatic user mapping
./docker-compose-wrapper.sh run docmaker-computational [command]
# Example: Run R analysis
./docker-compose-wrapper.sh run docmaker-computational Rscript analysis.R
# Example: Run Python analysis
./docker-compose-wrapper.sh run docmaker-computational python analysis.py
# Example: Start Jupyter notebook server
./docker-compose-wrapper.sh up
# Then access at http://localhost:8888
```
### Using with docker-compose directly
```bash
# Set environment variables and run docker-compose directly
LOCAL_USER_ID=$(id -u) LOCAL_GROUP_ID=$(id -g) docker-compose up --build
# Or export variables first
export LOCAL_USER_ID=$(id -u)
export LOCAL_GROUP_ID=$(id -g)
docker-compose up
```
### Using the wrapper script
```bash
# Build and start the computational container with Jupyter access and automatic user mapping
./docker-compose-wrapper.sh up --build
# Start without rebuilding
./docker-compose-wrapper.sh up
# View container status
./docker-compose-wrapper.sh ps
# Stop containers
./docker-compose-wrapper.sh down
```
## User ID Mapping (For File Permissions)
The container automatically detects and uses the host user's UID and GID to ensure proper file permissions. This means:
- Files created inside the container will have the correct ownership on the host
- No more root-owned files after container operations
- Works across different environments (development, CI/CD, cloud)
The container detects the user ID from the mounted workspace volume. If needed, you can override the default values by setting environment variables:
```bash
# Set specific user ID and group ID before running docker-compose
export LOCAL_USER_ID=1000
export LOCAL_GROUP_ID=1000
docker-compose up
```
Or run with inline environment variables:
```bash
LOCAL_USER_ID=1000 LOCAL_GROUP_ID=1000 docker-compose up
```
The container runs as a non-root user named `ReachableCEO-Tools` with the detected host user's UID/GID.

67
Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational/docker-compose-wrapper.sh Executable file
View File

@@ -0,0 +1,67 @@
#!/bin/bash
# docker-compose-wrapper.sh - Wrapper script to detect host UID/GID and run docker-compose
set -e # Exit on any error
# Detect the UID and GID of the user that owns the workspace directory (parent directory)
WORKSPACE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
echo "Detecting user ID from workspace directory: $WORKSPACE_DIR"
if [ -d "$WORKSPACE_DIR" ]; then
DETECTED_USER_ID=$(stat -c %u "$WORKSPACE_DIR" 2>/dev/null || echo 0)
DETECTED_GROUP_ID=$(stat -c %g "$WORKSPACE_DIR" 2>/dev/null || echo 0)
# If detection failed, try current user
if [ "$DETECTED_USER_ID" = "0" ]; then
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
else
# Fallback to current user if workspace directory doesn't exist
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
echo "Detected USER_ID=$DETECTED_USER_ID and GROUP_ID=$DETECTED_GROUP_ID"
# Set environment variables for docker-compose
export LOCAL_USER_ID=$DETECTED_USER_ID
export LOCAL_GROUP_ID=$DETECTED_GROUP_ID
# Show usage information
echo ""
echo "Usage: $0 [build|up|run <service> <command>|exec <service> <command>|down|ps]"
echo ""
echo "Examples:"
echo " $0 up # Start services"
echo " $0 build # Build containers"
echo " $0 run docmaker-full bash # Run command in container"
echo " $0 down # Stop and remove containers"
echo ""
# Check if docker compose (new format) or docker-compose (old format) is available
if command -v docker &> /dev/null && docker compose version &> /dev/null; then
# Use new docker compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker compose up'..."
docker compose up
else
# Execute the provided docker compose command
echo "Running: docker compose $*"
docker compose "$@"
fi
elif command -v docker-compose &> /dev/null; then
# Fallback to old docker-compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker-compose up'..."
docker-compose up
else
# Execute the provided docker-compose command
echo "Running: docker-compose $*"
docker-compose "$@"
fi
else
echo "Error: Neither 'docker compose' nor 'docker-compose' command found."
echo "Please install Docker Compose to use this script."
exit 1
fi

20
Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational/docker-compose.yml Normal file
View File

@@ -0,0 +1,20 @@
version: '3.8'
services:
docmaker-computational:
build:
context: .
dockerfile: Dockerfile
container_name: RCEO-AIOS-Public-Tools-DocMaker-Computational
image: rceo-aios-public-tools-docmaker-computational:latest
volumes:
- ../../../:/workspace:rw
working_dir: /workspace
stdin_open: true
tty: true
ports:
- "8888:8888" # Jupyter notebook access
environment:
- LOCAL_USER_ID=${LOCAL_USER_ID:-1000}
- LOCAL_GROUP_ID=${LOCAL_GROUP_ID:-1000}
user: "${LOCAL_USER_ID:-1000}:${LOCAL_GROUP_ID:-1000}"

14
Docker/RCEO-AIOS-Public-Tools-DocMaker-Full/Dockerfile Normal file
View File

@@ -0,0 +1,14 @@
FROM rceo-aios-public-tools-docmaker-base:latest
# Avoid prompts from apt
ENV DEBIAN_FRONTEND=noninteractive
# Install full LaTeX (the heavy component that takes time)
RUN apt-get update && apt-get install -y \
texlive-full \
&& rm -rf /var/lib/apt/lists/*
# Create a working directory
WORKDIR /workspace
# The entrypoint from the base image handles user creation

82
Docker/RCEO-AIOS-Public-Tools-DocMaker-Full/README.md Normal file
View File

@@ -0,0 +1,82 @@
# RCEO-AIOS-Public-Tools-DocMaker-Full Container
This container is part of the AIOS-Public project and provides a comprehensive documentation generation environment with full LaTeX support.
## Overview
The RCEO-AIOS-Public-Tools-DocMaker-Full container is designed for comprehensive documentation generation tasks that require full LaTeX functionality. It includes all documentation tools plus the complete TeX Live distribution for advanced document typesetting.
## Tools Included
Inherits all tools from:
- **RCEO-AIOS-Public-Tools-DocMaker-Base**: All base documentation generation tools
### LaTeX
- **TeX Live Full**: Complete LaTeX distribution for advanced document typesetting
## Usage
### Building the Full Documentation Container
```bash
# From this directory
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Full
# Use the wrapper script to automatically detect and set user IDs
./docker-compose-wrapper.sh build
# Or run commands in the full documentation container with automatic user mapping
./docker-compose-wrapper.sh run docmaker-full [command]
# Example: Convert a Markdown file to PDF using pandoc with full LaTeX
./docker-compose-wrapper.sh run docmaker-full pandoc input.md -o output.pdf --pdf-engine=xelatex
```
### Using with docker-compose directly
```bash
# Set environment variables and run docker-compose directly
LOCAL_USER_ID=$(id -u) LOCAL_GROUP_ID=$(id -g) docker-compose up --build
# Or export variables first
export LOCAL_USER_ID=$(id -u)
export LOCAL_GROUP_ID=$(id -g)
docker-compose up
```
### Using the wrapper script
```bash
# Build and start the full documentation container with automatic user mapping
./docker-compose-wrapper.sh up --build
# Start without rebuilding
./docker-compose-wrapper.sh up
# View container status
./docker-compose-wrapper.sh ps
# Stop containers
./docker-compose-wrapper.sh down
```
## User ID Mapping (For File Permissions)
The container automatically detects and uses the host user's UID and GID to ensure proper file permissions. This means:
- Files created inside the container will have the correct ownership on the host
- No more root-owned files after container operations
- Works across different environments (development, CI/CD, cloud)
The container detects the user ID from the mounted workspace volume. If needed, you can override the default values by setting environment variables:
```bash
# Set specific user ID and group ID before running docker-compose
export LOCAL_USER_ID=1000
export LOCAL_GROUP_ID=1000
docker-compose up
```
Or run with inline environment variables:
```bash
LOCAL_USER_ID=1000 LOCAL_GROUP_ID=1000 docker-compose up
```
The container runs as a non-root user named `ReachableCEO-Tools` with the detected host user's UID/GID.

67
Docker/RCEO-AIOS-Public-Tools-DocMaker-Full/docker-compose-wrapper.sh Executable file
View File

@@ -0,0 +1,67 @@
#!/bin/bash
# docker-compose-wrapper.sh - Wrapper script to detect host UID/GID and run docker-compose
set -e # Exit on any error
# Detect the UID and GID of the user that owns the workspace directory (parent directory)
WORKSPACE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
echo "Detecting user ID from workspace directory: $WORKSPACE_DIR"
if [ -d "$WORKSPACE_DIR" ]; then
DETECTED_USER_ID=$(stat -c %u "$WORKSPACE_DIR" 2>/dev/null || echo 0)
DETECTED_GROUP_ID=$(stat -c %g "$WORKSPACE_DIR" 2>/dev/null || echo 0)
# If detection failed, try current user
if [ "$DETECTED_USER_ID" = "0" ]; then
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
else
# Fallback to current user if workspace directory doesn't exist
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
echo "Detected USER_ID=$DETECTED_USER_ID and GROUP_ID=$DETECTED_GROUP_ID"
# Set environment variables for docker-compose
export LOCAL_USER_ID=$DETECTED_USER_ID
export LOCAL_GROUP_ID=$DETECTED_GROUP_ID
# Show usage information
echo ""
echo "Usage: $0 [build|up|run <service> <command>|exec <service> <command>|down|ps]"
echo ""
echo "Examples:"
echo " $0 up # Start services"
echo " $0 build # Build containers"
echo " $0 run docmaker-full bash # Run command in container"
echo " $0 down # Stop and remove containers"
echo ""
# Check if docker compose (new format) or docker-compose (old format) is available
if command -v docker &> /dev/null && docker compose version &> /dev/null; then
# Use new docker compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker compose up'..."
docker compose up
else
# Execute the provided docker compose command
echo "Running: docker compose $*"
docker compose "$@"
fi
elif command -v docker-compose &> /dev/null; then
# Fallback to old docker-compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker-compose up'..."
docker-compose up
else
# Execute the provided docker-compose command
echo "Running: docker-compose $*"
docker-compose "$@"
fi
else
echo "Error: Neither 'docker compose' nor 'docker-compose' command found."
echo "Please install Docker Compose to use this script."
exit 1
fi

18
Docker/RCEO-AIOS-Public-Tools-DocMaker-Full/docker-compose.yml Normal file
View File

@@ -0,0 +1,18 @@
version: '3.8'
services:
docmaker-full:
build:
context: .
dockerfile: Dockerfile
container_name: RCEO-AIOS-Public-Tools-DocMaker-Full
image: rceo-aios-public-tools-docmaker-full:latest
volumes:
- ../../../:/workspace:rw
working_dir: /workspace
stdin_open: true
tty: true
environment:
- LOCAL_USER_ID=${LOCAL_USER_ID:-1000}
- LOCAL_GROUP_ID=${LOCAL_GROUP_ID:-1000}
user: "${LOCAL_USER_ID:-1000}:${LOCAL_GROUP_ID:-1000}"

6
Docker/RCEO-AIOS-Public-Tools-DocMaker-Light/Dockerfile Normal file
View File

@@ -0,0 +1,6 @@
FROM rceo-aios-public-tools-docmaker-base:latest
# Create a working directory
WORKDIR /workspace
# The entrypoint from the base image handles user creation

79
Docker/RCEO-AIOS-Public-Tools-DocMaker-Light/README.md Normal file
View File

@@ -0,0 +1,79 @@
# RCEO-AIOS-Public-Tools-DocMaker-Light Container
This container is part of the AIOS-Public project and provides a lightweight documentation generation environment.
## Overview
The RCEO-AIOS-Public-Tools-DocMaker-Light container is designed for fast-starting documentation tasks. It extends the base documentation environment without adding heavy dependencies like full LaTeX, enabling quick startup and efficient operations for lighter documentation tasks.
## Tools Included
Inherits all tools from:
- **RCEO-AIOS-Public-Tools-DocMaker-Base**: All base documentation generation tools
## Usage
### Building the Lightweight Container
```bash
# From this directory
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Light
# Use the wrapper script to automatically detect and set user IDs
./docker-compose-wrapper.sh build
# Or run commands in the lightweight container with automatic user mapping
./docker-compose-wrapper.sh run docmaker-light [command]
# Example: Convert a Markdown file to PDF using pandoc
./docker-compose-wrapper.sh run docmaker-light pandoc input.md -o output.pdf
```
### Using with docker-compose directly
```bash
# Set environment variables and run docker-compose directly
LOCAL_USER_ID=$(id -u) LOCAL_GROUP_ID=$(id -g) docker-compose up --build
# Or export variables first
export LOCAL_USER_ID=$(id -u)
export LOCAL_GROUP_ID=$(id -g)
docker-compose up
```
### Using the wrapper script
```bash
# Build and start the lightweight documentation container with automatic user mapping
./docker-compose-wrapper.sh up --build
# Start without rebuilding
./docker-compose-wrapper.sh up
# View container status
./docker-compose-wrapper.sh ps
# Stop containers
./docker-compose-wrapper.sh down
```
## User ID Mapping (For File Permissions)
The container automatically detects and uses the host user's UID and GID to ensure proper file permissions. This means:
- Files created inside the container will have the correct ownership on the host
- No more root-owned files after container operations
- Works across different environments (development, CI/CD, cloud)
The container detects the user ID from the mounted workspace volume. If needed, you can override the default values by setting environment variables:
```bash
# Set specific user ID and group ID before running docker-compose
export LOCAL_USER_ID=1000
export LOCAL_GROUP_ID=1000
docker-compose up
```
Or run with inline environment variables:
```bash
LOCAL_USER_ID=1000 LOCAL_GROUP_ID=1000 docker-compose up
```
The container runs as a non-root user named `ReachableCEO-Tools` with the detected host user's UID/GID.

67
Docker/RCEO-AIOS-Public-Tools-DocMaker-Light/docker-compose-wrapper.sh Executable file
View File

@@ -0,0 +1,67 @@
#!/bin/bash
# docker-compose-wrapper.sh - Wrapper script to detect host UID/GID and run docker-compose
set -e # Exit on any error
# Detect the UID and GID of the user that owns the workspace directory (parent directory)
WORKSPACE_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
echo "Detecting user ID from workspace directory: $WORKSPACE_DIR"
if [ -d "$WORKSPACE_DIR" ]; then
DETECTED_USER_ID=$(stat -c %u "$WORKSPACE_DIR" 2>/dev/null || echo 0)
DETECTED_GROUP_ID=$(stat -c %g "$WORKSPACE_DIR" 2>/dev/null || echo 0)
# If detection failed, try current user
if [ "$DETECTED_USER_ID" = "0" ]; then
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
else
# Fallback to current user if workspace directory doesn't exist
DETECTED_USER_ID=$(id -u)
DETECTED_GROUP_ID=$(id -g)
fi
echo "Detected USER_ID=$DETECTED_USER_ID and GROUP_ID=$DETECTED_GROUP_ID"
# Set environment variables for docker-compose
export LOCAL_USER_ID=$DETECTED_USER_ID
export LOCAL_GROUP_ID=$DETECTED_GROUP_ID
# Show usage information
echo ""
echo "Usage: $0 [build|up|run <service> <command>|exec <service> <command>|down|ps]"
echo ""
echo "Examples:"
echo " $0 up # Start services"
echo " $0 build # Build containers"
echo " $0 run docmaker-full bash # Run command in container"
echo " $0 down # Stop and remove containers"
echo ""
# Check if docker compose (new format) or docker-compose (old format) is available
if command -v docker &> /dev/null && docker compose version &> /dev/null; then
# Use new docker compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker compose up'..."
docker compose up
else
# Execute the provided docker compose command
echo "Running: docker compose $*"
docker compose "$@"
fi
elif command -v docker-compose &> /dev/null; then
# Fallback to old docker-compose format
if [ $# -eq 0 ]; then
echo "No command provided. Running 'docker-compose up'..."
docker-compose up
else
# Execute the provided docker-compose command
echo "Running: docker-compose $*"
docker-compose "$@"
fi
else
echo "Error: Neither 'docker compose' nor 'docker-compose' command found."
echo "Please install Docker Compose to use this script."
exit 1
fi

18
Docker/RCEO-AIOS-Public-Tools-DocMaker-Light/docker-compose.yml Normal file
View File

@@ -0,0 +1,18 @@
version: '3.8'
services:
docmaker-light:
build:
context: .
dockerfile: Dockerfile
container_name: RCEO-AIOS-Public-Tools-DocMaker-Light
image: rceo-aios-public-tools-docmaker-light:latest
volumes:
- ../../../:/workspace:rw
working_dir: /workspace
stdin_open: true
tty: true
environment:
- LOCAL_USER_ID=${LOCAL_USER_ID:-1000}
- LOCAL_GROUP_ID=${LOCAL_GROUP_ID:-1000}
user: "${LOCAL_USER_ID:-1000}:${LOCAL_GROUP_ID:-1000}"

80
Docker/RCEO-AIOS-Public-Tools-DocMaker/README.md
View File

@@ -1,80 +0,0 @@
# RCEO-AIOS-Public-Tools-DocMaker Container
This container is part of the AIOS-Public project and provides a comprehensive documentation generation environment.
## Overview
The RCEO-AIOS-Public-Tools-DocMaker container is designed for documentation generation tasks. It includes a wide range of tools for creating, converting, and processing documentation in various formats.
## Tools Included
### Core Tools
- **Base OS**: Debian Bookworm slim
- **Shell**: Bash
- **Programming Languages**:
- Python 3
- Node.js
- Rust (with Cargo)
### Documentation Generation
- **Pandoc**: Universal document converter
- **mdBook**: Create books from Markdown files
- **mdbook-pdf**: PDF renderer for mdBook
- **Typst**: Modern typesetting system
- **Marp CLI**: Create presentations from Markdown
### LaTeX
- **TeX Live Full**: Complete LaTeX distribution for advanced document typesetting
### Spell and Grammar Checking
- **Hunspell**: Spell checker (with en-US dictionary)
- **Aspell**: Spell checker (with en dictionary)
- **Vale**: Syntax-aware linter for prose
### Text Analysis
- **mdstat**: Text statistics including reading time estimation
## Usage
### Building the container
```bash
# From the Docker directory
cd /home/localuser/AIWorkspace/AIOS-Public/Docker
docker-compose build docmaker
```
### Running the container
```bash
# Start an interactive session
docker-compose run docmaker
# Run a specific command
docker-compose run docmaker [command]
# Example: Convert a Markdown file to PDF using pandoc
docker-compose run docmaker pandoc input.md -o output.pdf
# Example: Check spelling in a document
docker-compose run docmaker hunspell -d en_US document.md
# Example: Generate reading time statistics
docker-compose run docmaker python3 -m mdstat document.md
```
### Using with docker-compose
```bash
# Build and start the container in one command
docker-compose up --build
# Start without rebuilding
docker-compose up
```
## Volumes
The container maps:
- Project root (`/home/localuser/AIWorkspace/AIOS-Public`) to `/workspace` inside the container (mapped as `../../` from the container directory)
## Purpose
This container should be used for projects that need to generate finished documentation in various formats (PDF, HTML, presentations, etc.) with integrated spell/grammar checking and reading time estimation.

15
Docker/RCEO-AIOS-Public-Tools-DocMaker/docker-compose.yml
View File

@@ -1,15 +0,0 @@
version: '3.8'
services:
docmaker:
build:
context: .
dockerfile: Dockerfile
container_name: RCEO-AIOS-Public-Tools-DocMaker
image: rceo-aios-public-tools-docmaker:latest
volumes:
- ../../:/workspace:rw
working_dir: /workspace
stdin_open: true
tty: true
command: /bin/bash

23
Docker/README.md
View File

@@ -1,31 +1,29 @@
# AIOS-Public Docker Documentation Tools
# RCEO-AIOS-Public Docker Documentation Tools
This directory contains Docker configurations for documentation generation tools in the AIOS-Public project.
This directory contains organized Docker configurations for documentation generation tools in the AIOS-Public project.
## Container Structure
Each container has its own subdirectory with specific configuration files:
- `RCEO-AIOS-Public-Tools-DocMaker/` - Comprehensive documentation generation environment
- `RCEO-AIOS-Public-Tools-DocMaker-Base/` - Base documentation environment with lightweight tools
- `RCEO-AIOS-Public-Tools-DocMaker-Light/` - Fast-starting documentation tools (no heavy LaTeX)
- `RCEO-AIOS-Public-Tools-DocMaker-Full/` - Full documentation environment with LaTeX-full
- `RCEO-AIOS-Public-Tools-DocMaker-Computational/` - All documentation tools plus R, Python, Jupyter, Octave
## Available Containers
## Container Naming Convention
### RCEO-AIOS-Public-Tools-DocMaker
A container with a full suite of documentation tools including:
- Pandoc, mdBook, Typst, Marp for document conversion
- LaTeX for typesetting
- Spell/grammar checking tools (Hunspell, Aspell, Vale)
- Reading time estimation (mdstat)
- Programming languages (Python, Node.js, Rust)
All containers follow the `RCEO-AIOS-Public-Tools-` naming convention with descriptive suffixes.
## Usage
### Building and Running Individual Containers
Each container has its own subdirectory with its Dockerfile and docker-compose.yml file.
```bash
# Navigate to the specific container directory
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Full
# Build the container
docker-compose build
@@ -35,4 +33,5 @@ docker-compose up --build
```
### Individual Container Documentation
For specific usage information for each container, see the README files in their respective subdirectories.

58
Docker/build-containers.sh Executable file
View File

@@ -0,0 +1,58 @@
#!/bin/bash
# build-containers.sh - Script to build all documentation containers
echo "Starting build of RCEO-AIOS-Public documentation containers..."
echo "This may take several minutes, especially for the Full and Computational containers due to LaTeX and other heavy packages."
echo ""
# Build the Base container first (foundation for others)
echo "Building Base container..."
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base
./docker-compose-wrapper.sh build
if [ $? -ne 0 ]; then
echo "Error building Base container. Exiting."
exit 1
fi
echo "Base container build complete"
echo ""
# Build the Light container
echo "Building Light container..."
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Light
./docker-compose-wrapper.sh build
if [ $? -ne 0 ]; then
echo "Error building Light container. Exiting."
exit 1
fi
echo "Light container build complete"
echo ""
# Build the Full container (this will take longer due to LaTeX-full)
echo "Building Full container (this may take several minutes due to texlive-full)..."
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Full
./docker-compose-wrapper.sh build
if [ $? -ne 0 ]; then
echo "Error building Full container. Exiting."
exit 1
fi
echo "Full container build complete"
echo ""
# Build the Computational container (this will also take some time)
echo "Building Computational container..."
cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-Computational
./docker-compose-wrapper.sh build
if [ $? -ne 0 ]; then
echo "Error building Computational container. Exiting."
exit 1
fi
echo "Computational container build complete"
echo ""
echo "All containers built successfully!"
echo ""
echo "You can now run individual containers with:"
echo " cd /home/localuser/AIWorkspace/AIOS-Public/Docker/RCEO-AIOS-Public-Tools-DocMaker-[type]"
echo " ./docker-compose-wrapper.sh up"
echo ""
echo "Where [type] is: Base, Light, Full, or Computational"

6
GUIDEBOOK/AgentRules.md
View File

@@ -13,3 +13,9 @@ Question -> Proposal -> Plan -> Prompt -> Implementation
Expanding on that:
Additional Rules:
- When working with Docker containers, minimize root usage as much as possible. Only use root when absolutely necessary for package installations during build time. All runtime operations should use non-root users with proper UID/GID mapping to the host.
- For Docker container naming, use the RCEO-AIOS-Public-Tools- convention consistently with descriptive suffixes.
- Create thin wrapper scripts that detect and handle UID/GID mapping to ensure file permissions work across any host environment.
- Maintain disciplined naming and organization to prevent technical debt as the number of projects grows.
- Keep the repository root directory clean. Place all project-specific files and scripts in appropriate subdirectories rather than at the top level.