296 lines
7.6 KiB
Markdown
296 lines
7.6 KiB
Markdown
# JIRA AI Fixer v2.0 - Installation Guide
|
|
|
|
## Overview
|
|
|
|
JIRA AI Fixer is an enterprise AI-powered platform that automatically analyzes issues from JIRA, ServiceNow, GitHub, GitLab and other platforms, generates root cause analysis, and creates Pull Requests with fixes.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌────────────┐
|
|
│ Frontend │────▶│ Backend │────▶│ PostgreSQL │
|
|
│ (Nginx) │ │ (FastAPI) │ │ │
|
|
│ React SPA │ │ Python 3.11 │ └────────────┘
|
|
└─────────────┘ └──────┬───────┘
|
|
│
|
|
┌──────▼───────┐
|
|
│ Redis │
|
|
│ (Queue) │
|
|
└──────────────┘
|
|
```
|
|
|
|
### Tech Stack
|
|
|
|
**Backend:**
|
|
- Python 3.11 + FastAPI
|
|
- PostgreSQL (async via SQLAlchemy + asyncpg)
|
|
- Redis (job queue)
|
|
- JWT Authentication
|
|
- Resend (email notifications)
|
|
|
|
**Frontend:**
|
|
- React 18 + Vite
|
|
- TailwindCSS + shadcn/ui components
|
|
- React Query (data fetching)
|
|
- Recharts (analytics)
|
|
- React Router (SPA routing)
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Docker & Docker Compose (or Docker Swarm)
|
|
- PostgreSQL 14+ (or use existing instance)
|
|
- Redis (or use existing instance)
|
|
- A domain with SSL (recommended)
|
|
|
|
---
|
|
|
|
## Quick Start (Docker Compose)
|
|
|
|
### 1. Clone the repository
|
|
|
|
```bash
|
|
git clone https://gitea.startdata.com.br/startdata/jira-ai-fixer.git
|
|
cd jira-ai-fixer
|
|
```
|
|
|
|
### 2. Configure environment
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your settings:
|
|
|
|
```env
|
|
# Database
|
|
DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/jira_fixer
|
|
|
|
# Redis
|
|
REDIS_URL=redis://redis:6379/0
|
|
|
|
# Security (generate with: openssl rand -hex 32)
|
|
SECRET_KEY=your-secret-key-here
|
|
JWT_SECRET=your-jwt-secret-here
|
|
|
|
# Email (optional - Resend.com)
|
|
RESEND_API_KEY=re_xxxxx
|
|
EMAIL_FROM=JIRA AI Fixer <noreply@yourdomain.com>
|
|
|
|
# AI Analysis (optional - OpenRouter.ai)
|
|
OPENROUTER_API_KEY=sk-or-xxxxx
|
|
|
|
# Git Integration (optional - Gitea/GitHub)
|
|
GITEA_URL=https://gitea.yourdomain.com
|
|
GITEA_TOKEN=your-token
|
|
|
|
# OAuth Integrations (optional)
|
|
JIRA_CLIENT_ID=
|
|
JIRA_CLIENT_SECRET=
|
|
GITHUB_CLIENT_ID=
|
|
GITHUB_CLIENT_SECRET=
|
|
```
|
|
|
|
### 3. Start with Docker Compose
|
|
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
|
|
### 4. Access the application
|
|
|
|
- **Frontend:** http://localhost (or your domain)
|
|
- **API Docs:** http://localhost/api/docs
|
|
- **Health Check:** http://localhost/api/health
|
|
|
|
---
|
|
|
|
## Production Deployment (Docker Swarm + Traefik)
|
|
|
|
### 1. Create the stack file
|
|
|
|
```yaml
|
|
version: '3.8'
|
|
|
|
services:
|
|
api:
|
|
image: python:3.11-slim
|
|
command: >
|
|
bash -c "
|
|
apt-get update && apt-get install -y curl &&
|
|
pip install fastapi uvicorn[standard] sqlalchemy[asyncio] asyncpg
|
|
pydantic[email] pydantic-settings python-jose[cryptography]
|
|
passlib[bcrypt] httpx python-multipart email-validator &&
|
|
mkdir -p /app && cd /app &&
|
|
curl -sL 'https://gitea.yourdomain.com/org/jira-ai-fixer/archive/master.tar.gz' |
|
|
tar xz --strip-components=1 &&
|
|
uvicorn app.main:app --host 0.0.0.0 --port 8000
|
|
"
|
|
environment:
|
|
- DATABASE_URL=postgresql+asyncpg://user:pass@db_host:5432/jira_fixer
|
|
- REDIS_URL=redis://redis_host:6379
|
|
- JWT_SECRET=your-jwt-secret
|
|
- RESEND_API_KEY=re_xxxxx
|
|
- APP_URL=https://jira-fixer.yourdomain.com
|
|
networks:
|
|
- internal
|
|
- db_network
|
|
deploy:
|
|
replicas: 1
|
|
restart_policy:
|
|
condition: on-failure
|
|
delay: 25s
|
|
|
|
frontend:
|
|
image: nginx:alpine
|
|
command: >
|
|
sh -c "apk add --no-cache curl &&
|
|
mkdir -p /app && cd /app &&
|
|
curl -sL 'https://gitea.yourdomain.com/org/jira-ai-fixer/archive/master.tar.gz' |
|
|
tar xz --strip-components=1 &&
|
|
cp -r frontend_build/* /usr/share/nginx/html/ &&
|
|
echo 'c2VydmVyIHsKICBsaXN0ZW4gODA7...' | base64 -d > /etc/nginx/conf.d/default.conf &&
|
|
nginx -g 'daemon off;'"
|
|
networks:
|
|
- proxy_network
|
|
- internal
|
|
deploy:
|
|
labels:
|
|
- traefik.enable=true
|
|
- traefik.http.routers.jira-fixer.rule=Host(`jira-fixer.yourdomain.com`)
|
|
- traefik.http.routers.jira-fixer.entrypoints=websecure
|
|
- traefik.http.routers.jira-fixer.tls.certresolver=le
|
|
- traefik.http.services.jira-fixer.loadbalancer.server.port=80
|
|
|
|
networks:
|
|
proxy_network:
|
|
external: true
|
|
db_network:
|
|
external: true
|
|
internal:
|
|
driver: overlay
|
|
```
|
|
|
|
### 2. Nginx Config (base64 encoded in command)
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
root /usr/share/nginx/html;
|
|
index index.html;
|
|
location / {
|
|
try_files $uri $uri/ /index.html;
|
|
}
|
|
location /api {
|
|
proxy_pass http://api:8000;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. Deploy
|
|
|
|
```bash
|
|
docker stack deploy -c docker-compose.yml jira-fixer
|
|
```
|
|
|
|
---
|
|
|
|
## Local Development
|
|
|
|
### Backend
|
|
|
|
```bash
|
|
cd app
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt # or install manually (see stack command)
|
|
uvicorn app.main:app --reload --port 8000
|
|
```
|
|
|
|
### Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
Frontend dev server runs on http://localhost:5173 with proxy to backend.
|
|
|
|
### Build Frontend
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run build
|
|
cp -r dist/* ../frontend_build/
|
|
```
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/auth/register` | Register new user |
|
|
| POST | `/api/auth/login` | Login |
|
|
| GET | `/api/organizations` | List organizations |
|
|
| POST | `/api/organizations` | Create organization |
|
|
| GET | `/api/issues` | List issues |
|
|
| POST | `/api/issues` | Create issue |
|
|
| GET | `/api/issues/:id` | Get issue detail |
|
|
| PATCH | `/api/issues/:id` | Update issue |
|
|
| POST | `/api/webhooks/jira` | JIRA webhook |
|
|
| POST | `/api/webhooks/servicenow` | ServiceNow webhook |
|
|
| POST | `/api/webhooks/github` | GitHub webhook |
|
|
| GET | `/api/reports/summary` | Report summary |
|
|
| GET | `/api/health` | Health check |
|
|
|
|
Full API documentation available at `/api/docs` (Swagger UI).
|
|
|
|
---
|
|
|
|
## Integrations
|
|
|
|
### JIRA Cloud
|
|
1. Go to Settings > Integrations > JIRA
|
|
2. Enter your Atlassian domain, email, and API token
|
|
3. Configure webhook in JIRA to point to `https://your-domain/api/webhooks/jira`
|
|
|
|
### GitHub
|
|
1. Create a GitHub App or use personal access token
|
|
2. Configure in Settings > Integrations > GitHub
|
|
3. Set webhook URL: `https://your-domain/api/webhooks/github`
|
|
|
|
### ServiceNow
|
|
1. Configure REST integration in ServiceNow
|
|
2. Point to: `https://your-domain/api/webhooks/servicenow`
|
|
|
|
---
|
|
|
|
## Environment Variables Reference
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| `DATABASE_URL` | Yes | - | PostgreSQL connection string |
|
|
| `REDIS_URL` | No | `redis://localhost:6379` | Redis connection string |
|
|
| `SECRET_KEY` | Yes | - | App secret key |
|
|
| `JWT_SECRET` | Yes | - | JWT signing key |
|
|
| `JWT_EXPIRE_MINUTES` | No | `1440` | Token expiry (24h) |
|
|
| `RESEND_API_KEY` | No | - | Email service API key |
|
|
| `OPENROUTER_API_KEY` | No | - | AI analysis API key |
|
|
| `GITEA_URL` | No | - | Git server URL |
|
|
| `GITEA_TOKEN` | No | - | Git server access token |
|
|
| `JIRA_CLIENT_ID` | No | - | JIRA OAuth client ID |
|
|
| `JIRA_CLIENT_SECRET` | No | - | JIRA OAuth client secret |
|
|
| `GITHUB_CLIENT_ID` | No | - | GitHub OAuth client ID |
|
|
| `GITHUB_CLIENT_SECRET` | No | - | GitHub OAuth client secret |
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT © StartData
|