From 927a906bbd25ac382081658dc6b27d2568873eed Mon Sep 17 00:00:00 2001 From: Ricel Leite Date: Wed, 18 Feb 2026 21:44:59 -0300 Subject: [PATCH] docs: add Installation Guide and update README --- INSTALL.md | 318 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 87 +++++++-------- 2 files changed, 355 insertions(+), 50 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..a630032 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,318 @@ +# 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 diff --git a/README.md b/README.md index 55c4453..cefd046 100644 --- a/README.md +++ b/README.md @@ -2,46 +2,46 @@ Enterprise-grade open-source ticket and issue tracking system. -## Features +## 🚀 Features ### Work Management -- 📊 **Dashboard** - Overview with KPIs and recent activity -- 🎫 **Tickets** - Full CRUD with filters, search, and bulk actions -- 📋 **Kanban Board** - Drag-and-drop ticket management -- 📁 **Projects** - Organize tickets by project with unique keys +- 📊 **Dashboard** — Overview with KPIs and recent activity +- 🎫 **Tickets** — Full CRUD with filters, search, and bulk actions +- 📋 **Kanban Board** — Drag-and-drop ticket management +- 📁 **Projects** — Organize tickets by project with unique keys ### Team Collaboration -- 👥 **Team Management** - Invite members with role-based access -- 💬 **Comments** - Discussion threads on tickets -- 🔔 **Notifications** - Email and Slack alerts +- 👥 **Team Management** — Invite members with role-based access +- 💬 **Comments** — Discussion threads on tickets +- 🔔 **Notifications** — Email and Slack alerts ### Enterprise Features -- 📈 **Reports & Analytics** - Performance metrics and insights -- 🔌 **Integrations** - GitHub, GitLab, Jira, ServiceNow, Slack -- ⚡ **Automation** - Rules engine for repetitive tasks -- 🔐 **Security** - SSO, 2FA, IP restrictions +- 📈 **Reports & Analytics** — Performance metrics and insights +- 🔌 **Integrations** — GitHub, GitLab, Jira, ServiceNow, Slack +- ⚡ **Automation** — Rules engine for repetitive tasks +- 🔐 **Security** — SSO, 2FA, IP restrictions ### API & Webhooks -- RESTful API with full documentation -- Incoming/outgoing webhooks -- API key management +- RESTful API with auto-generated documentation (Swagger UI) +- Incoming webhooks (create tickets from external systems) +- Outgoing webhooks (notify external systems on events) +- Project-level webhook configuration -## Tech Stack +## 📦 Tech Stack -### Backend -- Python 3.11 + FastAPI -- SQLite (development) / PostgreSQL (production) -- Async/await architecture +| Layer | Technology | +|-------|-----------| +| **Frontend** | React 18, TypeScript, Vite, TailwindCSS | +| **Backend** | Python 3.11, FastAPI, SQLAlchemy | +| **Database** | SQLite (dev) / PostgreSQL (prod) | -### Frontend -- React 18 + TypeScript -- TailwindCSS -- React Query -- React Router - -## Quick Start +## 🛠 Quick Start ```bash +# Clone +git clone https://gitea.startdata.com.br/startdata/tickethub.git +cd tickethub + # Backend cd backend pip install -r requirements.txt @@ -53,31 +53,18 @@ npm install npm run dev ``` -## API Endpoints +## 📖 Documentation -``` -GET /api/projects -POST /api/projects -GET /api/projects/:id -PATCH /api/projects/:id -DELETE /api/projects/:id +- **[Installation Guide](INSTALL.md)** — Full setup instructions (Docker, Swarm, local dev) +- **[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 +- **[API Docs](https://tickethub.startdata.com.br/docs)** — Swagger UI -GET /api/tickets -POST /api/tickets -GET /api/tickets/:id -PATCH /api/tickets/:id -DELETE /api/tickets/:id +## 🌐 Live Demo -GET /api/tickets/:id/comments -POST /api/tickets/:id/comments +https://tickethub.startdata.com.br -POST /api/webhooks/incoming -``` +## 📄 License -## License - -MIT - -## Credits - -Created by StartData +MIT © StartData