Skip to main content

Installation

Get ALFA up and running on your machine in minutes!

Prerequisites​

Before installing ALFA, make sure you have:

Installation Steps​

1. Clone the Repository​

git clone https://github.com/OZIOisgood/alfa.git
cd alfa

2. Install Python Dependencies​

Using UV (recommended):

uv sync

Or using pip:

pip install -r requirements.txt

3. Set Up Credentials​

Google Cloud Credentials​

  1. Create a Google Cloud project
  2. Enable the following APIs:
    • Text-to-Speech API
    • Vertex AI API
  3. Create a service account
  4. Download the JSON key file
  5. Place it in .credentials/alfa_gcp_sa.json

API Keys​

Create a .env file in the project root:

# Google Cloud
GCP_PROJECT_ID=your-project-id
GCP_LOCATION=us-central1

# OpenRouter (optional)
OPENROUTER_API_KEY=your-openrouter-key

Docker provides isolated rendering with all LaTeX packages:

docker build -t alfa-manim:latest .

5. Verify Installation​

Test the Gradio app:

uv run python run-gradio.py

Visit http://127.0.0.1:7865 - you should see the ALFA interface!

Platform-Specific Notes​

Windows​

  • Install FFmpeg via Chocolatey: 
    choco install ffmpeg
  • Use PowerShell or Windows Terminal

macOS​

  • Install FFmpeg via Homebrew: 
    brew install ffmpeg

Linux​

  • Install FFmpeg: 
    sudo apt-get install ffmpeg  # Ubuntu/Debian
    sudo yum install ffmpeg      # CentOS/RHEL

Troubleshooting​

Docker Issues​

If Docker build fails:

# Clean and rebuild
docker system prune -a
docker build --no-cache -t alfa-manim:latest .

LaTeX Errors​

If you see LaTeX errors without Docker:

  1. Install MiKTeX (Windows) or TeX Live (Linux/Mac)
  2. Or use Docker for guaranteed LaTeX support

Module Not Found​

If you see import errors:

# Reinstall dependencies
uv sync --reinstall

Port Already in Use​

If port 7865 is taken:

Edit apps/gradio/main.py and change:

app.launch(server_port=7865)  # Change to another port

Updating ALFA​

Pull the latest changes:

git pull origin main
uv sync  # Update dependencies
docker build -t alfa-manim:latest .  # Rebuild Docker image

Next Steps​

Need help? Open an issue on GitHub!