HeroForge UI

A web-based Git repository management UI built with Rust, designed as a Gitea/GitHub replacement. Uses the heroforge crate for the data layer.

Features

• Repository Management: View and manage Git repositories with issues, pull requests, projects, and wiki
• Multiple CSS Framework Versions: DaisyUI, Tailwind CSS, and Bootstrap themes
• TOML-based Configuration: All configuration stored in .data/config.toml
• File-based Data Storage: Issues, projects, and pull requests stored as TOML files

Prerequisites

• Rust (1.70+)
• A .forge or .heroforge repository file

Repository Setup

IMPORTANT: This application requires .forge or .heroforge repository files to function. These are special repository files created by the heroforge system.

Repository Path Configuration

The application looks for repositories using the REPO_PATH environment variable or the path configured in .data/config.toml.

Supported path formats:

Format	Description
/path/to/repo.forge	Direct path to a specific .forge repository
/path/to/repo.heroforge	Direct path to a specific .heroforge repository
/path/to/dir	Directory containing .forge or .heroforge files
/path/to/*.forge	Glob pattern to find repositories

Example Repository Configuration

In .data/config.toml:

[[repos]]
name = "myproject"
# Path to your .forge or .heroforge repository file
path = "/path/to/myproject.forge"
org = "myorg"

Project Structure

heroforge_ui/
├── .data/
│   ├── config.toml          # Main configuration (repos, users, groups, labels, milestones)
│   ├── issues/              # Issue data files (1.toml, 2.toml, etc.)
│   ├── projects/            # Project data files
│   └── pull_requests/       # Pull request data files
├── src/
│   ├── main.rs              # Application entry point
│   ├── config.rs            # Configuration handling
│   ├── heroforge/           # Heroforge integration
│   │   ├── repository.rs    # Repository operations
│   │   └── store.rs         # Data store for issues, PRs, projects
│   ├── api/                 # REST API endpoints
│   ├── models/              # Data models
│   └── views/               # View templates
├── templates/               # HTML templates (Askama)
├── run.sh                   # Run script
└── README.md

Configuration

Main Configuration (.data/config.toml)

The main configuration file contains:

• Repositories: Git repositories to manage
• Organizations: Groups of repositories
• Users: User accounts
• Groups: User groups for access control
• Labels: Issue/PR labels (global, not editable via UI)
• Milestones: Project milestones (global, not editable via UI)

# Repository configuration
[[repos]]
name = "myproject"
path = "/path/to/myproject.forge"
org = "myorg"

# Labels (read from config, not editable)
[[labels]]
name = "bug"
color = "#d73a4a"
description = "Something isn't working"

# Milestones (read from config, not editable)
[[milestones]]
name = "v1.0"
description = "First release"
due_date = "2025-01-01"

Data Files

Issues, projects, and pull requests are stored as individual TOML files in .data/:

Example Issue (.data/issues/1.toml):

id = 1
title = "Fix login bug"
description = "Users cannot log in with special characters"
state = "Open"
author = "admin@example.com"
labels = ["bug", "prio_high"]
milestone = "now"

Installation

# Clone the repository
git clone https://forge.ourworld.tf/lhumina_research/heroforge_ui.git
cd heroforge_ui

# Build the project
cargo build --release

Running the Application

./run.sh

Or manually:

export CONFIG_PATH=".data/config.toml"
export REPO_PATH="/path/to/your/repo.forge"
cargo run --release

The server starts on http://127.0.0.1:8654 with these routes:

Route	Description
/	DaisyUI version (default)
/tailwind	Tailwind CSS version
/bootstrap	Bootstrap version
/api/issues	Issues API
/api/pulls	Pull Requests API
/api/projects	Projects API

API Endpoints

Issues

• GET /api/issues - List all issues
• GET /api/issues/{id} - Get issue by ID
• POST /api/issues - Create new issue
• PUT /api/issues/{id} - Update issue
• DELETE /api/issues/{id} - Delete issue

Pull Requests

• GET /api/pulls - List all pull requests
• GET /api/pulls/{id} - Get PR by ID
• POST /api/pulls - Create new PR
• PUT /api/pulls/{id} - Update PR

Projects

• GET /api/projects - List all projects
• GET /api/projects/{id} - Get project by ID
• POST /api/projects - Create new project

Troubleshooting

"No .forge or .heroforge repositories found"

This error means the application cannot find any repository files. Check:

1. The path in .data/config.toml points to a valid .forge or .heroforge file
2. The REPO_PATH environment variable is set correctly
3. The repository file exists and is readable

Port Already in Use

The default port is 8654. If it's in use, the run script will attempt to kill the existing process. You can also modify the port in the source code.

Dependencies

• heroforge - Repository data layer
• actix-web - Web framework
• askama - Template engine
• serde - Serialization
• toml - Configuration parsing

License

This project is provided as-is for educational and demonstration purposes.

---

Version: 1.0.0
Status: Development