Skip to content

Commit

Permalink
📖 Add BUILD.md documentation for building and testing RESTHeart
Browse files Browse the repository at this point in the history
  • Loading branch information
@mkjsix
mkjsix committed Dec 13, 2024
1 parent a892977 commit 8be1bc1
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 135 deletions.
61 changes: 61 additions & 0 deletions BUILD.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Build RESTHeart from Source

Build the thin JAR:

```sh
./mvnw clean package
```

Check the build version:

```sh
java -jar core/target/restheart.jar -v
RESTHeart Version 8.0.7-SNAPSHOT Build-Time 2024-07-17
```

To build the fat JAR, add the `shade` Maven profile:

```sh
./mvnw clean package -P shade
```

## Running Integration Tests

To execute the integration test suite:

```sh
./mvnw clean verify
```

The `verify` goal starts the RESTHeart process and a MongoDB Docker container before running the integration tests.

To avoid starting the MongoDB Docker container, specify the system property `-P-mongodb`.

The integration tests use the MongoDB connection string `mongodb://127.0.0.1` by default. To use a different connection string, specify the property `test-connection-string`.

## Test with FerretDB

[FerretDB](https://www.ferretdb.com/) allows you to use MongoDB drivers seamlessly with __PostgreSQL__ as the database backend. Use all tools, drivers, UIs, and the same query language and stay open-source.

Example of running the integration test suite against an instance of FerretDB on `localhost`:

```sh
# Run FerretDB
docker run -d --rm --name ferretdb -p 27017:27017 ghcr.io/ferretdb/all-in-one
# Execute the integration tests
./mvnw clean verify -DskipUTs -P-mongodb -Dtest-connection-string="mongodb://username:password@localhost/ferretdb?authMechanism=PLAIN" -Dkarate.options="--tags ~@requires-replica-set"
```

This example skips tests tagged with `requires-replica-set` (FerretDB so far does not support change stream and transactions) and uses `-DskipUTs` to skip the execution of unit tests.

## Automatic SNAPSHOT Builds

Snapshot Maven artifacts are available from [sonatype.org](https://s01.oss.sonatype.org/content/repositories/snapshots/org/restheart/restheart/) repository.

Docker images of snapshots are also available from [Docker Hub](https://hub.docker.com/r/softinstigate/restheart-snapshot).

```sh
docker pull softinstigate/restheart-snapshot
```

You can even pull a [specific commit](https://hub.docker.com/r/softinstigate/restheart-snapshot/tags).
166 changes: 31 additions & 135 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# RESTHeart - Ready to use backend for the modern Web.
# RESTHeart

## Comprehensive Java backend solution offering a low-code API development framework on top of MongoDB.
RESTHeart is a __Java__ backend framework that facilitates the rapid development of __REST__, __GraphQL__, and __WebSocket__ APIs, leveraging __MongoDB__ for data storage.

[![GitHub last commit](https://img.shields.io/github/last-commit/softinstigate/restheart)](https://github.com/SoftInstigate/restheart/commits/master)
[![Build snapshot release](https://github.com/SoftInstigate/restheart/actions/workflows/branch.yml/badge.svg)](https://github.com/SoftInstigate/restheart/actions/workflows/branch.yml)
Expand All @@ -9,31 +9,24 @@
[![Docker Pulls](https://img.shields.io/docker/pulls/softinstigate/restheart.svg?maxAge=2592000)](https://hub.docker.com/r/softinstigate/restheart/)
[![Join the chat on Slack](https://img.shields.io/badge/chat-on%20slack-orange)](https://join.slack.com/t/restheart/shared_invite/zt-1olrhtoq8-5DdYLBWYDonFGEALhmgSXQ)

RESTHeart is a modern Java backend solution enabling **REST**, **GraphQL**, and **WebSocket** APIs. It features a low-code development framework, ready-to-use security, and seamless **MongoDB** API integration.
### Who Benefits from RESTHeart?

## Key Features of RESTHeart
RESTHeart is designed for:
- __Developers__ seeking a low-code solution to build scalable, secure, and high-performance APIs.
- __Teams__ aiming to reduce development time and complexity when working with MongoDB.
- __Businesses__ looking for a reliable and efficient way to expose data through REST or GraphQL APIs.

✅ **Low-Code Backend Foundation**: RESTHeart serves as a robust foundation for creating low-code backends, offering flexibility and power for on-premises deployment.

✅ **Instant Backend Launch**: Developers can swiftly connect RESTHeart to a MongoDB database, enabling the rapid launch of a fully functional backend without extensive coding.

✅ **Seamless Integration**: It integrates seamlessly with MongoDB, providing a hassle-free connection for data handling and management.

✅ **Customizable APIs**: RESTHeart empowers developers to create and customize APIs quickly, enabling efficient communication between applications and the backend.

✅ **Security and Compliance**: Built-in security features ensure robust protection for data and endpoints, meeting compliance standards for sensitive information handling.

✅ **Scalability and Performance**: Designed for scalability, RESTHeart maintains high performance even with increased data loads, ensuring smooth operations as applications grow.

✅ **On-Premises Control**: Offers the advantages of on-premises deployment, granting developers full control over the backend infrastructure while maintaining the ease of a low-code approach.

✅ **Concurrency**: Powered by the new [Java 21 Virtual Threads](https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html) lightweight concurrency model.
---

✅ **Built on Undertow**: RESTHeart is built on top of the [Undertow](https://undertow.io/) web server.
## Key Features

> Undertow is a high-performance web server written in Java, known for its flexibility and efficiency. It provides both blocking and non-blocking APIs based on NIO (Non-blocking I/O), making it suitable for a wide range of use cases from lightweight HTTP handlers to full-fledged servlet containers. Notably, Undertow is the default web server for the WildFly application server and [replaces JBoss Web in JBoss EAP 7](https://docs.redhat.com/en/documentation/red_hat_jboss_enterprise_application_platform/7.3/html/development_guide/undertow).
✅ **Low-Code Development**: Create APIs with minimal coding effort.
✅ **Seamless MongoDB Integration**: Instantly expose your MongoDB collections via REST, GraphQL, and WebSocket APIs.
✅ **Built-in Security**: Provides declarative authentication and authorization mechanisms.
✅ **High Performance**: Utilizes Java 21 Virtual Threads for efficient concurrency.
✅ **Customizable**: Flexible architecture that adapts to your specific needs.

### Supported Databases
## Compatible Databases

- [MongoDB](https://www.mongodb.com/)
- [MongoDB Atlas Cloud Database](https://www.mongodb.com/products/platform/atlas-database)
Expand All @@ -42,15 +35,7 @@ RESTHeart is a modern Java backend solution enabling **REST**, **GraphQL**, and
- [Amazon DocumentDB](https://docs.aws.amazon.com/documentdb/latest/developerguide/what-is.html) (*)
- [Microsoft Azure CosmosDB](https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/) (*)

> (*) Some of these databases might have partial compatibility with MongoDB APIs.
## Documentation

The full documentation is available on [restheart.org/docs](https://restheart.org/docs/).

To explore the APIs, start with:
- [The REST Data API Tutorial](https://restheart.org/docs/mongodb-rest/tutorial)
- [The GraphQL Data API Tutorial](https://restheart.org/docs/mongodb-graphql/tutorial)
> (*) Might be partially compatibile with MongoDB.
## Quick Start with Docker Compose

Expand All @@ -62,7 +47,7 @@ curl https://raw.githubusercontent.com/SoftInstigate/restheart/master/docker-com
&& docker compose up --pull=always --attach restheart
```

2. Open another terminal and call RESTHeart's ping service with [curl](https://curl.se/) or any other tool you like, to verify it's running:
1. Call RESTHeart's ping service with [curl](https://curl.se/) to verify it's running:

```sh
curl -i localhost:8080/ping
Expand All @@ -82,113 +67,28 @@ Greetings from RESTHeart!

## Running Without Docker

1. Download a pre-built binary of RESTHeart and all plugins from the [Releases](https://github.com/SoftInstigate/restheart/releases) page.
2. Uncompress the `restheart.tar.gz` or `restheart.zip` archive to create a `restheart` folder:

```
.
├── COMM-LICENSE.txt
├── LICENSE.txt
├── plugins
│   ├── restheart-graphql.jar
│   ├── restheart-metrics.jar
│   ├── restheart-mongoclient-provider.jar
│   ├── restheart-mongodb.jar
│   ├── restheart-polyglot.jar
│   └── restheart-security.jar
└── restheart.jar
```

3. Start MongoDB on `localhost:27017` and then run RESTHeart with its default configuration:

1. Download a pre-built binary of RESTHeart from the [Releases](https://github.com/SoftInstigate/restheart/releases) page.
2. Uncompress the `restheart.tar.gz` or `restheart.zip` archive
3. `cd restheart`
4. Start MongoDB on `localhost:27017` and then run RESTHeart with its default configuration:

```sh
java -jar restheart.jar
```

4. To connect to a MongoDB server running in a remote host, you can quickly [modify the configuration with the RHO env var](https://restheart.org/docs/configuration#modify-the-configuration-with-the-rho-env-var).

## Software Development Framework

RESTHeart offers an SDK for developing custom plugins. A plugin in RESTHeart enhances the API by adding new features and capabilities. RESTHeart supports creating plugins in Java, Kotlin, any language supported by the JVM, JavaScript, or any language supported by GraalVM.
> To connect to a MongoDB server running in a remote host, you can quickly [modify the configuration with the RHO env var](https://restheart.org/docs/configuration#modify-the-configuration-with-the-rho-env-var).
Types of plugins in RESTHeart:
## Build from Source

1. **Service**: Adds new web services to the API.
2. **Interceptor**: Monitors and modifies requests and responses at various stages of the request lifecycle.
3. **Initializer**: Runs initialization logic during system startup.
4. **Provider**: Supplies objects to other plugins using the `@Inject` annotation.
To build from source or to run the integration tests suite look at [BUILD.md](BUILD.md).

Additionally, security plugins can be developed to customize the security layer.

## Building from Source

Build the thin JAR:

```sh
./mvnw clean package
```

Check the build version:

```sh
java -jar core/target/restheart.jar -v
RESTHeart Version 8.0.7-SNAPSHOT Build-Time 2024-07-17
```

To build a fat JAR, add the `shade` Maven profile:

```sh
./mvnw clean package -Pshade
```

## Running Integration Tests

To execute the integration test suite:

```sh
./mvnw clean verify
```

The `verify` goal starts the RESTHeart process and a MongoDB Docker container before running the integration tests.

To avoid starting the MongoDB Docker container, specify the system property `-P-mongodb`.

The integration tests use the MongoDB connection string `mongodb://127.0.0.1` by default. To use a different connection string, specify the property `test-connection-string`.

Example of running the integration test suite against an instance of [FerretDB](https://www.ferretdb.io) on `localhost`:

```sh
# Run FerretDB
docker run -d --rm --name ferretdb -p 27017:27017 ghcr.io/ferretdb/all-in-one
# Execute the integration tests
./mvnw clean verify -DskipUTs -P-mongodb -Dtest-connection-string="mongodb://username:password@localhost/ferretdb?authMechanism=PLAIN" -Dkarate.options="--tags ~@requires-replica-set"
```

This example skips tests tagged with `requires-replica-set` (FerretDB does not support change stream and transactions) and uses `-DskipUTs` to skip the execution of unit tests.

## Automatic Snapshot Builds

Snapshot builds are available from [sonatype.org](https://s01.oss.sonatype.org/content/repositories/snapshots/org/restheart/restheart/).

Docker images of snapshots are also available:

```sh
docker pull softinstigate/restheart-snapshot:[commit-short-hash]
```

To find the commit short hash, use:

```sh
git log
```

The short hash is the first 7 digits of the commit hash. For example, for commit `2108ce033da8a8c0b65afea0b5b478337e44e464`, the short hash is `2108ce0` and the Docker pull command is:
## Documentation

```
The full documentation is available on [restheart.org/docs](https://restheart.org/docs/).

bash
docker pull softinstigate/restheart-snapshot:2108ce0
```
To explore the APIs, start with:
- [The REST Data API Tutorial](https://restheart.org/docs/mongodb-rest/tutorial)
- [The GraphQL Data API Tutorial](https://restheart.org/docs/mongodb-graphql/tutorial)

## Community Support

Expand All @@ -211,11 +111,7 @@ docker pull softinstigate/restheart-snapshot:2108ce0
</tbody>
</table>

### Become a Sponsor

You can support the development of RESTHeart via the GitHub Sponsor program and receive public acknowledgment of your help.

[See available sponsor tiers.](https://github.com/sponsors/SoftInstigate)
If you enjoy using this open-source project, you can support the development of RESTHeart via the [GitHub Sponsor program](https://github.com/sponsors/SoftInstigate).

---

Expand Down

0 comments on commit 8be1bc1

Please sign in to comment.