Skip to content

Post-Installation Setup

Complete these steps after installing ModelForge to ensure everything is configured correctly.

Verify Installation

1. Check ModelForge Version

modelforge --version

Should display: ModelForge v2 (or current version)

2. Verify GPU Detection

python -c "import torch; print(f'CUDA Available: {torch.cuda.is_available()}'); print(f'GPU Count: {torch.cuda.device_count()}'); print(f'GPU Name: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"None\"}')"

Expected output (with GPU): 

CUDA Available: True
GPU Count: 1
GPU Name: NVIDIA GeForce RTX 3060

3. Test Basic Import

python -c "from ModelForge import app; print('ModelForge imported successfully!')"

Configure HuggingFace Token

Your HuggingFace token is required to download models.

Get Your Token

  1. Go to HuggingFace Settings
  2. Click "New token"
  3. Give it a name (e.g., "ModelForge")
  4. Select type: Fine-grained or Write
  5. Copy the token

Set Token

Linux (persistent): 

echo 'export HUGGINGFACE_TOKEN="hf_xxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell (persistent): 

[System.Environment]::SetEnvironmentVariable('HUGGINGFACE_TOKEN', 'hf_xxxxxxxxxxxx', 'User')

Using .env file (all platforms): 

cd ~/ModelForge  # or your project directory
echo "HUGGINGFACE_TOKEN=hf_xxxxxxxxxxxx" > .env

First Run

Start ModelForge

modelforge run

You should see: 

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

Access Web Interface

Open browser: http://localhost:8000

You should see the ModelForge interface with: - Dashboard - Training tab - Playground tab - Models tab

Verify Features

Check Available Providers

Open browser console and make API call: 

fetch('http://localhost:8000/api/info')
  .then(r => r.json())
  .then(d => console.log(d))

Should show: 

{
  "providers": ["huggingface", "unsloth"],
  "strategies": ["sft", "qlora", "rlhf", "dpo"],
  "tasks": ["text-generation", "summarization", "extractive-question-answering"]
}

Test Health Endpoint

curl http://localhost:8000/api/health

Should return: 

{
  "status": "healthy",
  "version": "v2"
}

Directory Structure

ModelForge creates the following directories:

Linux: 

~/.local/share/modelforge/
├── database/              # SQLite database
├── datasets/              # Uploaded datasets
├── model_checkpoints/     # Trained models
└── training_logs/         # TensorBoard logs

Windows: 

C:\Users\<username>\AppData\Local\modelforge\
├── database\
├── datasets\
├── model_checkpoints\
└── training_logs\

Optional: Install Additional Providers

Install Unsloth (2x Faster Training)

Linux/WSL: 

pip install unsloth

Verify: 

python -c "import unsloth; print('Unsloth installed successfully!')"

Windows Users: Unsloth requires WSL or Docker. See Windows Installation Guide.

Configure Advanced Settings

Custom Port

Run on different port: 

modelforge run --port 8080

Bind to All Interfaces

Allow remote access: 

modelforge run --host 0.0.0.0

Configure Database Path

Set custom database location: 

export MODELFORGE_DB_PATH="/path/to/database"
modelforge run

Performance Tuning

GPU Memory Optimization

Add to .env: 

PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512

Disable TensorBoard (Save Memory)

export MODELFORGE_DISABLE_TENSORBOARD=1

Set Default Batch Size

export MODELFORGE_DEFAULT_BATCH_SIZE=4

Verify Sample Dataset

Download Test Dataset

cd ~/ModelForge
curl -o test_dataset.jsonl https://raw.githubusercontent.com/RETR0-OS/ModelForge/main/ModelForge/test_datasets/low_text_generation.jsonl

Upload via UI

  1. Go to Training tab
  2. Click "Upload Dataset"
  3. Select test_dataset.jsonl
  4. Should see validation success

Or Upload via API

curl -X POST http://localhost:8000/api/upload_dataset \
  -F "file=@test_dataset.jsonl"

Common Post-Installation Tasks

Update ModelForge

pip install --upgrade modelforge-finetuning

Reset Database

rm -rf ~/.local/share/modelforge/database
modelforge run  # Will recreate database

Clear Cache

rm -rf ~/.cache/huggingface

View Logs

# Real-time logs
modelforge run --log-level debug

# Or check specific log file
cat ~/.local/share/modelforge/training_logs/latest.log

Security Considerations

API Key Protection

Never commit .env files with tokens to version control:

echo ".env" >> .gitignore

Firewall Configuration

If running on server, configure firewall:

Linux (UFW): 

sudo ufw allow 8000/tcp

Expose only to localhost: 

modelforge run --host 127.0.0.1

HTTPS Setup (Production)

Use reverse proxy (nginx/Apache) with SSL:

server {
    listen 443 ssl;
    server_name modelforge.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Next Steps

Installation Complete! You're ready to start fine-tuning models. 🚀