Skip to content

bernardoamorimalvarenga/EnvForge

BranchesTags

Repository files navigation

🔥 EnvForge

Forge, sync and restore complete development environments in minutes

Python Platform License Status

🎯 What is it?

EnvForge is a CLI tool that solves one of developers' biggest problems: reconfiguring development environments from scratch.

Instead of spending days installing packages, setting up dotfiles and extensions every time you:

  • 💻 Get a new laptop
  • 🔄 Format your system
  • 👥 Need to standardize your team
  • 🏠 Want to sync home/work setups

You simply restore everything automatically with EnvForge!

🆚 EnvForge vs Other Tools

EnvForge Git/GitHub Docker Dotfiles Repos
What it manages 🖥️ Complete environment 📝 Source code 📦 Isolated containers 📄 Config files only
Installs packages ✅ 271 APT packages ❌ ❌ ❌
System configuration ✅ Dotfiles + extensions ❌ ❌ ✅ Configs only
Synchronization ✅ Bidirectional Git ✅ Code only ❌ ✅ Configs only
Use case 🛠️ Complete personal setup 📂 Code projects 🚀 App deployment ⚙️ Basic configs

Practical Example:

❌ Current Situation (2 days of work):

# New/reformatted laptop:
sudo apt update && sudo apt install git curl vim...    # 271 packages manually
code --install-extension ms-python.python...          # 15+ VS Code extensions  
cp dotfiles/.bashrc ~/.bashrc                         # Configure terminal
git config --global user.name...                      # Git configs
# ... hundreds of manual steps

✅ With EnvForge (30 minutes):

pip install envforge
envforge restore "my-complete-environment"
# ☕ Go grab a coffee - everything automated!

🚀 Installation

Method 1: Direct Installation (Recommended)

# Install via PyPI
pip install envforge

Method 2: Manual Installation

# Clone the repository
git clone https://github.com/bernardoamorimalvarenga/envforge.git
cd envforge

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Test installation
envforge --help

System Requirements:

  • 🐧 Linux (Ubuntu 20.04+, Debian 10+, Arch, Fedora)
  • 🐍 Python 3.8+
  • 🔑 sudo (for package installation)
  • 📦 git (for synchronization)

📋 Complete Usage Guide

1. Initial Setup

# Initialize EnvForge
envforge init

# ✅ Output:
# 🔥 EnvForge initialized successfully!
# Config stored in: /home/user/.envforge

2. Capture Your Current Environment

# Capture everything installed and configured
envforge capture "my-setup-$(date +%Y%m%d)"

# ✅ Example output:
# 🔥 Capturing environment: my-setup-20241201
# ✓ Detecting system configuration...
# 
# ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
# ┃ Component          ┃ Count ┃
# ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
# │ APT Packages       │ 271   │
# │ Snap Packages      │ 26    │
# │ Flatpak Packages   │ 3     │
# │ PIP Packages       │ 45    │
# │ Dotfiles           │ 8     │
# │ VS Code Extensions │ 23    │
# └────────────────────┴───────┘
# ✓ Environment 'my-setup-20241201' captured successfully!

3. List Saved Environments

# List all captured environments
envforge list

# ✅ Example output:
# ┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Name                 ┃ Created         ┃ File                ┃
# ┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
# │ my-setup-20241201    │ 2024-12-01 14:30│ my-setup-20241201.json │
# │ work-environment     │ 2024-11-28 09:15│ work-environment.json  │
# │ complete-setup       │ 2024-11-25 16:45│ complete-setup.json    │
# └──────────────────────┴─────────────────┴─────────────────────────┘

4. View Environment Details

# See what a specific environment contains
envforge show "my-setup-20241201"

# ✅ Example output:
# 📋 Environment Details: my-setup-20241201
# 
# ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Property           ┃ Value                        ┃
# ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
# │ Os                 │ Linux                        │
# │ Kernel             │ 5.15.0-91-generic           │
# │ Architecture       │ x86_64                       │
# │ Python Version     │ 3.12.3                      │
# │ Shell              │ /bin/bash                    │
# └────────────────────┴─────────────────────────────┘
# 
# ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
# ┃ Type               ┃ Count ┃
# ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
# │ APT                │ 271   │
# │ SNAP               │ 26    │
# │ FLATPAK            │ 3     │
# │ PIP                │ 45    │
# └────────────────────┴───────┘

5. Restore an Environment

Safe Preview (Dry Run):

# See what will be done WITHOUT applying changes
envforge restore "my-setup-20241201" --dry-run

# ✅ Example output:
# 🔍 DRY RUN MODE - No changes will be made
# 📦 Restoring packages...
# Would install 45 new APT packages
# Would install: git vim curl nodejs python3-pip code...
# 📝 Would restore 8 dotfiles
# 🔌 Would install 12 new VS Code extensions
# ✓ Dry run completed successfully!

