Forge Installation Guide

July 7, 2025 ยท View on GitHub

This guide provides detailed installation instructions for setting up Forge on various platforms.

Table of Contents

Prerequisites

Before installing Forge, ensure you have the following:

  • Python 3.8+ installed
  • pip (Python package manager)
  • git for cloning the repository
  • Docker (optional, for containerized installation)

Installation Methods

Quick Setup Script

The quickest way to get started with Forge is to use the provided setup script:

  1. Clone the repository:

    git clone https://github.com/yourusername/forge.git
cd forge

  2. Run the setup script:

    chmod +x setup.sh
./setup.sh

  3. Start the server:

    python run.py

The setup script performs the following actions:

  • Creates a Python virtual environment
  • Installs all required dependencies
  • Creates a .env file from .env.example
  • Generates secure random keys for encryption and JWT
  • Runs database migrations
  • Sets up the initial database structure

Manual Installation

If you prefer more control over the installation process, follow these steps:

  1. Clone the repository:

    git clone https://github.com/yourusername/forge.git
cd forge

  2. Create a virtual environment:

    python -m venv venv

  3. Activate the virtual environment:

    • On Linux/macOS: 
      source venv/bin/activate
    • On Windows: 
      venv\Scripts\activate

  4. Install dependencies:

    pip install -r requirements.txt

  5. Create a .env file:

    cp .env.example .env

  6. Generate secure keys:

    python -c "import os; from base64 import b64encode; print(f'API_KEY_ENCRYPTION_KEY={b64encode(os.urandom(32)).decode()}')"
python -c "import os; from base64 import b64encode; print(f'JWT_SECRET_KEY={b64encode(os.urandom(32)).decode()}')"

  7. Add the generated keys to your .env file.

  8. Run database migrations:

    alembic upgrade head

  9. Start the server:

    python run.py

    or

    uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Docker Installation

For a containerized deployment:

  1. Clone the repository:

    git clone https://github.com/yourusername/forge.git
cd forge

  2. Build and start with Docker Compose:

    docker-compose up -d

  3. To view logs:

    docker-compose logs -f

  4. To stop the service:

    docker-compose down

Platform-Specific Instructions

Linux

For Debian/Ubuntu-based distributions:

  1. Install system dependencies:

    sudo apt update
sudo apt install -y python3 python3-pip python3-venv git

  2. Follow the Manual Installation or Quick Setup Script instructions.

macOS

  1. Install Homebrew if not already installed:

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Install Python and Git:

    brew install python git

  3. Follow the Manual Installation or Quick Setup Script instructions.

Windows

  1. Install Python from the official website.

  2. Install Git from the official website.

  3. Open Command Prompt or PowerShell and follow the Manual Installation steps, with these Windows-specific adjustments:

    • Clone the repository:

      git clone https://github.com/yourusername/forge.git
cd forge

    • Create and activate a virtual environment:

      python -m venv venv
venv\Scripts\activate

    • Continue with the rest of the manual installation steps.

Verifying Your Installation

To verify that Forge is installed and running correctly:

  1. Open a web browser and navigate to:

    http://localhost:8000/docs

    You should see the Swagger UI API documentation.

  2. Test with the CLI tool:

    ./forge-cli.py interactive

    You should see the interactive menu prompting you for actions.

Troubleshooting

Common Issues

Problem: ModuleNotFoundError when running the application.

Solution: Ensure the virtual environment is activated and all dependencies are installed:

source venv/bin/activate  # On Linux/macOS
venv\Scripts\activate     # On Windows
pip install -r requirements.txt

Problem: Database migration errors.

Solution: Try resetting the migrations and starting from scratch:

rm -rf migrations  # Be cautious with this command!
alembic init migrations
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head

Problem: Permission errors when running the setup script.

Solution: Ensure the script is executable:

chmod +x setup.sh

Problem: API key encryption errors.

Solution: Check that your .env file contains valid base64-encoded encryption keys:

python -c "import os; from base64 import b64encode; print(f'API_KEY_ENCRYPTION_KEY={b64encode(os.urandom(32)).decode()}')"
python -c "import os; from base64 import b64encode; print(f'JWT_SECRET_KEY={b64encode(os.urandom(32)).decode()}')"

Getting Help

If you encounter issues not covered by this guide:

  1. Check the GitHub Issues to see if others have faced the same problem.
  2. Search for similar problems in the project discussions.
  3. Open a new issue if your problem hasn't been addressed yet.

Next Steps

After installation, refer to: