Skip to content

Configuration

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

Configuration Guide

This guide covers all configuration options for Fira, including user management, system settings, Git integration, and customization options.

System Configuration

Environment Variables

Configure Fira behavior using environment variables:

# Server Configuration
FIRA_PORT=8080                    # Server port (default: 8080)
FIRA_REQUIRE_LOGIN=true          # Enable authentication (default: false)
FIRA_SESSION_TIMEOUT=3600        # Session timeout in seconds
FIRA_MAX_FILE_SIZE=10MB          # Maximum file upload size

# Git Integration
GIT_AUTHOR_NAME="Fira System"    # Git commit author name
GIT_AUTHOR_EMAIL="system@fira"   # Git commit author email
GIT_AUTO_COMMIT=true             # Auto-commit task changes
GIT_AUTO_PUSH=false              # Auto-push to remote repository

# Security Settings
FIRA_RATE_LIMIT=100             # API requests per minute
FIRA_CORS_ORIGINS=*             # CORS allowed origins
FIRA_LOG_LEVEL=INFO             # Logging level (DEBUG, INFO, WARNING, ERROR)

# Optional Integrations
FIREBASE_PROJECT_ID=your-project # Firebase project ID
WEBHOOK_SECRET=your-secret       # Webhook verification secret

Configuration Files

Main configuration file (web/config.json):

{
  "server": {
    "port": 8080,
    "host": "0.0.0.0",
    "debug": false
  },
  "authentication": {
    "required": true,
    "session_timeout": 3600,
    "max_login_attempts": 5
  },
  "features": {
    "git_integration": true,
    "file_system_api": true,
    "analytics": true,
    "webhooks": false
  },
  "limits": {
    "max_projects": 100,
    "max_tasks_per_project": 1000,
    "max_file_size": "10MB"
  }
}

User Management

User Configuration

Configure users in web/users.json:

{
  "users": [
    {
      "id": "1",
      "username": "admin",
      "password": "secure_password_hash",
      "email": "admin@company.com",
      "role": "admin",
      "active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "last_login": "2024-01-15T10:30:00Z",
      "git_name": "Admin User",
      "git_email": "admin@company.com",
      "preferences": {
        "theme": "light",
        "timezone": "UTC",
        "notifications": true
      }
    },
    {
      "id": "2", 
      "username": "developer",
      "password": "hashed_password",
      "email": "dev@company.com",
      "role": "developer",
      "active": true,
      "git_name": "Developer User",
      "git_email": "dev@company.com"
    }
  ]
}

User Roles and Permissions

Admin Role:

  • Create and delete projects
  • Manage user accounts
  • Access system analytics
  • Configure system settings
  • Git repository access

Developer Role:

  • Create and edit tasks
  • Move tasks between columns
  • Add comments and time logs
  • Access assigned projects only

Viewer Role:

  • Read-only access to projects
  • View task details and analytics
  • Cannot modify tasks or projects

Password Management

Password Hashing:

import hashlib
import secrets

def hash_password(password):
    salt = secrets.token_hex(16)
    hash_obj = hashlib.pbkdf2_hmac('sha256', 
                                   password.encode('utf-8'), 
                                   salt.encode('utf-8'), 
                                   100000)
    return f"{salt}${hash_obj.hex()}"

Password Policy:

  • Minimum 8 characters
  • Must include uppercase, lowercase, number
  • Cannot be common passwords
  • Cannot be username or email

Project Configuration

Project Structure

Default project folder structure:

project-name/
├── backlog/              # New tasks
├── progress/             # Active development
│   ├── developer-1/      # Developer-specific folder
│   └── developer-2/
├── review/               # Code review
│   ├── developer-1/
│   └── developer-2/
├── testing/              # QA testing
│   ├── developer-1/
│   └── developer-2/
├── done/                 # Completed tasks
│   ├── developer-1/
│   └── developer-2/
└── README.md             # Project documentation

Project Metadata

Configure project settings in project-name/.fira/config.json:

{
  "name": "project-name",
  "description": "Project description",
  "created_at": "2024-01-01T00:00:00Z",
  "settings": {
    "workflow": {
      "columns": ["backlog", "progress", "review", "testing", "done"],
      "auto_assign": true,
      "require_estimates": true
    },
    "git": {
      "enabled": true,
      "auto_commit": true,
      "auto_push": false,
      "branch": "main"
    },
    "notifications": {
      "task_moved": true,
      "task_assigned": true,
      "deadline_warning": true
    }
  },
  "team": [
    {
      "username": "developer-1",
      "role": "developer",
      "capacity": 40
    }
  ]
}

