Add organized Docker container structure with disciplined naming

- 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
2025-10-16 11:40:25 -05:00
parent 7fad76ea9d
commit d30f103209
24 changed files with 1055 additions and 131 deletions
--- a/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/Dockerfile
+++ b/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/Dockerfile
@@ -0,0 +1,79 @@
+FROM debian:bookworm-slim
+
+# Avoid prompts from apt
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install base packages
+RUN apt-get update && apt-get install -y \
+    bash \
+    curl \
+    wget \
+    git \
+    python3 \
+    python3-pip \
+    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 (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}"
+
+# Install Pandoc
+RUN apt-get update && apt-get install -y \
+    pandoc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install lightweight LaTeX
+RUN apt-get update && apt-get install -y \
+    texlive-latex-base \
+    texlive-fonts-recommended \
+    texlive-fonts-extra \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install mdBook and mdbook-pdf using cargo
+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 \
+    | tar xJ -C /tmp && cp /tmp/typst-x86_64-unknown-linux-musl/typst /usr/local/bin && chmod +x /usr/local/bin/typst
+
+# 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 \
+    hunspell-en-us \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install vale for advanced style and grammar checking
+RUN curl -L https://github.com/errata-ai/vale/releases/download/v3.12.0/vale_3.12.0_Linux_64-bit.tar.gz \
+    | tar xz -C /tmp && cp /tmp/vale /usr/local/bin && chmod +x /usr/local/bin/vale
+
+# Install text statistics tool for reading time estimation
+RUN pip3 install mdstat textstat
+
+# Install additional text processing tools
+RUN apt-get update && apt-get install -y \
+    aspell \
+    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
+
+# Use the entrypoint script to handle user creation
+ENTRYPOINT ["/entrypoint.sh"]
--- a/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/README.md
+++ b/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/README.md
@@ -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.
--- a/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/TODO.md
+++ b/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/TODO.md
@@ -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
--- a/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/docker-compose-wrapper.sh
+++ b/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/docker-compose-wrapper.sh
@@ -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
--- a/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/docker-compose.yml
+++ b/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/docker-compose.yml
@@ -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}"
--- a/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/entrypoint.sh
+++ b/Docker/RCEO-AIOS-Public-Tools-DocMaker-Base/entrypoint.sh
@@ -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