startdata
/
tickethub
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
tickethub/INSTALL.md

7.4 KiB
Raw Blame History

TicketHub - Installation Guide

Overview

TicketHub is a lightweight, enterprise-grade open-source ticket and issue tracking system. It provides project management, Kanban boards, team collaboration, and integrations with popular platforms.

Architecture

┌─────────────────┐     ┌──────────────┐     ┌────────────┐
│    Frontend      │────▶│   Backend    │────▶│  SQLite /   │
│  React + Vite    │     │  (FastAPI)   │     │ PostgreSQL  │
│  (or static)     │     │  Python 3.11 │     └────────────┘
└─────────────────┘     └──────────────┘

Tech Stack

Backend:

  • Python 3.11 + FastAPI
  • SQLite (development) / PostgreSQL (production)
  • Async architecture (aiosqlite)
  • RESTful API with auto-generated docs

Frontend (React - recommended):

  • React 18 + TypeScript + Vite
  • TailwindCSS
  • React Query (data fetching)
  • React Router (SPA routing)

Frontend (Static - legacy):

  • Vanilla HTML/JS + Tailwind CDN
  • Zero build step required
  • Located in frontend/static/

Prerequisites

  • Python 3.11+
  • Node.js 18+ (for React frontend)
  • Docker (for containerized deployment)

Quick Start (Local Development)

1. Clone the repository

git clone https://gitea.startdata.com.br/startdata/tickethub.git
cd tickethub

2. Start the backend

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

The API is now available at http://localhost:8000

3. Start the frontend (React)

cd frontend
npm install
npm run dev

Frontend dev server runs at http://localhost:5173

4. Access

Production Deployment (Docker Swarm + Traefik)

1. Stack file

version: "3.8"

services:
  tickethub:
    image: python:3.11-slim
    working_dir: /app
    command: >
      bash -c "
        apt-get update && apt-get install -y git --no-install-recommends &&
        git clone https://gitea.yourdomain.com/org/tickethub.git /app/repo &&
        cd /app/repo/backend &&
        pip install --no-cache-dir -r requirements.txt &&
        mkdir -p /data &&
        DATABASE_PATH=/data/tickethub.db uvicorn app.main:app --host 0.0.0.0 --port 8000
      "      
    environment:
      - DATABASE_PATH=/data/tickethub.db
    volumes:
      - tickethub_data:/data
    networks:
      - traefik_public
    deploy:
      labels:
        - traefik.enable=true
        - traefik.http.routers.tickethub.rule=Host(`tickethub.yourdomain.com`)
        - traefik.http.routers.tickethub.entrypoints=websecure
        - traefik.http.routers.tickethub.tls.certresolver=le
        - traefik.http.services.tickethub.loadbalancer.server.port=8000

volumes:
  tickethub_data:

networks:
  traefik_public:
    external: true

2. Deploy

docker stack deploy -c docker-compose.yml tickethub

Docker Compose (Simple)

version: "3.8"

services:
  tickethub:
    build: ./backend
    ports:
      - "8080:8000"
    volumes:
      - tickethub_data:/data
      - ./frontend/static:/app/static:ro
    environment:
      - DATABASE_PATH=/data/tickethub.db
    restart: unless-stopped

volumes:
  tickethub_data:

docker compose up -d

API Endpoints

Projects

Method Endpoint Description
GET /api/projects List all projects
POST /api/projects Create project
GET /api/projects/:id Get project details
PATCH /api/projects/:id Update project
DELETE /api/projects/:id Delete project

Tickets

Method Endpoint Description
GET /api/tickets List tickets (filter by project_id, status)
POST /api/tickets Create ticket
GET /api/tickets/:id Get ticket details
PATCH /api/tickets/:id Update ticket
DELETE /api/tickets/:id Delete ticket
GET /api/tickets/:id/comments List comments
POST /api/tickets/:id/comments Add comment

Webhooks

Method Endpoint Description
POST /api/webhooks/incoming Receive external webhook

Health

Method Endpoint Description
GET /api/health Health check

Full API documentation available at /docs (Swagger UI).

Configuration

Environment Variables

Variable Required Default Description
DATABASE_PATH No ./tickethub.db SQLite database file path
DATABASE_URL No - PostgreSQL URL (overrides SQLite)

Project Configuration

Each project supports:

  • Name — Display name
  • Key — Unique 2-10 character uppercase key (e.g., PROJ)
  • Webhook URL — External webhook for ticket events

Ticket Fields

Field Type Values
title string Required
description string Required
status enum open, in_progress, resolved, closed
priority enum low, medium, high, critical
project_id integer Required

Frontend Pages (React)

Page Route Description
Dashboard / KPIs, recent activity, overview
Tickets /tickets List with filters, search, bulk actions
New Ticket /tickets/new Create ticket form
Ticket Detail /tickets/:id Full detail view with comments
Kanban Board /board Drag-and-drop board
Projects /projects Project management
Team /team Team members
Reports /reports Analytics and metrics
Integrations /integrations External service connections
Automation /automation Rules engine
Settings /settings System configuration

Building for Production

Frontend Build

cd frontend
npm install
npm run build
# Output in frontend/dist/

Backend Dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY backend/ .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

Webhooks

Incoming Webhooks

TicketHub can receive webhooks from external systems to automatically create tickets:

curl -X POST https://tickethub.yourdomain.com/api/webhooks/incoming \
  -H "Content-Type: application/json" \
  -d '{
    "project_key": "PROJ",
    "title": "Server Down",
    "description": "Production server is unreachable",
    "priority": "critical",
    "source": "monitoring"
  }'

Outgoing Webhooks

Configure a webhook URL per project. TicketHub will POST events when tickets are created or updated:

{
  "event": "ticket.created",
  "ticket": {
    "id": 1,
    "key": "PROJ-1",
    "title": "Server Down",
    "status": "open",
    "priority": "critical"
  }
}

Documentation

Additional documentation in the docs/ folder:

License

MIT © StartData