[#39 Add clustering support with Consul (#40)

.gitignore

@@ -42,3 +42,5 @@ local.properties
 .settings/
 .loadpath
 
+# Consul data
+consul-data/

Dockerfile

@@ -13,5 +13,8 @@ ENV OPENWEATHERMAP_API_KEY=openweatherapikey
 ENV SEGMENTIO_WRITE_API_KEY=segmentioapikey
 ENV ACTUATOR_USERNAME=username
 ENV ACTUATOR_PASSWORD=password
+ENV SPRING_CLOUD_CONSUL_ENABLED=false
+ENV SPRING_CLOUD_CONSUL_HOST=localhost
+ENV SPRING_CLOUD_CONSUL_PORT=8500
 
 ENTRYPOINT ["java", "org.springframework.boot.loader.JarLauncher"]

README.md

@@ -12,22 +12,68 @@ Eris is a simple Spring Boot Java API that is developed as a consolidation of th
 
 The technology stack consists of Spring Boot framework only. The free version of the service is also hosted on Heroku. Though the API can be hosted in any platform that supports Spring Boot. Feel free to fork it and create your private API.
 
-## Heroku deployment
+## Dependencies
 
-[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/kasramp/Eris)
+The project depends on JDK 17 and Maven. Make sure to have them installed. Any other project dependencies exist in pom.xml file and once you run the project, they will be downloaded.
 
-## Dependencies
-All the project dependencies exist in pom.xml file and once your run the project, all dependencies will be downloaded.
+## Development
+
+Eris can operate in **two modes**:
+  - Standalone: single node (default)
+  - Cluster: multiple nodes registering with Consul
+
+### Standalone mode
+
+To run the project in standalone mode just run,
+
+```bash
+$ mvn spring-boot:run
+```
+
+### Cluster mode 
+
+To test the cluster mode, you need to have the Consul agent up and running. You can use `docker-compose.yml` file included in the project,
+
+```bash
+$ docker-compose -f docker-compose.yml up
+```
+
+After that, enable the cluster mode via exporting the following environment variable,
 
-## How to use
+```bash
+$ export SPRING_CLOUD_CONSUL_ENABLED=true
+```
 
-To run and deploy the project on your local or any desired server, first clone the project and the follow the below instruction.
-- Add Open Weather Map API key to `apikey.properties` that located under `resource` folder.
-- Compile and run the API using Maven
+Lastly, run the project,
 
-        $ maven clean install
-        $ cd target
-        $ java -jar eris-[version]-SNAPSHOT.jar
+```bash
+$ mvn spring-boot:run
+```
+
+You can monitor the Eris instance via Consul UI at [http://localhost:8500/ui](http://localhost:8500/ui).
+
+## Build JAR file
+
+If you decide to build your own Über-JAR file to deploy either locally or on a server, after cloning the project, you have to set `openweathermap` key
+and `actuator.username` and `actuator.password`. For that, modify `apikey.properties` and `application.properties` file respectively before generating
+the JAR file. Alternatively, you can overwrite them those variables at runtime, see `Dockerfile` for all variable names.
+
+To generate the Über-JAR, run:
+
+```bash
+$ maven clean install
+```
+
+To test the generated JAR file,
+
+```bash
+$ cd target
+$ java -jar eris-[version]-SNAPSHOT.jar
+```
+
+## Heroku deployment
+
+[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/kasramp/Eris)
 
 ## Project & API documentation
 
@@ -53,5 +99,5 @@ GNU General Public License for more details.  <http://www.gnu.org/licenses/>
 
 Author(s):
 
-© 2017-2023 Kasra Madadipouya <[email protected]> 
+© 2017-2024 Kasra Madadipouya <[email protected]> 
 

consul-server-config.json

@@ -0,0 +1,13 @@
+{
+  "node_name": "Cassini",
+  "server": true,
+  "data_dir": "consul-data",
+  "log_level": "INFO",
+  "client_addr": "0.0.0.0",
+  "bind_addr": "0.0.0.0",
+  "advertise_addr": "127.0.0.1",
+  "bootstrap_expect": 1,
+  "ui_config": {
+    "enabled": true
+  }
+}

docker-compose.yml

@@ -0,0 +1,13 @@
+version: '3.8'
+services:
+  consul-dev:
+    image: consul:1.15.4
+    container_name: consul-dev
+    restart: unless-stopped
+    ports:
+      - "8500:8500"
+      - "8600:8600/udp"
+    volumes:
+      - ./consul-server-config.json:/consul/config/consul-config.json
+      - ./consul-data:/consul/config
+    #command: "agent -dev -client 0.0.0.0"

pom.xml

@@ -47,6 +47,10 @@
             <groupId>org.springframework.cloud</groupId>
             <artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
         </dependency>
+        <dependency>
+            <groupId>org.springframework.cloud</groupId>
+            <artifactId>spring-cloud-starter-consul-discovery</artifactId>
+        </dependency>
         <dependency>
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-actuator</artifactId>

src/main/resources/application.properties

@@ -1,3 +1,7 @@
+spring.application.name=Eris
 spring.mvc.throw-exception-if-no-handler-found=true
 #spring.resources.add-mappings=false
-management.endpoints.web.exposure.include=*
+management.endpoints.web.exposure.include=*
+spring.cloud.consul.host=localhost
+spring.cloud.consul.port=8500
+spring.cloud.consul.enabled=false