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

docs: add Installation Guide and update README

This commit is contained in:
Ricel Leite 2026-02-18 21:44:59 -03:00
parent af710a7620
commit 927a906bbd
2 changed files with 355 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

318
INSTALL.md Normal file
View File

@ -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

87
README.md
View File

@ -2,46 +2,46 @@
Enterprise-grade open-source ticket and issue tracking system. Enterprise-grade open-source ticket and issue tracking system.
## Features ## 🚀 Features
### Work Management ### Work Management
- 📊 **Dashboard** - Overview with KPIs and recent activity - 📊 **Dashboard** — Overview with KPIs and recent activity
- 🎫 **Tickets** - Full CRUD with filters, search, and bulk actions - 🎫 **Tickets** — Full CRUD with filters, search, and bulk actions
- 📋 **Kanban Board** - Drag-and-drop ticket management - 📋 **Kanban Board** — Drag-and-drop ticket management
- 📁 **Projects** - Organize tickets by project with unique keys - 📁 **Projects** — Organize tickets by project with unique keys
### Team Collaboration ### Team Collaboration
- 👥 **Team Management** - Invite members with role-based access - 👥 **Team Management** — Invite members with role-based access
- 💬 **Comments** - Discussion threads on tickets - 💬 **Comments** — Discussion threads on tickets
- 🔔 **Notifications** - Email and Slack alerts - 🔔 **Notifications** — Email and Slack alerts
### Enterprise Features ### Enterprise Features
- 📈 **Reports & Analytics** - Performance metrics and insights - 📈 **Reports & Analytics** — Performance metrics and insights
- 🔌 **Integrations** - GitHub, GitLab, Jira, ServiceNow, Slack - 🔌 **Integrations** — GitHub, GitLab, Jira, ServiceNow, Slack
- ⚡ **Automation** - Rules engine for repetitive tasks - ⚡ **Automation** — Rules engine for repetitive tasks
- 🔐 **Security** - SSO, 2FA, IP restrictions - 🔐 **Security** — SSO, 2FA, IP restrictions
### API & Webhooks ### API & Webhooks
- RESTful API with full documentation - RESTful API with auto-generated documentation (Swagger UI)
- Incoming/outgoing webhooks - Incoming webhooks (create tickets from external systems)
- API key management - Outgoing webhooks (notify external systems on events)
- Project-level webhook configuration
## Tech Stack ## 📦 Tech Stack
### Backend | Layer | Technology |
- Python 3.11 + FastAPI |-------|-----------|
- SQLite (development) / PostgreSQL (production) | **Frontend** | React 18, TypeScript, Vite, TailwindCSS |
- Async/await architecture | **Backend** | Python 3.11, FastAPI, SQLAlchemy |
| **Database** | SQLite (dev) / PostgreSQL (prod) |
### Frontend ## 🛠 Quick Start
- React 18 + TypeScript
- TailwindCSS
- React Query
- React Router
## Quick Start
```bash ```bash
# Clone
git clone https://gitea.startdata.com.br/startdata/tickethub.git
cd tickethub
# Backend # Backend
cd backend cd backend
pip install -r requirements.txt pip install -r requirements.txt
@ -53,31 +53,18 @@ npm install
npm run dev npm run dev
``` ```
## API Endpoints ## 📖 Documentation
``` - **[Installation Guide](INSTALL.md)** — Full setup instructions (Docker, Swarm, local dev)
GET /api/projects - **[Architecture](docs/ARCHITECTURE.md)** — System design and data flow
POST /api/projects - **[Developer Guide](docs/DEVELOPER_GUIDE.md)** — Contributing and extending
GET /api/projects/:id - **[User Guide](docs/USER_GUIDE.md)** — End-user documentation
PATCH /api/projects/:id - **[API Docs](https://tickethub.startdata.com.br/docs)** — Swagger UI
DELETE /api/projects/:id
GET /api/tickets ## 🌐 Live Demo
POST /api/tickets
GET /api/tickets/:id
PATCH /api/tickets/:id
DELETE /api/tickets/:id
GET /api/tickets/:id/comments https://tickethub.startdata.com.br
POST /api/tickets/:id/comments
POST /api/webhooks/incoming ## 📄 License
```
## License MIT © StartData
MIT
## Credits
Created by StartData