Actual Restoration:

# Restore the environment (WILL INSTALL PACKAGES)
envforge restore "my-setup-20241201"

# ✅ Interactive process:
# 🔥 Restoring environment: my-setup-20241201
# 
# ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
# ┃ Type               ┃ Count ┃
# ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
# │ APT                │ 45    │
# │ SNAP               │ 8     │
# │ PIP                │ 12    │
# └────────────────────┴───────┘
# 
# ⚠️  This will install 65 packages and may modify your system.
# Do you want to continue? [y/N]: y
# 
# 📦 Installing APT packages...
# ✓ APT packages installed successfully
# 📝 Restoring dotfiles...
# Backed up existing .bashrc to .bashrc.envforge-backup
# ✓ Restored .bashrc
# ✓ Restored .vimrc
# 🔌 Installing VS Code extensions...
# ✓ VS Code extensions installed successfully
# ✓ Environment restored successfully!

🔄 Git Synchronization (Multi-machine)

Initial Setup (Once)

# Configure synchronization with private repository
envforge sync setup [email protected]:your-user/envforge-private.git

# ✅ Output:
# 🔧 Setting up git sync with [email protected]:your-user/envforge-private.git
# 
# ╭─ Sync Ready ─╮
# │ Git sync setup complete! │
# │                          │
# │ Repository: [email protected]:your-user/envforge-private.git │
# │ Branch: main             │
# │                          │
# │ Use 'envforge sync push' to upload environments │
# │ Use 'envforge sync pull' to download environments │
# ╰──────────────╯

Pushing Environments

# Send all environments to repository
envforge sync push

# Send only a specific environment
envforge sync push -e "my-setup-20241201"

# Send multiple environments
envforge sync push -e "environment1" -e "environment2"

# ✅ Example output:
# 📤 Pushing specific environments: my-setup-20241201
# ✓ Successfully pushed 1 specific environments

Downloading Environments

# Download environments from repository
envforge sync pull

# ✅ Example output:
# 📥 Pulling environments from remote...
# ✓ Imported work-environment
# ✓ Imported home-setup
# ✓ Successfully imported 2 environments

Synchronization Status

# View sync status
envforge sync status

# ✅ Example output:
# ┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Property           ┃ Value                                               ┃
# ┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
# │ Status             │ ✓ Enabled                                          │
# │ Remote URL         │ [email protected]:your-user/envforge-private.git     │
# │ Branch             │ main                                               │
# │ Uncommitted Changes │ No                                                │
# │ Last Commit        │ abc123 - Sync 2 environments                      │
# └────────────────────┴────────────────────────────────────────────────────┘

💼 Practical Use Cases

🆕 Case 1: New Laptop

# On old machine:
envforge capture "my-complete-setup"
envforge sync push

# On new machine:
pip install envforge
envforge init
envforge sync setup [email protected]:your-user/envforge-private.git
envforge sync pull
envforge restore "my-complete-setup"
# ☕ 30 minutes later: identical environment!

👥 Case 2: Team Onboarding

# Company setup (done once by tech lead):
envforge capture "company-dev-env-2024"  
envforge sync push

# New developer:
envforge sync pull
envforge restore "company-dev-env-2024"
# 🎉 Standardized environment automatically!

🏠 Case 3: Home/Work Synchronization

# At work:
envforge capture "work-setup"
envforge sync push

# At home:
envforge sync pull
envforge restore "work-setup" 
# 🔄 Same environment at home!

🔄 Case 4: Backup/Disaster Recovery

# Regular backup:
envforge capture "backup-$(date +%Y%m%d)"
envforge sync push

# After problem/reformatting:
envforge sync pull
envforge list  # View available backups
envforge restore "backup-20241201"
# 🛡️ Environment restored!

📊 Available Commands

Basic Commands:

envforge init                    # Initialize EnvForge
envforge capture "name"          # Capture current environment
envforge list                    # List saved environments
envforge show "name"             # Show environment details  
envforge restore "name"          # Restore environment
envforge delete "name"           # Delete environment
envforge status                  # Current system status

Sync Commands:

envforge sync setup <repo-url>   # Configure Git synchronization
envforge sync push               # Send all environments
envforge sync push -e "name"     # Send specific environment
envforge sync pull               # Download environments from repository
envforge sync status             # Synchronization status

Utility Commands:

envforge export "name" file.json    # Export to file
envforge import-env file.json       # Import from file
envforge diff "env1" "env2"         # Compare environments
envforge clean                      # Clean old backups

Useful Options:

envforge restore "name" --dry-run     # Preview without applying changes
envforge restore "name" --force       # Skip confirmations
envforge delete "name" --force        # Delete without confirmation

🎯 What Gets Captured

📦 System Packages:

  • APT packages (manually installed only)
  • Snap packages
  • Flatpak packages
  • PIP packages (global)

