platform-java Quick Start Guide

Get up and running with platform-java in 5 minutes!

Prerequisites

Java 11 or later
Maven 3.6+

Build platform-java

# Clone the repository
git clone https://github.com/FlossWare/platform-java.git
cd platform-java

# Build all modules (takes ~2 minutes)
mvn clean install

# Launcher JAR will be at:
# platform-java-launcher/target/platform-java-launcher-1.0.jar

Quick Start: Interactive Mode

The simplest way to get started is with the interactive console:

cd platform-java-launcher/target
java -jar platform-java-launcher-1.0.jar

You'll see:

  _____ _____  _       _    __                    
  |_   _|  __ \| |     | |  / _|                   
    | | | |__) | | __ _| |_| |_ ___  _ __ _ __ ___  
    | | |  ___/| |/ _` | __|  _/ _ \| '__| '_ ` _ \ 
   _| |_| |    | | (_| | |_| || (_) | |  | | | | | |
  |_____|_|    |_|\__,_|\__|_| \___/|_|  |_| |_| |_|

platform-java 1.0 - Java Application Platform
Type 'help' for commands

platform-java>

Deploy Your First Application

Let's deploy the Hello World sample:

# Build the sample
cd ../../platform-java-samples/hello-world
mvn clean package
cd ../../platform-java-launcher/target

# Launch platform and deploy
java -jar platform-java-launcher-1.0.jar

platform-java> deploy hello-world ../../platform-java-samples/hello-world/target/sample-hello-world-1.0.jar org.flossware.platform-java.samples.helloworld.HelloWorldApp
Application deployed: hello-world

platform-java> start hello-world
[hello-world] Hello from platform-java!
[hello-world] Application ID: hello-world
[hello-world] Running in thread: hello-world-pool-1
Application started: hello-world

platform-java> status hello-world
Application ID: hello-world
State: RUNNING
CPU Time: 1234567 ns
Heap Used: 1048576 bytes
Thread Count: 5
Active Threads: 2
Queued Tasks: 0
Completed Tasks: 1

platform-java> stop hello-world
Application stopped: hello-world

platform-java> list
Applications:
  hello-world - STOPPED

platform-java> exit
Shutting down platform...

Advanced: Descriptor-Based Deployment

Create a YAML descriptor (my-app.yaml):

applicationId: my-app
name: My Application
version: 1.0.0
mainClass: com.example.MyApp

classpathEntries:
  - file:///path/to/my-app.jar

threadPool:
  corePoolSize: 4
  maxPoolSize: 20

resources:
  maxHeapMB: 512

enableMessaging: true

properties:
  app.environment: production

Deploy it:

platform-java> deploy-yaml /path/to/my-app.yaml
Application deployed from YAML: my-app

platform-java> start my-app

Enable Web Console

For a graphical management interface:

java -jar platform-java-launcher-1.0.jar --rest-api --web-console

# Open browser to:
http://localhost:8080/console

The web console provides:

Application deployment via upload or paste
Start/stop/undeploy buttons
Real-time metrics charts (CPU, memory, threads)
Application properties viewer

Use Swing Desktop UI

For a native desktop management interface:

java -cp platform-java-swing-ui-1.1.jar:platform-java-api-1.1.jar:platform-java-core-1.1.jar \
    org.flossware.platform-java.swing.SwingConsole

# Or if using the executable JAR:
java -jar platform-java-swing-ui-1.1.jar

The Swing UI provides:

Application deployment via native file chooser
Start/stop/undeploy buttons
Real-time metrics table (CPU time, heap, threads)
Auto-refresh every 2 seconds
Native look and feel for your operating system

Note: Swing UI requires a display environment (X11, Wayland, Windows, macOS). It cannot run in headless CI/CD environments.

Use Terminal UI

For a full-screen terminal interface perfect for SSH sessions:

java -cp platform-java-terminal-ui-1.1.jar:platform-java-api-1.1.jar:platform-java-core-1.1.jar:lanterna-3.1.1.jar \
    org.flossware.platform.terminal.TerminalConsole

# Or integrated with launcher:
java -jar platform-java-launcher-1.1.jar --terminal-ui

The Terminal UI provides:

Full-screen terminal interface (like htop or vim)
Keyboard-driven navigation (arrow keys or vi-style j/k)
Color-coded application states
Real-time metrics updates
Start/stop/undeploy operations
Auto-refresh every 2 seconds
Works over SSH sessions

Keyboard Controls:

↑/↓ or j/k - Navigate applications
s - Start selected application
t - Stop selected application
u - Undeploy selected application
r - Refresh display
q - Quit

Note: Terminal UI requires a TTY (interactive terminal). It cannot run in cron jobs, systemd services, or CI/CD pipelines.

Enable Metrics Monitoring

JMX Metrics (JConsole, VisualVM)

java -jar platform-java-launcher-1.0.jar --jmx-port 9999

# In another terminal:
jconsole localhost:9999

# Navigate to MBeans tab → org.flossware.platform-java
# See per-application metrics and operations

Prometheus Metrics

java -jar platform-java-launcher-1.0.jar --prometheus

# Metrics endpoint:
curl http://localhost:9090/metrics

Output:

# HELP platform-java_app_cpu_time_seconds Total CPU time used by application
# TYPE platform-java_app_cpu_time_seconds counter
platform-java_app_cpu_time_seconds{app_id="my-app"} 123.45

# HELP platform-java_app_heap_used_bytes Heap memory used by application
# TYPE platform-java_app_heap_used_bytes gauge
platform-java_app_heap_used_bytes{app_id="my-app"} 134217728

# HELP platform-java_app_state Application lifecycle state
# TYPE platform-java_app_state gauge
platform-java_app_state{app_id="my-app",state="running"} 1.0
platform-java_app_state{app_id="my-app",state="stopped"} 0.0

Auto-Deployment via Filesystem Watcher

Enable automatic deployment when descriptor files are added:

# Create watch directory
mkdir /var/platform-java/apps

# Start launcher with watcher
java -jar platform-java-launcher-1.0.jar --watch-dir /var/platform-java/apps

# In another terminal, drop descriptor files:
cp my-app.yaml /var/platform-java/apps/

# Application automatically deploys and starts!
# Remove file to undeploy:
rm /var/platform-java/apps/my-app.yaml

REST API Usage

Start with REST API enabled:

java -jar platform-java-launcher-1.0.jar --rest-api

Deploy Application

curl -X POST http://localhost:8080/api/applications \
  -H "Content-Type: application/json" \
  -d '{
    "applicationId": "api-app",
    "mainClass": "com.example.ApiApp",
    "classpathEntries": ["file:///path/to/app.jar"],
    "threadPool": {
      "corePoolSize": 4,
      "maxPoolSize": 20
    }
  }'

