Note: This has been tested with docker version 1.10+. Please upgrade if you have an older docker version. To check your version: $ docker -v.
RESTHeart fully embraces a microservices architecture. The quickest way to run RESTHeart + MongoDB both as docker containers is to use docker-compose.
The file docker-compose.yml defines a single microservice made of a RESTHeart and MongoDB instance configured to work together.
To start both services just type:
$ docker-compose up -d
Creating restheartdocker_mongodb_1
Creating restheartdocker_restheart_1
Check everything is fine:
$ docker-compose ps
Name Command State Ports
-------------------------------------------------------------------------------------------------------
restheartdocker_mongodb_1 /entrypoint.sh mongod Up 0.0.0.0:27017->27017/tcp
restheartdocker_restheart_1 ./entrypoint.sh etc/resthe ... Up 4443/tcp, 0.0.0.0:8080->8080/tcp
Tail the logs of both services:
$ docker-compose logs -f
Attaching to restheartdocker_restheart_1, restheartdocker_mongodb_1
restheart_1 | 08:44:28.538 [main] INFO org.restheart.Bootstrapper - Starting RESTHeart instance restheart-docker
restheart_1 | 08:44:28.546 [main] INFO org.restheart.Bootstrapper - version 2.0.1
restheart_1 | 08:44:28.557 [main] INFO org.restheart.Bootstrapper - Logging to file /var/log/restheart.log with level DEBUG
...
restheart_1 | 08:44:30.044 [main] INFO org.restheart.Bootstrapper - Pid file /var/run/restheart--1441246088.pid
restheart_1 | 08:44:30.045 [main] INFO org.restheart.Bootstrapper - RESTHeart started
You can now create a database with curl or httpie
$ http -j -a admin:changeit PUT 127.0.0.1:8080/testdb
HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ETag, Auth-Token, Auth-Token-Valid-Until, Auth-Token-Location, X-Powered-By
Auth-Token: 7275cf59-4b51-4a44-aa34-f393c617bd16
Auth-Token-Location: /_authtokens/admin
Auth-Token-Valid-Until: 2016-06-11T09:08:50.859Z
Connection: keep-alive
Content-Length: 0
Date: Sat, 11 Jun 2016 08:53:50 GMT
ETag: 575bd19efca13600050d9581
X-Powered-By: restheart.org
GET the testdb
$ http -a admin:changeit 127.0.0.1:8080/testdb
HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Location, ETag, Auth-Token, Auth-Token-Valid-Until, Auth-Token-Location, X-Powered-By
Auth-Token: 7275cf59-4b51-4a44-aa34-f393c617bd16
Auth-Token-Location: /_authtokens/admin
Auth-Token-Valid-Until: 2016-06-11T09:11:14.843Z
Connection: keep-alive
Content-Encoding: gzip
Content-Length: 113
Content-Type: application/hal+json
Date: Sat, 11 Jun 2016 08:56:14 GMT
ETag: 575bd0fefca13600050d957d
X-Powered-By: restheart.org
{
"_etag": {
"$oid": "575bd0fefca13600050d957d"
},
"_id": "testdb",
"_returned": 0,
"_size": 0,
"_total_pages": 0
}
See our API Tutorial for more.
This section is useful if you want to run RESTHeart with docker but you already have an existing MongoDB container to connect to. Note that if instead you want to connect to a remote MongoDB instance then you must edit the restheart.yml configuration file and change the mongouri.
mongo-uri: mongodb://<remote-host>
You can then decide to rebuild the container itself with your version of this file or mount the folder as a volume, so that you can override the default configuration files. For example:
$ docker run -d -p 80:8080 --name restheart -v "$PWD"/etc:/opt/restheart/etc:ro softinstigate/restheart:2.0.1
We strongly recommend to always add the tag to the image (e.g.
softinstigate/restheart:2.0.1), so that you are sure which version of RESTHeart you are running.
docker pull mongo:3.2docker pull softinstigate/restheart:2.0.1
We recommend to pull a specific MongoDB image, for example
docker pull mongo:3.2. RESTHeart has been tested so far with MongoDB 2.6, 3.0 and 3.2.
docker run -d --name mongodb mongo:3.2
To make it accessible from your host and add a persistent data volume:
docker run -d -p 27017:27017 --name mongodb -v <db-dir>:/data/db mongo:3.2
The <db-dir> must be a folder in your host, such as /var/data/db or whatever you like. If you don't attach a volume then your data will be lost when you delete the container.
Run in foreground, linking to the mongodb instance, mapping the container's 8080 port to the 80 port on host:
docker run --rm -i -t -p 80:8080 --name restheart --link mongodb softinstigate/restheart:2.0.1
In alternative, you might prefer to run it in background:
docker run -d -p 80:8080 --name restheart --link mongodb softinstigate/restheart:2.0.1
If it's running in background, you can open the RESTHeart's logs:
docker logs restheart
You can append arguments to docker run command to provide RESTHeart and the JVM with arguments.
For example you can mount an alternate configuration file and specify it as an argument
docker run --rm -i -t -p 80:8080 -v my-conf-file.yml:/opt/restheart/etc/my-conf-file.yml:ro --name restheart --link mongodb:mongodb softinstigate/restheart:2.0.1 my-conf-file.yml
If you want to pass system properties to the JVM, just specify -D or -X arguments. Note that in this case you need to provide the configuration file as well.
docker run --rm -i -t -p 80:8080 --name restheart --link mongodb:mongodb softinstigate/restheart:2.0.1 etc/restheart.yml -Dkey=value
If you are running the docker-machine from Docker Toolbox then point your browser to something like:
Beware your configuration might use a different IP address than 192.168.99.100. Issue the env command to discover the real IP (usually docker-machine env default)
If you are running Docker directly on a Linux box:
Whenever the browser asks for credentials then use the following:
username: admin
password: changeit
To stop the RESTHeart background daemon just issue
docker stop restheart
or simply press CTRL-C if it was running in foreground.
You can start it again with
docker start restheart
but it's not recommended: RESTHeart is a stateless service, best Docker practices would suggest to just delete the stopped container with docker rm restheart or to run it in foreground with the --rm parameter, so that it will be automatically removed when it exits.
The MongoDB container instead is stateful, so if you delete it then you'll lose all data unless you attached to it a persistent volume. In this case you might prefer to start it again, so that your data is preserved, or ypu might prefer to attach a local Docker Volume to it.
To stop MongoDb issue
docker stop mongodb
To start MongoDb again
docker start mongodb
Note that you must always stop RESTHeart before MongoDB, or you might experience data losses.
When you containers are up and running you can go to the official RESTHeart's Documentation.
Made with ❤️ by The SoftInstigate Team. Follow us on Twitter.