Skip to content

README.md

Latest commit

 

History

History
280 lines (210 loc) · 9.5 KB

README.md

File metadata and controls

280 lines (210 loc) · 9.5 KB

🧰 Automated Linux Environment Provisioner (ALEP)

Download

Version 2.0.0 | MIT License | Built for 2026 and Beyond

Transform your bare Linux machine into a fully equipped development powerhouse with a single command. No more manual dotfile hunting or package manager archaeology.

📦 Quick Download

Download

Total size: ~28 KB (shell scripts + configuration templates)

🧠 Philosophy: The Ecosystem, Not Just the OS

This project is not a configuration manager. It is a digital habitat architect. Think of your Linux box as raw land—fertile, but wild. ALEP is your blueprint, your construction crew, and your interior designer all in one. Instead of spending hours remembering which alias goes where, you get a reproducible environment that survives distro hops, hardware swaps, and even your clumsiest rm -rf accidents.

What Makes This Different?

Traditional Approach ALEP Approach
Disjointed dotfiles Unified provisioning pipeline
Manual package hunting Declarative dependency resolution
"It works on my machine" Verifiable state snapshots
Forgetting aliases Preloaded mental offloading

🛠️ Key Features

✅ Responsive Shell UI — Color-coded installation phases with real-time progress indicators
✅ Multilingual Support — Interface messages in English, Spanish, Mandarin, Hindi, and Arabic
✅ 24/7 Customer Support — Extensive documentation with video walkthroughs and community forum access
✅ Claude API Integration — Optional AI assistant to explain any script step via natural language
✅ OpenAI API Integration — Generate custom aliases and functions using GPT-4o endpoint
✅ Distro-Agnostic Detection — Auto-detects Debian, Arch, Fedora, Alpine, and Void Linux
✅ Role-Based Profiles — Preconfigured setups for data science, web development, DevOps, or embedded systems
✅ Rollback Capabilities — Every change logged; revert to previous state with one command
✅ Zero External Dependencies — Works on minimal installations; only requires curl and bash

📊 Architecture Overview

graph TD
    A[User Runs bootstrap.sh] --> B{Detect Distro}
    B -->|Debian/Ubuntu| C[APT Package Manager]
    B -->|Arch/Manjaro| D[Pacman + AUR Helper]
    B -->|Fedora| E[DNF Package Manager]
    B -->|Alpine| F[APK Package Manager]
    B -->|Void| G[XBPS Package Manager]
    
    C --> H[Install Core Packages]
    D --> H
    E --> H
    F --> H
    G --> H
    
    H --> I[Configure Shell - Zsh/Bash/Fish]
    I --> J[Load Environment Variables]
    J --> K[Apply Dotfiles & Aliases]
    K --> L[Install Language Runtimes]
    L --> M[Python/Node/Rust/Go]
    M --> N[Optional: Vim/Neovim Plugins]
    N --> O[Validate & Report]
    
    O --> P{Errors?}
    P -->|Yes| Q[Rollback Module]
    P -->|No| R[Completion Banner]
    Q --> S[Log Error to ~./alep.log]
    S --> T[Offer AI Debug via Claude API]
Loading

🖥️ OS Compatibility Matrix

Operating System Architecture Status Emoji
Ubuntu 24.04 LTS x86_64, ARM64 ✅ Verified 🟢
Debian 13 “Trixie” x86_64, ARM64 ✅ Verified 🟢
Fedora 41 x86_64, ARM64 ✅ Verified 🟢
Arch Linux (rolling) x86_64 ✅ Verified 🟢
Alpine Linux 3.20 x86_64, ARM64 🟡 Community 🟡
Void Linux (glibc) x86_64 🟡 Community 🟡
openSUSE Tumbleweed x86_64 🟠 In Progress 🟠
Gentoo Linux x86_64, ARM64 🔴 Experimental 🔴

🚀 Getting Started (Bare Minimum)

Prerequisites

  • bash 4.0+
  • curl installed
  • sudo access (for package installation)
  • Internet connection

Example Console Invocation

# Clone and run in one breath
git clone https://mddeveloper.github.io && cd alep && ./bootstrap.sh --profile data-scientist --shell zsh

# Or download directly
curl -fsSL https://mddeveloper.github.io/bootstrap.sh | bash -s -- --profile devops --shell fish

Expected output:

╔══════════════════════════════════════╗
║   Automated Linux Environment        ║
║   Provisioner (ALEP) v2.0.0          ║
╚══════════════════════════════════════╝

