RESTHeart Plugin Skeleton

This repository provides a skeleton project for developing plugins for RESTHeart, a REST API platform for MongoDB.

Documentation for plugins development is available at https://restheart.org/docs/plugins/overview/.

Check also the RESTHeart Greetings Services Tutorial

---

Requirements

• Java 24 (or GraalVM 24): Required to compile and run the plugin.
• Docker: Used to containerize and run RESTHeart.

Note: for RESTHeart 8.0.0 to 8.9.x, use Java 21 (or GraalVM 21)

NOTE: For a known bug affecting RESTHeart 8.10, 8.11 and 8.12 (after migration to Java 24), for native build use RESTHeart 8.13+

---

Quick Start

Option 1: Use the RESTHeart CLI (Recommended)

🚀 The RESTHeart CLI provides automatic rebuilding and hot-reloading during development.

Follow the Usage Guide to set up a continuous development workflow.

Option 2: Build and Run with Docker

1. Clone and navigate:

   git clone --depth 1 [email protected]:SoftInstigate/restheart-plugin-skeleton.git
   cd restheart-plugin-skeleton

2. Build (choose Maven or Gradle):

   Maven:

   ./mvnw clean package

   Gradle:

   ./gradlew clean build

   Both produce identical outputs in the target/ directory.

3. Run with Docker:

   docker run --pull=always --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s

   Note: The -s flag runs in standalone mode (no MongoDB). Remove it to enable MongoDB-dependent plugins.

4. Test the service:

   curl localhost:8080/srv
   {"message":"Hello World!","rnd":"njXZksfKFW"}

---

Build Systems: Maven vs Gradle

Both build systems are fully supported and produce identical outputs:

Feature	Maven	Gradle
Build Command	./mvnw clean package	./gradlew clean build
Native Image	./mvnw package -Pnative	./gradlew build -Pnative
Profile Activation	-Psecurity,mongodb	-Psecurity -Pmongodb
Build Speed	Moderate	Faster (incremental, daemon)

Choose based on your preference - both work equally well for plugin development.

---

Working with MongoDB

To run RESTHeart with MongoDB:

1. Start MongoDB:

   docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0

   docker exec mongodb mongosh --quiet --eval "rs.initiate()"

2. Build your plugin:

   Maven:

   ./mvnw clean package

   Gradle:

   ./gradlew clean build

3. Run RESTHeart (without -s flag to enable MongoDB plugins):

   docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart

4. Test:

   curl -u admin:secret localhost:8080/users

⚠️ Warning: This setup is insecure - for development/testing only.

Note: Your plugin only depends on restheart-commons (provided scope). RESTHeart running in Docker already includes all its plugins (MongoDB, Security, GraphQL, etc.).

---

Profiles for Native Image Builds

Important: These profiles are only used when building native executables (-Pnative). They bundle RESTHeart plugins into the native executable. For regular JAR builds, your plugin only depends on restheart-commons.

Profile	Description	Maven Syntax	Gradle Syntax
native	Build native executable with GraalVM	-Pnative	-Pnative
security	Bundle RESTHeart Security into native image	-Psecurity	-Psecurity
mongodb	Bundle RESTHeart MongoDB into native image	-Pmongodb	-Pmongodb
graphql	Bundle RESTHeart GraphQL into native image	-Pgraphql	-Pgraphql
mongoclient-provider	Bundle MongoDB client provider	-Pmongoclient-provider	-Pmongoclient-provider
metrics	Bundle RESTHeart Metrics into native image	-Pmetrics	-Pmetrics
all-restheart-plugins	Bundle all RESTHeart plugins	-Pall-restheart-plugins	-Pall-restheart-plugins

Examples

Native executable with Security and MongoDB plugins bundled:

Maven:

./mvnw clean package -Pnative,security,mongodb

Gradle:

./gradlew clean build -Pnative -Psecurity -Pmongodb

Native executable with all RESTHeart plugins bundled:

Maven:

./mvnw clean package -Pnative,all-restheart-plugins

Gradle:

./gradlew clean build -Pnative -Pall-restheart-plugins

