tickethub/INSTALL.md

# 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

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

### 2. Start the backend

```bash
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)

```bash
cd frontend
npm install
npm run dev
```

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

### 4. Access

- **App:** http://localhost:5173
- **API Docs:** http://localhost:8000/docs
- **Health:** http://localhost:8000/api/health

---

## Production Deployment (Docker Swarm + Traefik)

### 1. Stack file

```yaml
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

```bash
docker stack deploy -c docker-compose.yml tickethub
```

---

## Docker Compose (Simple)

```yaml
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:
```

```bash
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

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

### Backend Dockerfile

```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:

```bash
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:

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

---

## Documentation

Additional documentation in the `docs/` folder:

- **[Architecture](docs/ARCHITECTURE.md)** — System design and data flow
- **[Developer Guide](docs/DEVELOPER_GUIDE.md)** — Contributing and extending
- **[User Guide](docs/USER_GUIDE.md)** — End-user documentation

---

## License

MIT © StartData