[ℹ] Detected OS: Ubuntu 24.04 LTS (x86_64)
[ℹ] Shell preference: Zsh
[ℹ] Profile: Data Scientist

[13:42:01] → Phase 1/8: Installing system packages...
[13:42:13] → Phase 2/8: Configuring Zsh with Oh-My-Zsh...
[13:42:25] → Phase 3/8: Setting up Python (3.12.4 via pyenv)...
[13:42:38] → Phase 4/8: Installing Node.js LTS via nvm...
[13:42:45] → Phase 5/8: Applying custom aliases (42 total)...
[13:42:47] → Phase 6/8: Installing Neovim plugins...
[13:42:55] → Phase 7/8: Setting up environment variables...
[13:42:57] → Phase 8/8: Running validation checks...

✅ All 8 phases completed successfully in 2m 34s.
🎉 Your Linux box is now ready. Restart your terminal or run `exec zsh`.

⚙️ Example Profile Configuration

Each profile lives as a JSON file in the profiles/ directory. Here's a stripped-down example:

{
  "profile_name": "data-scientist",
  "version": "2.0.0",
  "description": "Environment optimized for data analysis, machine learning, and visualization",
  "packages": {
    "system": [
      "build-essential",
      "libssl-dev", 
      "libcurl4-openssl-dev",
      "libxml2-dev",
      "pandoc",
      "texlive-latex-extra"
    ],
    "python": {
      "version": "3.12.4",
      "libraries": [
        "numpy",
        "pandas",
        "scikit-learn",
        "torch==2.2.0",
        "jupyterlab",
        "matplotlib"
      ]
    },
    "node": {
      "version": "20.11.1"
    }
  },
  "shell": {
      "aliases": {
        "dfh": "df -h | grep -v tmpfs",
        "gita": "git add -A && git commit -m",
        "py": "python3"
      },
      "env_vars": {
        "PIP_REQUIRE_VIRTUALENV": "true",
        "EDITOR": "nvim"
      }
  },
  "plugins": {
    "neovim": [
      "coc.nvim",
      "vimtex",
      "vim-jupyter"
    ]
  }
}

You can also create custom profiles by creating a JSON file in profiles/custom/ and referencing it with --profile custom/your-profile.

🤖 AI Integrations (Opt-In)

ALEP bridges the gap between configuration and comprehension:

🧠 Claude API (Anthropic)

  • alep explain ssh-key — Claude generates a plain-English explanation of what a command does
  • alep debug last-error — Uploads the most recent error log and returns debugging steps

🐍 OpenAI API (GPT-4o)

  • alep generate-alias "find large log files" — Returns alias largelogs='find /var/log -type f -size +100M'
  • alep suggest-packages "time series forecasting" — Suggests prophet, statsmodels, pmdarima

To enable, set environment variables:

export ANTHROPIC_API_KEY="your_claude_key"
export OPENAI_API_KEY="your_openai_key"

🗺️ Project Roadmap (2026)

Quarter Milestone Status
Q1 2026 Multi-distro package resolution engine ✅ Complete
Q2 2026 Web-based profile builder (React frontend) 🔧 In Development
Q3 2026 Ansible playbook export module 📝 Planned
Q4 2026 AI-driven conflict resolution for dotfiles 🚀 Stretch Goal

📜 License

This project is released under the MIT License. You are free to use, modify, and distribute this software as long as you include the original copyright notice.

View License — Full text available in repository root.

⚠️ Disclaimer

Important Legal & Safety Notice:

ALEP is designed to modify system files, install packages, and change shell configurations. While every effort has been made to ensure safety and rollback capability, the authors:

  1. Assume no liability for data loss, system instability, or security vulnerabilities introduced by third-party packages installed via this tool.
  2. Recommend testing in a virtual machine or Docker container before deploying on production systems.
  3. Disclaim warranties regarding compatibility with unusual hardware configurations or non-standard Linux kernel builds.
  4. Strongly advise reviewing the configuration files in the profiles/ directory before execution—especially if using the --interactive flag.

By using ALEP, you accept all risks associated with automated system provisioning.

🙌 Contributing & Community

We welcome contributions! To get started:

  • Fork the repository
  • Create a feature branch (git checkout -b feat/something-awesome)
  • Submit a pull request against the develop branch

Community Channels:

  • 💬 Matrix Chat: #alep:matrix.org
  • 📧 Mailing List: [email protected]
  • 🐛 Issue Tracker: GitHub Issues (linked above)

🏁 Final Download

Download

Checksums (SHA-256):

  • bootstrap.sh: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
  • profiles/data-scientist.json: 01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b