Workflow Customization

Custom Workflow Columns:

{
  "workflow": {
    "columns": [
      {
        "id": "backlog",
        "name": "Backlog",
        "description": "New tasks",
        "color": "#e2e8f0"
      },
      {
        "id": "analysis",
        "name": "Analysis", 
        "description": "Requirements analysis",
        "color": "#fbbf24"
      },
      {
        "id": "development",
        "name": "Development",
        "description": "Active coding",
        "color": "#3b82f6"
      },
      {
        "id": "testing",
        "name": "Testing",
        "description": "Quality assurance", 
        "color": "#8b5cf6"
      },
      {
        "id": "done",
        "name": "Done",
        "description": "Completed tasks",
        "color": "#10b981"
      }
    ]
  }
}

Git Integration

SSH Configuration

Set up SSH keys for Git operations:

# Generate SSH key
ssh-keygen -t ed25519 -f ~/.ssh/fira_deploy_key

# Add to SSH agent
ssh-add ~/.ssh/fira_deploy_key

# Configure Git
git config --global user.name "Fira System"
git config --global user.email "system@company.com"

Git Hooks

Configure automatic Git operations in web/git_config.json:

{
  "enabled": true,
  "auto_commit": true,
  "auto_push": false,
  "commit_messages": {
    "task_created": "Add new task: {task_title}",
    "task_moved": "Move task {task_id} from {old_status} to {new_status}",
    "task_updated": "Update task: {task_title}",
    "task_deleted": "Delete task: {task_title}"
  },
  "ignore_patterns": [
    "*.tmp",
    "*.log",
    ".DS_Store"
  ]
}

Remote Repository

Configure remote Git repository:

# Add remote repository
cd /path/to/project
git remote add origin git@github.com:company/project-tasks.git

# Configure push settings
git config push.default simple
git config branch.main.remote origin
git config branch.main.merge refs/heads/main

Analytics and Reporting

Analytics Configuration

Configure analytics features in web/analytics_config.json:

{
  "enabled": true,
  "retention_days": 365,
  "metrics": {
    "task_velocity": true,
    "burndown_chart": true,
    "developer_performance": true,
    "time_tracking": true
  },
  "reports": {
    "daily_summary": true,
    "weekly_report": true,
    "monthly_dashboard": true
  },
  "export_formats": ["json", "csv", "pdf"]
}

Custom Metrics

Define custom project metrics:

{
  "custom_metrics": [
    {
      "name": "code_quality",
      "type": "percentage",
      "calculation": "review_passed / total_reviews * 100"
    },
    {
      "name": "bug_rate",
      "type": "ratio", 
      "calculation": "bugs_found / tasks_completed"
    }
  ]
}

Webhooks and Integrations

Webhook Configuration

Set up webhooks for external integrations:

{
  "webhooks": [
    {
      "name": "slack_notifications",
      "url": "https://hooks.slack.com/services/...",
      "events": ["task.created", "task.moved", "task.completed"],
      "headers": {
        "Authorization": "Bearer your-token"
      },
      "payload_template": {
        "text": "Task {task.title} moved to {task.status}",
        "channel": "#development"
      }
    },
    {
      "name": "jira_sync", 
      "url": "https://company.atlassian.net/rest/api/3/issue",
      "events": ["task.created", "task.updated"],
      "authentication": {
        "type": "basic",
        "username": "user@company.com",
        "token": "jira-api-token"
      }
    }
  ]
}

Third-party Integrations

Slack Integration:

{
  "slack": {
    "enabled": true,
    "webhook_url": "https://hooks.slack.com/services/...",
    "default_channel": "#development",
    "notifications": {
      "task_assigned": true,
      "task_completed": true,
      "deadline_approaching": true
    }
  }
}

Email Notifications:

{
  "email": {
    "enabled": true,
    "smtp_server": "smtp.company.com",
    "smtp_port": 587,
    "username": "fira@company.com",
    "password": "smtp-password",
    "from_address": "fira@company.com",
    "notifications": {
      "task_assigned": true,
      "daily_summary": true
    }
  }
}

