Docker Support for platform-java

Official Docker images for platform-java are published and maintained for easy deployment in containerized environments.

Quick Start

The fastest way to get started:

# Run with REST API and Web Console
docker run \
  -p 8080:8080 \
  flossware/platform-java:latest \
  --rest-api --web-console

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

Image Registries

platform-java images are available from three major registries:

Docker Hub

docker pull flossware/platform-java:latest
docker pull flossware/platform-java:1.1
docker pull flossware/platform-java:latest-alpine

GitHub Container Registry (GHCR)

docker pull ghcr.io/flossware/platform-java:latest
docker pull ghcr.io/flossware/platform-java:1.1
docker pull ghcr.io/flossware/platform-java:latest-alpine

Quay.io

docker pull quay.io/flossware/platform-java:latest
docker pull quay.io/flossware/platform-java:1.1
docker pull quay.io/flossware/platform-java:latest-alpine

Image Variants

Main Image

Tags: latest, main, 1.1, 1.1, etc.
Base: eclipse-temurin:21-jre-noble
Size: ~670MB
Use Case: Full-featured deployments with best JVM performance
Platforms: linux/amd64, linux/arm64

Alpine Variant

Tags: latest-alpine, alpine, 1.1-alpine, etc.
Base: eclipse-temurin:21-jre-alpine
Size: ~400MB
Use Case: Space-constrained environments, cloud deployments
Platforms: linux/amd64, linux/arm64

Running platform-java

Basic Container

Start platform-java with default configuration:

docker run flossware/platform-java:latest

With REST API and Web Console

docker run \
  -p 8080:8080 \
  flossware/platform-java:latest \
  --rest-api --web-console

Access the Web Console at http://localhost:8080/console

With All Features

docker run \
  -p 8080:8080 \
  -p 9090:9090 \
  -p 9999:9999 \
  -e JAVA_OPTS="-Xms1g -Xmx2g" \
  flossware/platform-java:latest \
  --rest-api --web-console --prometheus --jmx-port 9999

Port mapping:

8080: REST API and Web Console
9090: Prometheus metrics
9999: JMX metrics

With Custom Configuration

Create platform.yaml:

api:
  enabled: true
  port: 8080
  bind-address: 0.0.0.0
  auth-enabled: true
  
metrics:
  prometheus:
    enabled: true
    port: 9090
  
watcher:
  enabled: true
  watch-directory: "/app/apps"
  auto-deploy: true

Run with config:

docker run \
  -p 8080:8080 \
  -v $(pwd)/platform.yaml:/app/config/platform.yaml \
  flossware/platform-java:latest \
  --config /app/config/platform.yaml

With Application Directory

Mount a directory for auto-deployment:

mkdir apps

docker run \
  -p 8080:8080 \
  -v $(pwd)/apps:/app/apps \
  flossware/platform-java:latest \
  --rest-api --watch-dir /app/apps

Copy application descriptors to the apps directory for automatic deployment.

Resource Limits

Constrain memory and CPU:

docker run \
  -p 8080:8080 \
  -m 2g \
  --cpus="2" \
  -e JAVA_OPTS="-Xms1g -Xmx1g" \
  flossware/platform-java:latest \
  --rest-api --web-console

Logging

View platform logs:

docker logs <container-id>
docker logs -f <container-id>  # Follow logs

Docker Compose

Use the included docker-compose.yml for orchestrated deployment:

Basic Setup

docker-compose up

This starts:

platform-java with REST API, Web Console, and metrics
Automatic application deployment directory

Full Monitoring Stack

Include Prometheus and Grafana:

docker-compose --profile monitoring up

This adds:

