Iskue overview

Iskue is a self-hosted, Jira-class issue-tracking platform. It covers tickets (epics, stories, tasks and bugs with sub-tickets, custom fields, labels and full change history), a per-project workflow engine, agile boards with sprints and backlog ordering, TQL search (project = CORE AND assignee = me AND status != Done), a service desk (knowledge base, CSAT, SLA policies), per-project automation rules, and a REST API with OpenAPI documentation at /swagger-ui.html. Authentication is JWT-based, with optional OIDC single sign-on (Google, Microsoft) and optional TOTP two-factor authentication.

This page describes the moving parts, the two supported deployment shapes, the system requirements, and where persistent data lives. Everything runs in Docker on a Linux host.

Moving parts

The backend schema is managed exclusively by Flyway migrations shipped in the backend image (backend/src/main/resources/db/migration). In the single-host shape the backend applies them automatically on boot; in the cluster shape a dedicated one-shot container applies them and the application boots with SPRING_FLYWAY_ENABLED: "false". Never apply schema changes by hand.

Deployment shapes

Three Compose files ship in the repository and do not interfere with each other: the root docker-compose.yml (development and single-host full stack), deploy/docker-compose.yml (self-contained distributed Citus cluster, dev/e2e) and deploy/docker-compose.prod.yml (the cluster's production variant, covered on the cluster install page).

Single host — http://localhost:8088

The root docker-compose.yml defines three services: postgres (container issuehub-postgres — PostgreSQL 16, published on host port 5432), backend (container issuehub-backend — built from ./backend, internal only) and frontend (container issuehub-frontend — built from ./frontend, published as 8088:80). The backend and frontend sit behind the full profile, so a bare docker compose up -d postgres starts only the database for local development. Only the frontend publishes an application port; the backend is reachable solely on the internal Docker network.

cp .env.example .env                      # set JWT_SECRET
docker compose --profile full up -d --build
# http://localhost:8088

Distributed Citus cluster — http://localhost:8090

deploy/docker-compose.yml runs Iskue on a Citus distributed Postgres cluster behind two clustered application servers and an nginx load balancer. It is self-contained and does not touch the root Compose file.

docker compose -f deploy/docker-compose.yml up -d --build

Bring-up order is enforced by depends_on conditions: the three Citus nodes become healthy, then citus-register, flyway and citus-distribute run to completion in sequence, then both backends start and pass their health checks, and finally the load balancer comes up on :8090. Sharding follows Scheme B: ticket is distributed by id; ticket-child tables (ticket_comment, ticket_label, ticket_change, ticket_watcher, attachment, git_link, csat_rating, ticket_sla and the other ticket-child tables) are distributed by ticket_id and colocated with ticket; every non-ticket table is a reference table replicated to every node.

docker compose -f deploy/docker-compose.yml down -v

System requirements

• A Linux host with Docker Engine and the Docker Compose v2 plugin (docker compose). All builds happen inside Docker: the backend image is a multi-stage Maven build on JDK 21, so no local Java, Maven or Node installation is required to deploy.
• Free host ports: 8088 and 5432 for the single-host shape; 8090 and 5432 for the cluster. The two shapes both claim 5432, so do not run them simultaneously on one host.
• Disk space for the Postgres data volume, the attachments volume and the built images; the first cluster build additionally downloads Maven dependencies and base images.

Where data lives

Key environment variables (single-host stack)

Copy .env.example to .env and adjust before docker compose --profile full up. The Compose file passes these through to the backend container; values shown are the defaults applied when a variable is unset.