Skip to content

installation.md

Latest commit

 

History

History
398 lines (276 loc) · 6.81 KB

installation.md

File metadata and controls

398 lines (276 loc) · 6.81 KB
Raw

Installation Guide

Complete guide to installing Forge on your system.

Prerequisites

Required

  • Python 3.11 or higher
  • Git (for version control)

Optional

  • Docker (for isolated testing)
  • Poetry (will be installed if not present)

System Requirements

  • OS: macOS, Linux, or Windows (with WSL2)
  • RAM: 2GB minimum, 4GB recommended
  • Disk: 500MB for dependencies + embeddings model

Installation Steps

1. Install Poetry

Poetry is Forge's dependency manager.

macOS/Linux

curl -sSL https://install.python-poetry.org | python3 -

Add Poetry to PATH

export PATH="/Users/$USER/.local/bin:$PATH"

# Make permanent (zsh)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# Make permanent (bash)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Verify Installation

poetry --version
# Output: Poetry (version 2.2.1)

2. Clone/Download Forge

cd /path/to/your/projects
# If you have Forge in a directory already:
cd forge

3. Install Dependencies

# Install all dependencies
poetry install

# This will:
# - Create a virtual environment
# - Install 63+ dependencies
# - Install Forge CLI
# - Download embedding model (~90MB)

Expected output:

Updating dependencies
Resolving dependencies...
Package operations: 63 installs, 0 updates, 0 removals
...
Installing the current project: forge (1.0.0)

Note: First install will download the sentence-transformers model (~90MB). This is normal and only happens once.

4. Verify Installation

# Check Forge version
poetry run forge --version
# Output: forge, version 1.0.0

# Run system health check
poetry run forge doctor

Expected output:

✓ Python 3.11.13
✓ git installed
✓ docker installed
✓ KnowledgeForge patterns (28 files)
✓ Compound Engineering plugin
✨ Forge health check complete!

5. Set Up KnowledgeForge Patterns

Forge requires KnowledgeForge patterns in a sibling directory:

# Create patterns directory
mkdir -p patterns

# Copy your .md pattern files there
cp /path/to/patterns/*.md patterns/

# Verify patterns
ls patterns/*.md | wc -l
# Should show: 28

6. Optional: Configure Forge

Create a configuration file:

# Project config (recommended)
poetry run forge config

# Global config (applies to all projects)
poetry run forge config --global-config

This creates forge.yaml with default settings.

Post-Installation

Install as Global CLI Command (Recommended)

To use forge directly without typing poetry run every time:

pip install -e .

Now you can run Forge from anywhere:

forge --version
forge doctor
forge review panel

This is the recommended setup for daily use.

Alternative: Poetry Shell (Temporary)

If you prefer not to install globally, use Poetry's shell:

poetry shell

# Now you can run commands directly:
forge doctor
forge search "patterns"

# Exit when done:
exit

Note: poetry shell only works in the current terminal session.

Configure Environment Variables

If using CodeGen API:

# Add to ~/.zshrc or ~/.bashrc
export CODEGEN_API_KEY="your-api-key"
export CODEGEN_ORG_ID="your-org-id"

Test the Installation

Run the test suite:

poetry run pytest -v

# Expected: 26 passed in ~17s

Docker Installation (Optional)

For isolated testing capabilities:

macOS

brew install --cask docker
# Or download from: https://www.docker.com/products/docker-desktop

Linux

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io

# Enable Docker
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER

Verify Docker

docker --version
docker run hello-world

Troubleshooting Installation

Poetry Installation Issues

If curl command fails:

# Download installer manually
wget https://install.python-poetry.org -O install-poetry.py
python3 install-poetry.py

Python Version Issues

Check Python version:

python3 --version
# Must be 3.11 or higher

If too old, install Python 3.11+:

# macOS
brew install python@3.11

# Ubuntu
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install python3.11

Dependency Installation Failures

Clear cache and retry:

poetry cache clear pypi --all
poetry install --no-cache

Pattern Store Issues

If patterns aren't found:

# Check directory structure
ls -la patterns/

# Should show .md files
# If not, create and populate:
mkdir -p patterns
# Copy your pattern files

Permission Errors

# Ensure Forge directory is writable
chmod -R 755 .

# Create .forge directory manually
mkdir -p .forge
chmod 755 .forge

ImportError Issues

Ensure you're using Poetry's environment:

# Show which Python
poetry run which python

# Should point to Poetry's virtual environment
# Example: ~/.cache/pypoetry/virtualenvs/forge-*/bin/python

Uninstalling

Remove Forge

# Remove virtual environment
poetry env remove python

# Remove installed files
rm -rf .venv/
rm -rf dist/
rm -rf *.egg-info/

Remove Poetry

curl -sSL https://install.python-poetry.org | python3 - --uninstall

Remove Data

# Remove project data
rm -rf .forge/

# Remove global config
rm -rf ~/.forge/

Next Steps

After successful installation:

  1. Read the Quick Start Guide
  2. Follow the Tutorial
  3. Review the User Guide
  4. Configure Forge: Configuration Guide

Platform-Specific Notes

macOS

  • Use zsh (default shell)
  • Homebrew recommended for dependencies
  • Docker Desktop provides easy Docker setup

Linux

  • Use bash or zsh
  • Package manager varies by distribution
  • Docker requires additional setup

Windows (WSL2)

  • Install WSL2 first
  • Use Ubuntu 20.04+ in WSL
  • Follow Linux instructions within WSL

Updating Forge

# Update dependencies
poetry update

# Update to specific version
poetry add forge@^1.1.0

# Check for updates
poetry show --outdated

Getting Help

If you encounter issues:

  1. Run forge doctor to check system health
  2. Check Troubleshooting Guide
  3. Review error messages carefully
  4. Run tests: poetry run pytest -v
  5. Check Python version: python3 --version

Verification Checklist

After installation, verify:

  • poetry --version shows Poetry 2.2.1+
  • pip install -e . completes successfully
  • forge --version shows forge 1.0.0
  • forge doctor passes all checks
  • ls patterns/*.md shows pattern files
  • poetry run pytest shows tests passing
  • .forge/patterns.db exists after running forge doctor

Once all items are checked, you're ready to use Forge!