Security Configuration

Authentication Settings

{
  "authentication": {
    "method": "local",
    "password_policy": {
      "min_length": 8,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_numbers": true,
      "require_special_chars": false
    },
    "session": {
      "timeout": 3600,
      "renewable": true,
      "secure_cookies": true
    },
    "rate_limiting": {
      "enabled": true,
      "max_attempts": 5,
      "lockout_duration": 300
    }
  }
}

CORS Configuration

{
  "cors": {
    "enabled": true,
    "allowed_origins": [
      "http://localhost:3000",
      "https://fira.company.com"
    ],
    "allowed_methods": ["GET", "POST", "PUT", "DELETE"],
    "allowed_headers": ["Content-Type", "Authorization"],
    "max_age": 3600
  }
}

Logging and Monitoring

Logging Configuration

Configure logging in web/logging_config.json:

{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "detailed": {
      "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
    },
    "simple": {
      "format": "%(levelname)s - %(message)s"
    }
  },
  "handlers": {
    "file": {
      "class": "logging.handlers.RotatingFileHandler",
      "filename": "logs/fira.log",
      "maxBytes": 10485760,
      "backupCount": 5,
      "formatter": "detailed"
    },
    "console": {
      "class": "logging.StreamHandler",
      "formatter": "simple"
    }
  },
  "loggers": {
    "fira": {
      "level": "INFO",
      "handlers": ["file", "console"]
    }
  }
}

Performance Monitoring

{
  "monitoring": {
    "enabled": true,
    "metrics_endpoint": "/metrics",
    "health_check_endpoint": "/health",
    "performance_tracking": {
      "api_response_times": true,
      "database_query_times": true,
      "file_operation_times": true
    }
  }
}

Customization

Theme Configuration

Customize the application appearance:

{
  "theme": {
    "name": "company-theme",
    "colors": {
      "primary": "#3b82f6",
      "secondary": "#8b5cf6", 
      "success": "#10b981",
      "warning": "#f59e0b",
      "error": "#ef4444",
      "background": "#f8fafc",
      "surface": "#ffffff",
      "text": "#1f2937"
    },
    "typography": {
      "font_family": "Inter, sans-serif",
      "heading_size": "1.25rem",
      "body_size": "0.875rem"
    }
  }
}

Custom Fields

Add custom fields to tasks:

{
  "custom_fields": [
    {
      "name": "priority",
      "type": "select",
      "options": ["low", "medium", "high", "critical"],
      "required": true
    },
    {
      "name": "story_points",
      "type": "number",
      "min": 1,
      "max": 13
    },
    {
      "name": "epic",
      "type": "text",
      "validation": "^EPIC-\\d+$"
    }
  ]
}

Backup and Restore

Backup Configuration

#!/bin/bash
# backup-fira.sh

BACKUP_DIR="/backup/fira-$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

# Backup users
cp web/users.json "$BACKUP_DIR/"

# Backup projects
tar -czf "$BACKUP_DIR/projects.tar.gz" web/projects/

# Backup configuration
cp -r web/*.json "$BACKUP_DIR/"

echo "Backup completed: $BACKUP_DIR"

Restore Procedure

#!/bin/bash
# restore-fira.sh

BACKUP_DIR="$1"

# Restore users
cp "$BACKUP_DIR/users.json" web/

# Restore projects  
tar -xzf "$BACKUP_DIR/projects.tar.gz" -C web/

# Restore configuration
cp "$BACKUP_DIR"/*.json web/

echo "Restore completed from: $BACKUP_DIR"

Troubleshooting Configuration

Common Configuration Issues

Invalid JSON format:

# Validate JSON files
python3 -m json.tool web/users.json
python3 -m json.tool web/config.json

Permission issues:

# Fix file permissions
chmod 644 web/users.json
chmod 644 web/config.json
chown -R www-data:www-data web/

Environment variable issues:

# Check environment variables
env | grep FIRA
printenv FIRA_PORT

Configuration Validation

Use the built-in configuration validator:

# Validate all configuration files
python3 web/validate_config.py

# Check specific configuration
python3 web/validate_config.py --users
python3 web/validate_config.py --projects

This comprehensive configuration guide covers all aspects of setting up and customizing Fira for your organization's needs.

Clone this wiki locally