⚙️ Configurations:

  • Important dotfiles: .bashrc, .bash_profile, .zshrc, .profile
  • Tool configs: .vimrc, .gitconfig
  • SSH config: .ssh/config (optional, disabled by default)

🔌 Extensions and Tools:

  • VS Code: All installed extensions
  • System info: OS, kernel, architecture, Python version

Example Snapshot (JSON):

{
  "metadata": {
    "name": "my-setup-20241201",
    "created_at": "2024-12-01T14:30:00",
    "version": "0.1.0"
  },
  "system_info": {
    "os": "Linux",
    "kernel": "5.15.0-91-generic",
    "architecture": "x86_64",
    "python_version": "3.12.3"
  },
  "packages": {
    "apt": ["git", "vim", "curl", "nodejs", "python3-pip"],
    "snap": ["code", "discord", "telegram-desktop"],
    "pip": ["requests", "flask", "django"]
  },
  "dotfiles": {
    ".bashrc": "# .bashrc content...",
    ".vimrc": "# Vim configurations..."
  },
  "vscode_extensions": [
    "ms-python.python",
    "ms-vscode.vscode-json"
  ]
}

🔒 Security

✅ Secure Settings:

  • SSH keys are not captured by default
  • Automatic backups of existing files before replacement
  • Dry-run mode for safe previews
  • Confirmations before important changes
  • Private repositories recommended for sync

⚠️ Important Considerations:

  • Use private repositories for sensitive data
  • Review snapshots before sharing
  • Dotfiles may contain personal information
  • Always test with --dry-run first

🛡️ Best Practices:

# ✅ Use private repository
envforge sync setup [email protected]:your-user/envforge-PRIVATE.git

# ✅ Always preview first
envforge restore "environment" --dry-run

# ✅ Manual backup before major changes
cp ~/.bashrc ~/.bashrc.backup-$(date +%s)

# ✅ Review what will be installed
envforge show "environment"

🚀 Performance

Typical Times:

  • Capture: ~30 seconds (271 packages + configs)
  • Restore APT: ~15 minutes (271 packages)
  • Restore Snap: ~5 minutes (26 packages)
  • Dotfiles: ~1 second
  • VS Code extensions: ~2 minutes

Sizes:

  • Snapshot JSON: ~16KB per environment
  • Sync repository: ~1MB (10 environments)

🐛 Troubleshooting

Common Issues:

"Permission denied" during restore:

# Make sure you have sudo
sudo echo "test"

# Execute with confirmation
envforge restore "environment" --force

"Git sync failed":

# Check if repository is private and you have access
git clone [email protected]:your-user/envforge-private.git

# Reconfigure if necessary
envforge sync setup [email protected]:your-user/envforge-private.git

"VS Code extensions failed":

# Make sure VS Code is installed
code --version

# Install manually if necessary
envforge show "environment"  # View extension list

Logs and Debug:

# View detailed status
envforge status

# Check config files
ls -la ~/.envforge/

# Preview before applying
envforge restore "environment" --dry-run

🤝 Contributing

Contributions are welcome!

How to Contribute:

  1. Fork the repository
  2. Create a branch for your feature (git checkout -b feature/new-functionality)
  3. Commit your changes (git commit -am 'Add new functionality')
  4. Push to the branch (git push origin feature/new-functionality)
  5. Open a Pull Request

Areas That Need Help:

  • Support for other distros (CentOS, OpenSUSE)
  • Additional package managers (brew, chocolatey)
  • Automated testing
  • Documentation
  • Graphical interface

🗺️ Roadmap

v0.2.0 - Security (Implemented)

  • [✅] Snapshot encryption
  • [✅] Safe package list (whitelist)
  • [✅] Sensitive data filtering
  • [✅] Integrity verification

v0.3.0 - Multi-OS (8 weeks)

  • Windows support (WSL)
  • macOS support
  • Homebrew support
  • Chocolatey support

v1.0.0 - GUI and Cloud (12 weeks)

  • Graphical interface (PyQt6)
  • Cloud storage (Google Drive, Dropbox)
  • Community templates
  • Pro version with advanced features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Bernardo

🙏 Acknowledgments

  • Click - Fantastic CLI framework
  • Rich - Beautiful colored interface
  • Git - Robust sync system
  • Python Community - Amazing tools

⭐ Like the Project?

If EnvForge helped you, consider:

  • ⭐ Give it a star on GitHub
  • 🐛 Report bugs or suggest improvements
  • 📢 Share with other developers
  • 🤝 Contribute with code or documentation

🔥 Stop manually reconfiguring environments - forge with EnvForge! 🔥

🇧🇷 Português | 🇺🇸 English

About

No description or website provided.

Topics

python git linux cli sync devops automation backup developer-tools development-enviroment

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

30 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 1

EnvForge v0.1.3 - Security Fixes Latest
May 28, 2025

Packages

No packages published

Languages