Desktop Application

The desktop application is a native Java 21 / JavaFX 21 client targeting cinema operators and administrators. It bundles the full Rakcha feature set — cinema management, film and series catalogs, an e-commerce module, and user administration — into a single distributable that runs on Windows, macOS, and Linux.

Prerequisites

Java JDK 21 or later
Maven 3.6+
A supported database: MySQL 8.0+, PostgreSQL, SQLite (no setup needed for development), or H2
An IDE with JavaFX support (IntelliJ IDEA, Eclipse, or VS Code) — optional for running via Maven

Installation and running locally

Configure environment variables

Copy the example environment file and fill in your credentials:

cd apps/desktop
cp .env.example .env

Key variables:

# Database — SQLite requires no user/password
DB_URL=jdbc:sqlite:./data/rakcha.db
DB_USER=
DB_PASSWORD=

# OAuth (optional)
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
MICROSOFT_CLIENT_ID=your_microsoft_client_id
MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret

# Payments (optional)
STRIPE_API_KEY=your_stripe_key
PAYPAL_CLIENT_ID=your_paypal_client_id
PAYPAL_CLIENT_SECRET=your_paypal_secret

# Media
CLOUDINARY_URL=cloudinary://api_key:api_secret@cloud_name
YOUTUBE_API_KEY=your_youtube_api_key

Build the project

mvn clean install -DskipTests

Run the application

mvn javafx:run

SQLite is the easiest way to get started locally — no database server required. The database file is created automatically at ./data/rakcha.db on first launch.

Building a distributable

The Maven build produces native installers via jpackage for each platform:

mvn clean install

Installers are output to target/:

Platform	Format
Windows	`.msi` installer
macOS	`.pkg` installer
Linux	`.deb` package + portable archive

Installers are also built automatically by the build-and-deploy.yml GitHub Actions workflow when a release tag is pushed.

Running tests

mvn test

For CI environments (headless mode):

mvn test -Dtestfx.robot=glass -Dtestfx.headless=true

Generate a JaCoCo coverage report alongside tests:

mvn test jacoco:report

Tests are written with JUnit Jupiter and TestFX, with AssertJ for assertions.

Key functional areas

Controllers live under src/main/java/com/esprit/controllers/ and are organized by domain:

Module	Controllers	Description
`cinemas/`	11 controllers	Cinema venues, halls, seating, and movie session scheduling
`films/`	8 controllers	Film catalog, actor management, ticket booking, IMDB import, trailers
`series/`	9 controllers	TV series catalog, seasons, episodes, favorites, and watch progress
`products/`	12 controllers	Product catalog, shopping cart, checkout, order tracking, QR codes
`users/`	21 controllers	Role-based access (Client, Admin, Cinema Manager), profiles, messaging, achievements

Additional shared components:

SidebarController.java — navigation sidebar
SplashScreenController.java — startup screen
UniversalSearchBox.java — role-aware search with Caffeine caching

Docker deployment

A docker-compose.yml and Dockerfile are included in apps/desktop.

Development
Production

Starts the application with the Adminer database UI on port 8081:

docker-compose --profile dev up -d

docker-compose up -d

Service overview:

Service	Port	Description
`rakcha-app`	8080	Main application
`rakcha-db`	3306	MySQL database
`rakcha-redis`	6379	Redis cache
`adminer`	8081	Database admin UI (dev profile only)

View logs or stop services:

# Follow application logs
docker-compose logs -f rakcha-app

# Stop all services
docker-compose down

Multi-database support

The DataSource.java utility supports four databases via HikariCP connection pooling. Switch by updating DB_URL in your .env file:

SQLite (development)
MySQL
PostgreSQL
H2

No server required. The database file is created on first run.

DB_URL=jdbc:sqlite:./data/rakcha.db
DB_USER=
DB_PASSWORD=

DB_URL=jdbc:mysql://localhost:3306/rakcha_db?serverTimezone=UTC
DB_USER=rakcha_user
DB_PASSWORD=your_password

DB_URL=jdbc:postgresql://localhost:5432/rakcha_db
DB_USER=rakcha_user
DB_PASSWORD=your_password

H2 operates in embedded mode — suitable for testing and CI pipelines where no external database is available.

DB_URL=jdbc:h2:./data/rakcha
DB_USER=sa
DB_PASSWORD=

Technology stack

Layer	Technology
Language	Java 21
UI framework	JavaFX 21.0.7
Build tool	Maven 3.6+
UI extensions	ControlsFX 11.2.2, JFoenix 9.0.10
Icons	Ikonli 12.4.0 (Material Design 2)
Animations	AnimateFX 1.3.0
Databases	MySQL 9.3, PostgreSQL 42.7, SQLite 3.50, H2
Connection pool	HikariCP 5.1.0
Auth (OAuth)	ScribeJava 8.3.3 (Google, Microsoft)
Biometric auth	OpenCV 4.9+ (face recognition)
Payments	Stripe Java 29.4.0, PayPal REST SDK 1.14.0
Search / cache	Apache Lucene 9.12.1, Caffeine 3.1.8
PDF	iText 5.5.13.4, PDFBox 3.0.5
QR / barcodes	ZXing 3.5.3
SMS	Twilio 11.0.0, Vonage 9.3.1
Testing	JUnit Jupiter, TestFX 4.0.18, AssertJ 3.27.3

Get Started

Core Features

Platform Guides

Configuration & Deployment

Desktop Application

Prerequisites

Installation and running locally

Building a distributable

Running tests

Key functional areas

Docker deployment

Multi-database support

Technology stack

Build docs developers (and LLMs) love

Get Started

Core Features

Platform Guides

Configuration & Deployment

​Prerequisites

​Installation and running locally

​Building a distributable

​Running tests

​Key functional areas

​Docker deployment

​Multi-database support

​Technology stack

Build docs developers (and LLMs) love

Prerequisites

Installation and running locally

Building a distributable

Running tests

Key functional areas

Docker deployment

Multi-database support

Technology stack