Prometheus for metrics collection
Grafana for visualization (http://localhost:3000)

Custom Configuration

Create config/platform.yaml:

api:
  enabled: true
  port: 8080
  auth-enabled: true

metrics:
  prometheus:
    enabled: true
    port: 9090

watcher:
  enabled: true
  watch-directory: "/app/apps"
  auto-deploy: true

Run:

docker-compose up

Building Images

Build your own images from source:

Main Image

docker build -t my-platform-java:latest .

Alpine Variant

docker build -t my-platform-java:latest-alpine -f Dockerfile.alpine .

With Custom Base JDK

docker build \
  --build-arg BASE_IMAGE=eclipse-temurin:21-jre-jammy \
  -t my-platform-java:jammy .

Image Contents

Images include:

Java Runtime: Eclipse Temurin 21 JRE
Platform JAR: platform-java-launcher with all modules
Configuration: Example platform.yaml
Health Check: Automated REST API availability check
Non-root User: Runs as platform user (UID 1000) for security
Volumes: /app/config, /app/apps, /app/logs

Security

Default Security Features

Runs as non-root user (platform:1000)
No privileged mode required
Restricted file permissions
Health checks enabled
TLS/HTTPS support via environment

Security Considerations

Authentication: Enable API authentication in production
```
api:
  auth-enabled: true
```

Network Isolation: Use Docker networks

docker network create platform-net
docker run --network platform-net flossware/platform-java:latest

Secret Management: Use Docker secrets or environment files

docker run --env-file secrets.env flossware/platform-java:latest

Registry Authentication: Authenticate to registries

docker login ghcr.io
docker pull ghcr.io/flossware/platform-java:latest

Environment Variables

Key environment variables:

Variable	Default	Description
`JAVA_OPTS`	`-Xms512m -Xmx1024m`	JVM options
`PLATFORM_CONFIG`	`/app/config/platform.yaml`	Config file path
`PLATFORM_APPS_DIR`	`/app/apps`	Applications directory
`PLATFORM_LOGS_DIR`	`/app/logs`	Logs directory

Example:

docker run \
  -e JAVA_OPTS="-Xms2g -Xmx4g -XX:+UseG1GC" \
  -e PLATFORM_CONFIG=/app/config/custom.yaml \
  flossware/platform-java:latest

Monitoring

Health Check

Images include built-in health checks:

docker ps  # Shows health status

# Force health check
docker exec <container-id> curl -f http://localhost:8080/api/health

Metrics Collection

Enable Prometheus metrics:

docker run \
  -p 9090:9090 \
  flossware/platform-java:latest \
  --prometheus

Access metrics at http://localhost:9090/metrics

JMX Monitoring

Enable JMX for tools like JConsole:

docker run \
  -p 9999:9999 \
  -e JAVA_OPTS="-Dcom.sun.management.jmxremote ..." \
  flossware/platform-java:latest \
  --jmx-port 9999

Troubleshooting

Container won't start

Check logs:

docker logs <container-id>

Common issues:

Port already in use: -p 8080:9000 (map to different port)
Memory constraints: -m 2g for minimum 2GB
Configuration file missing: Mount volume correctly

REST API not responding

docker exec <container-id> curl -f http://localhost:8080/api/health

Ensure --rest-api flag is passed to container.

High memory usage

Adjust JVM heap:

docker run \
  -e JAVA_OPTS="-Xms1g -Xmx2g" \
  flossware/platform-java:latest

Application deployment not working

Check watcher is enabled:

watcher:
  enabled: true
  watch-directory: "/app/apps"
  auto-deploy: true

Verify volume is mounted:

docker exec <container-id> ls -la /app/apps

Performance Tuning

For High-Throughput

docker run \
  -m 8g \
  --cpus="4" \
  -e JAVA_OPTS="-Xms6g -Xmx6g -XX:+UseG1GC -XX:MaxGCPauseMillis=100" \
  flossware/platform-java:latest

For Low-Latency

docker run \
  -e JAVA_OPTS="-Xms4g -Xmx4g -XX:+UseG1GC -XX:MaxGCPauseMillis=50 -XX:+ParallelRefProcEnabled" \
  flossware/platform-java:latest

For Space-Constrained

Use Alpine variant:

docker run \
  -m 512m \
  -e JAVA_OPTS="-Xms256m -Xmx256m" \
  flossware/platform-java:latest-alpine

Publishing to Registries

Docker Hub

docker tag platform-java:latest flossware/platform-java:1.1
docker push flossware/platform-java:1.1

GitHub Container Registry

docker tag platform-java:latest ghcr.io/flossware/platform-java:1.1
docker push ghcr.io/flossware/platform-java:1.1

Quay.io

docker tag platform-java:latest quay.io/flossware/platform-java:1.1
docker push quay.io/flossware/platform-java:1.1

Advanced Topics

Multi-Stage Development

Create development image with build tools:

FROM maven:3.9-eclipse-temurin-21 AS dev
WORKDIR /dev
COPY . .
RUN mvn clean install

FROM flossware/platform-java:latest
COPY --from=dev /dev/target/platform-launcher-*.jar /app/

Kubernetes Deployment

Example Kubernetes manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: platform-java
spec:
  replicas: 2
  selector:
    matchLabels:
      app: platform-java
  template:
    metadata:
      labels:
        app: platform-java
    spec:
      containers:
      - name: platform-java
        image: ghcr.io/flossware/platform-java:latest
        ports:
        - containerPort: 8080
          name: api
        - containerPort: 9090
          name: metrics
        env:
        - name: JAVA_OPTS
          value: "-Xms512m -Xmx1024m"
        livenessProbe:
          httpGet:
            path: /api/health
            port: 8080
          initialDelaySeconds: 15
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /api/health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10

Contributing

To contribute Docker improvements:

Modify Dockerfile and/or Dockerfile.alpine
Test with: docker build -t platform-java:test .
Submit pull request

Support

Issues: https://github.com/FlossWare/platform-java/issues
Discussions: https://github.com/FlossWare/platform-java/discussions
Documentation: https://github.com/FlossWare/platform-java/blob/main/README.md

License

Images are built from source code licensed under GPL v3. See LICENSE file.

FilesExpand file tree

DOCKER.md

Latest commit

History

DOCKER.md

File metadata and controls

Docker Support for platform-java

Quick Start

Image Registries

Docker Hub

GitHub Container Registry (GHCR)

Quay.io

Image Variants

Main Image

Alpine Variant

Running platform-java

Basic Container

With REST API and Web Console

With All Features

With Custom Configuration

With Application Directory

Resource Limits

Logging

Docker Compose

Basic Setup

Full Monitoring Stack

Custom Configuration

Building Images

Main Image

Alpine Variant

With Custom Base JDK

Image Contents

Security

Default Security Features

Security Considerations

Environment Variables

Monitoring

Health Check

Metrics Collection

JMX Monitoring

Troubleshooting

Container won't start

REST API not responding

High memory usage

Application deployment not working

Performance Tuning

For High-Throughput

For Low-Latency

For Space-Constrained

Publishing to Registries

Docker Hub

GitHub Container Registry

Quay.io

Advanced Topics

Multi-Stage Development

Kubernetes Deployment

Contributing

Support

License