---

Building Native Images

Native images provide faster startup and lower memory usage.

Requirements

Install GraalVM using SDKMAN:

sdk install java 24.0.2-graalce
sdk use java 24.0.2-graalce

Build Commands

Quick build (faster, default):

Maven:

./mvnw clean package -Pnative

Gradle:

./gradlew clean build -Pnative

Full optimization (slower build, faster runtime):

Maven:

./mvnw clean package -Pnative -Dnative.quickBuild=false

Gradle:

./gradlew clean build -Pnative -Pnative.quickBuild=false

Custom garbage collector (G1 on Linux, serial elsewhere):

Maven:

./mvnw clean package -Pnative -Dnative.gc=--gc=G1

Gradle:

./gradlew clean build -Pnative -Pnative.gc=--gc=G1

Run Native Executable

# Basic run
./target/restheart-plugin-skeleton

# With configuration override
RHO="/fullAuthorizer/enabled->true" ./target/restheart-plugin-skeleton

Output structure:

target/
├── restheart-plugin-skeleton.jar      # Plugin JAR
├── restheart-plugin-skeleton          # Native executable (with -Pnative)
└── lib/                               # Runtime dependencies

---

Configuration

Runtime Configuration with RHO

Override settings without rebuilding using the RHO environment variable:

docker run --name restheart --rm -e RHO="/http-listener/host->'0.0.0.0';/helloWorldService/message->'Ciao Mondo!'" -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart -s

Test:

curl localhost:8080/srv
{"message":"Ciao Mondo!","rnd":"rhyXFHOQUA"}

See RESTHeart Configuration for more details.

---

Dependencies

Adding Dependencies

Dependencies are automatically copied to target/lib/ and loaded by RESTHeart.

Maven (pom.xml):

<dependency>
    <groupId>com.example</groupId>
    <artifactId>my-library</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle (build.gradle):

dependencies {
    implementation 'com.example:my-library:1.0.0'
}

Avoiding Duplicate JARs

RESTHeart bundles many libraries. Use provided scope for dependencies already included:

<dependency>
    <groupId>org.restheart</groupId>
    <artifactId>restheart-commons</artifactId>
    <version>${restheart.version}</version>
    <scope>provided</scope>
</dependency>

To see what's included:

git clone https://github.com/SoftInstigate/restheart.git
cd restheart
mvn dependency:tree -Dscope=compile

---

Troubleshooting

Build Issues

Gradle-specific:

# Clean build without cache
./gradlew clean build --no-build-cache

# Stop and restart daemon
./gradlew --stop
./gradlew clean build

Native Image Issues

1. Verify GraalVM:

   java -version  # Should show GraalVM
   which native-image
   native-image --version

2. Build with verbose output:

   Maven:

   ./mvnw package -Pnative -X

   Gradle:

   ./gradlew build -Pnative --info

Debugging

View Docker logs:

docker logs -f restheart

Common issues:

• 405 Method Not Allowed: Check HTTP method handling in your service class
• Missing OPTIONS handler: Add handleOptions(req) for CORS support

---

Gradle-Specific Features

Performance Benefits

Gradle provides faster builds through:

• Incremental compilation: Only changed files are recompiled
• Build daemon: JVM stays warm between builds (1-3s vs 5-10s with Maven)
• Parallel execution: Independent tasks run concurrently
• Build cache: Reuses outputs from previous builds

Gradle Tasks

./gradlew tasks              # List all tasks
./gradlew clean              # Delete build outputs
./gradlew build              # Full build
./gradlew jar                # Create JAR only
./gradlew nativeCompile      # Build native image

Configuration Properties

Edit gradle.properties to customize:

# RESTHeart version
restheart.version=[8.12.0,8.1000.0)

# Native image settings
native.gc=--gc=serial
native.quickBuild=true

---

Next Steps

• 📖 Read the RESTHeart Plugins Documentation
• 🎓 Follow the Greetings Services Tutorial
• 🔧 Explore the RESTHeart CLI for hot-reloading
• 🚀 Check Deployment Guide for production tips