From 103427b2270c62fb8be76e9d6811c7b03f236c7e Mon Sep 17 00:00:00 2001 From: Andrea Di Cesare Date: Sun, 14 Jan 2024 16:54:44 +0100 Subject: [PATCH] :memo: Update setup-with-docker.adoc --- docs/setup-with-docker.adoc | 117 ++++++++++++++++++++++++++++++------ 1 file changed, 100 insertions(+), 17 deletions(-) diff --git a/docs/setup-with-docker.adoc b/docs/setup-with-docker.adoc index 04363f30..51efe412 100644 --- a/docs/setup-with-docker.adoc +++ b/docs/setup-with-docker.adoc @@ -60,53 +60,50 @@ $ docker run --rm -p "8080:8080" --add-host host.docker.internal:host-gateway so NOTE: This command relies on the docker support of `host.docker.internal`. If you are using an old docker version or a docker runtime that does not support it, than you need to configure the docker network accordingly (you can refer to the brilliant link:https://stackoverflow.com/questions/24319662/from-inside-of-a-docker-container-how-do-i-connect-to-the-localhost-of-the-mach["From inside of a Docker container, how do I connect to the localhost of the machine?" on StackOverflow]) or use one of the an alternative methods described in the further sections. -Your RESTHeart setup documentation is quite detailed, but it can be further refined for clarity and ease of use. Here's an improved version: +## Run RESTHeart and network isolated MongoDB with Docker ---- - -## Run RESTHeart and MongoDB with Docker +This setup involves a RESTHeart container interfacing with a MongoDB container via a private Docker network. This arrangement ensures network isolation, with the RESTHeart API serving as the sole entry point. This configuration allows the two containers to communicate securely and efficiently within their dedicated network environment, while external access is streamlined and controlled through the RESTHeart API ### Setup Procedure This setup only needs to be completed once. Follow these steps: -1. **Create a Docker Network** +1) **Create a Docker Network** Create a dedicated network for RESTHeart and MongoDB communication: [source,bash] $ docker network create restheart-network -2. **Start MongoDB Container** +2) **Start MongoDB Container** Launch a MongoDB container within the created network: [source,bash] -$ docker run -d --name mongodb --network restheart-network mongo:7.0 --replSet=rs0 +$ docker run -d --name mongodb --network restheart-network mongo --replSet=rs0 -3. **Initialize MongoDB as a Single Node Replica Set** +3) **Initialize MongoDB as a Single Node Replica Set** Initialize the MongoDB instance to work as a single node replica set: [source,bash] -$ docker exec -it mongodb /bin/bash -c 'mongosh --quiet --eval "rs.initiate()"' +$ docker run -it --network restheart-network --rm mongo mongosh --host mongodb --quiet --eval "rs.initiate()" -4. **Launch RESTHeart Container** +4) **Launch RESTHeart Container** Run the RESTHeart container, linking it to the MongoDB container: [source,bash] - $ docker run --name restheart --rm --network restheart-network -p "8080:8080" -e RHO='/http-listener/host->"0.0.0.0";/mclient/connection-string->"mongodb://mongodb"' softinstigate/restheart -[source,bash] +$ docker run --name restheart --rm --network restheart-network -p "8080:8080" -e RHO='/http-listener/host->"0.0.0.0";/mclient/connection-string->"mongodb://mongodb"' softinstigate/restheart -5. **Test the Setup** +5) **Test the Setup** Execute a test request to verify that RESTHeart is running: [source,bash] ---- - $ http -b http://localhost:8080/ping - # Expected Output: Greetings from RESTHeart! +$ http -b http://localhost:8080/ping +# Expected Output: Greetings from RESTHeart! ---- ### Stopping the Containers @@ -120,16 +117,102 @@ $ docker stop restheart mongodb The RESTHeart container is stateless and is removed upon stopping (due to the `--rm` option). However, the MongoDB container retains its state and is not removed on stop. To restart, use the following commands: -1. **Start MongoDB Container** +1) **Start MongoDB Container** [source,bash] $ docker start mongodb -2. **Run RESTHeart Container** +2) **Run RESTHeart Container** [source,bash] $ docker run --name restheart --rm --network restheart-network -p 8080:8080 -e RHO='/http-listener/host->"0.0.0.0";/mclient/connection-string->"mongodb://mongodb"' softinstigate/restheart +### How to connect to MongoDB with mongosh + +[source,bash] +$ docker run -it --network restheart-network --rm mongo mongosh --host mongodb + +## Run RESTHeart and MongoDB with Docker + +WARNING: This setup is insecure and should be only used for developing or testing purposes. + +### Setup Procedure + +This setup only needs to be completed once. Follow these steps: + +1) **Start MongoDB Container** + +Launch a MongoDB container within the created network: + +[source,bash] +$ docker run -d --name mongodb -p 27017:27017 mongo --replSet=rs0 + +3) **Initialize MongoDB as a Single Node Replica Set** + +Initialize the MongoDB instance to work as a single node replica set: + +[source,bash] +$ docker exec mongodb mongosh --quiet --eval "rs.initiate()" + +4) **Launch RESTHeart Container** + +Run the RESTHeart container, linking it to the MongoDB container: + +[source,bash] +$ docker run --name restheart --rm -p "8080:8080" softinstigate/restheart + +5) **Test the Setup** + +Execute a test request to verify that RESTHeart is running: + +[source,bash] +---- +$ http -b http://localhost:8080/ping +# Expected Output: Greetings from RESTHeart! +---- + +### Stopping the Containers + +To stop both RESTHeart and MongoDB containers, use the following command: + +[source,bash] +$ docker stop restheart mongodb + +### Restarting the Containers + +The RESTHeart container is stateless and is removed upon stopping (due to the `--rm` option). However, the MongoDB container retains its state and is not removed on stop. To restart, use the following commands: + +1) **Start MongoDB Container** + +[source,bash] +$ docker start mongodb + +2) **Run RESTHeart Container** + +[source,bash] +$ docker run --name restheart --rm -p "8080:8080" softinstigate/restheart + +### Run RESTHeart with custom plugin + +If the plugin jar file is in the directory `./target`, this command starts RESTHeart with the plugin integrated: + +[surce,bash] +$ docker run --name restheart --rm -p "8080:8080" -v ./target:/opt/restheart/plugins/custom softinstigate/restheart + +NOTE: This command requires RESTHeart version equal or greater than 7.7. + +### Run RESTHeart with remote debugger + +This runs RESTHeart enabling remove debugging (port 4000). + +[surce,bash] +$ docker run --rm -p 8080:8080 -p 4000:4000 --entrypoint "java" softinstigate/restheart -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:4000 -jar restheart.jar + +### How to connect to MongoDB with mongosh + +[source,bash] +$ docker exec -it mongodb mongosh + == The RESTHeart Docker tags RESTHeart Docker images come in four different versions: