Skip to content

Installation

Jump to bottom
denys.kramar edited this page Sep 11, 2025 · 1 revision

Installation Guide

This guide covers all installation methods for Fira, from local development to production deployment.

Prerequisites

Before installing Fira, ensure you have:

  • Modern web browser (Chrome, Firefox, Safari, Edge)
  • Python 3.7+ (for server-based installations)
  • Git (for cloning the repository)
  • Docker (optional, for containerized deployment)

Option 1: Local Development

Perfect for testing, development, and single-user scenarios.

Quick Start

# Clone the repository
git clone https://github.com/your-org/fira.git
cd fira

# Navigate to web directory
cd web

# Start the server
./start.sh    # Linux/Mac
start.bat     # Windows

# Alternative: Manual Python server
python -m http.server 8080

Access the Application

Open your browser and navigate to:

http://localhost:8080

Features Available

  • Full task management functionality
  • File System Access API integration (Chrome/Edge)
  • Direct folder manipulation
  • No authentication required
  • Instant setup with no configuration

Option 2: Production Web Server

Recommended for team collaboration with authentication and Git integration.

Installation Steps

# Clone repository
git clone https://github.com/your-org/fira.git
cd fira/web

# Install Python dependencies
pip install -r requirements.txt

# Configure users (copy and edit)
cp users.json.example users.json

# Start production server
python mini-server.py

User Configuration

Edit web/users.json to configure team members:

{
  "users": [
    {
      "id": "1",
      "username": "admin",
      "password": "secure_password",
      "email": "admin@company.com",
      "role": "admin",
      "active": true,
      "git_name": "Admin User",
      "git_email": "admin@company.com"
    }
  ]
}

Environment Variables

Configure the server behavior:

export FIRA_PORT=8080
export FIRA_REQUIRE_LOGIN=true
export GIT_AUTHOR_NAME="Fira System"
export GIT_AUTHOR_EMAIL="system@fira"

Option 3: Fira Standalone (Local File System)

Alternative local version with Flask backend for enhanced file system operations.

Installation

# Navigate to Fira directory
cd fira/code

# Windows: Auto-install dependencies and start
start-server.bat

# Manual installation
pip install -r requirements.txt
python server.py  # Start Flask API (port 5000)

# In another terminal
python -m http.server 8080  # Start static server

Access

Troubleshooting

Common Issues

Port already in use:

# Check what's using the port
netstat -tulpn | grep :8080

# Kill the process
pkill -f "python.*http.server"

Permission denied on Unix systems:

chmod +x start.sh
./start.sh

Python dependencies missing:

pip install --upgrade pip
pip install flask flask-cors pyyaml

Browser compatibility issues:

  • Use Chrome or Edge for File System Access API
  • Firefox and Safari work with server-based file operations

System-Specific Notes

Windows:

  • Use start.bat for automatic setup
  • PowerShell may require execution policy changes
  • Windows Defender might flag Python servers

macOS:

  • Use ./start.sh for automatic setup
  • May need to allow Python through firewall
  • File system permissions may require approval

Linux:

  • Ensure Python 3.7+ is installed
  • May need to install python3-pip separately
  • Check firewall settings for port access

Verification

After installation, verify the setup:

  1. Web Interface: Navigate to http://localhost:8080
  2. Create Test Project: Use "Create Project" button
  3. Add Test Task: Create a task in the Backlog column
  4. Drag and Drop: Move task between columns
  5. Analytics: Check analytics view for data display

Next Steps

Support

If you encounter issues during installation:

  1. Check the troubleshooting section above
  2. Review system requirements
  3. Create an issue on GitHub with:
    • Operating system and version
    • Python version (python --version)
    • Error messages or logs
    • Steps to reproduce the issue

Clone this wiki locally