List Applications

curl http://localhost:8080/api/applications

Start Application

curl -X POST http://localhost:8080/api/applications/api-app/start

Get Application Status

curl http://localhost:8080/api/applications/api-app/status

Stop and Undeploy

# Stop
curl -X POST http://localhost:8080/api/applications/api-app/stop

# Undeploy
curl -X DELETE http://localhost:8080/api/applications/api-app

Production Deployment

For production use, enable all features via command-line:

java -jar platform-java-launcher-1.0.jar \
  --rest-api \
  --port 8080 \
  --web-console \
  --jmx-port 9999 \
  --prometheus \
  --prometheus-port 9090 \
  --watch-dir /var/platform-java/apps

Or better yet, use a configuration file (platform.yaml):

api:
  enabled: true
  port: 8080
  bindAddress: 0.0.0.0

metrics:
  jmx:
    enabled: true
    port: 9999
    domain: org.flossware.platform-java
  prometheus:
    enabled: true
    port: 9090
    path: /metrics

watcher:
  enabled: true
  watchDirectory: /var/platform-java/apps
  autoStart: true
  autoDeploy: true

Then launch with:

java -jar platform-java-launcher-1.0.jar --config platform.yaml

This gives you:

REST API on port 8080
Web console at http://localhost:8080/console
JMX metrics on port 9999
Prometheus metrics on port 9090
Auto-deployment from /var/platform-java/apps

Command-line flags override configuration file settings:

# Override port from config file
java -jar platform-java-launcher-1.0.jar --config platform.yaml --port 9000

Deployment Modes

platform-java supports three deployment modes:

1. JVM Applications (Default)

Standard Java applications running in isolated classloaders:

applicationId: my-java-app
mainClass: com.example.MyApp
classpathEntries:
  - file:///path/to/app.jar

2. Native Processes

Deploy GraalVM native images or compiled executables:

applicationId: graal-app
nativeImage: true
classpathEntries:
  - file:///usr/local/bin/myapp

properties:
  native.args: "--server --port=8080"
  native.env.DATABASE_URL: "jdbc:postgresql://db/app"
  native.workdir: "/var/apps/graal-app"

See NATIVE_EXECUTION.md for details.

3. Containers

Deploy applications as Docker, Podman, or LXC containers:

applicationId: web-server
properties:
  container.runtime: docker
  container.image: nginx:alpine
  container.ports: "8080:80,8443:443"
  container.volumes: "/var/www:/usr/share/nginx/html"
  container.network: bridge
  container.env.NGINX_HOST: example.com

See CONTAINER_DEPLOYMENT.md for details.

Next Steps

Read the README for architecture details
Learn about Native Execution - GraalVM and compiled binaries
Learn about Container Deployment - Docker/Podman/LXC
Check examples/applications for sample descriptors
Explore sample applications in platform-java-samples
Review API documentation in platform-java-api

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

platform-java Quick Start Guide

Prerequisites

Build platform-java

Quick Start: Interactive Mode

Deploy Your First Application

Advanced: Descriptor-Based Deployment

Enable Web Console

Use Swing Desktop UI

Use Terminal UI

Enable Metrics Monitoring

JMX Metrics (JConsole, VisualVM)

Prometheus Metrics

Auto-Deployment via Filesystem Watcher

REST API Usage

Deploy Application

List Applications

Start Application

Get Application Status

Stop and Undeploy

Production Deployment

Deployment Modes

1. JVM Applications (Default)

2. Native Processes

3. Containers

Next Steps

FilesExpand file tree

QUICKSTART.md

Latest commit

History

QUICKSTART.md

File metadata and controls

platform-java Quick Start Guide

Prerequisites

Build platform-java

Quick Start: Interactive Mode

Deploy Your First Application

Advanced: Descriptor-Based Deployment

Enable Web Console

Use Swing Desktop UI

Use Terminal UI

Enable Metrics Monitoring

JMX Metrics (JConsole, VisualVM)

Prometheus Metrics

Auto-Deployment via Filesystem Watcher

REST API Usage

Deploy Application

List Applications

Start Application

Get Application Status

Stop and Undeploy

Production Deployment

Deployment Modes

1. JVM Applications (Default)

2. Native Processes

3. Containers

Next Steps