generator-jhipster-docker

generator-jhipster-docker

JHipster module, Docker support in your JHipster application

Introduction

This is a JHipster module, that is meant to be used in a JHipster application. This module is used to :

• Generate docker-compose services
• Generate files for Automated build at Docker Hub
• Containerize your application and push image to Docker Hub

Prerequisites

As this is a JHipster module, we expect you have JHipster and its related tools already installed:

• Installing JHipster

You have to install Docker and Docker Compose:

• Docker
• Docker Compose

To use Automated build or Pushing your application to Docker Hub, you have to create an account at:

• https://hub.docker.com/

All these images come from the official Docker Hub:

• MySQL
• PostgreSQL
• MongoDB
• Cassandra
• Elasticsearch
• SonarQube

Installation

To install this module:

npm install -g generator-jhipster-docker

To update this module:

npm update -g generator-jhipster-docker

Usage

To run the module on a JHipster generated application:

yo jhipster-docker

You can use this command to generate docker-compose services with default options:

yo jhipster-docker default

To force the generator:

yo jhipster-docker default --force

1 - Generate docker-compose services

1.1 - Description

When using the option Generate docker-compose services, if your project uses MySQL, PostgreSQL, MongoDB or Cassandra, these files will be generated in your folder project:

• docker-compose.yml
• docker-compose-prod.yml
• docker/sonar.yml

If your project uses Elasticsearch as search engine, the configuration will be included in the docker-compose-prod.yml file.

So you can use docker-compose to start your database in development or production profile.

The main JHipster Generator already generated the docker-compose services described here: docker_compose. You can use this option to use a specific version of database or to use volumes.

1.2 - Working with databases

1.2.1 - Starting MySQL, PostgreSQL or MongoDB

In development profile:

docker-compose up -d

In production profile (it will start ElasticSearch too if you selected it as search engine):

docker-compose -f docker-compose-prod.yml up -d

1.2.2 - Starting Cassandra the first time

In development profile:

Build the image, which will contain the CQL scripts generated by your project for initializing the database:

docker-compose build

Start the container (it will show the container id):

docker-compose up -d

Initialize the database by creating the Keyspace and the Tables:

docker exec -it "container id" init

In production profile (with Clusters):

Build the image:

docker-compose -f docker-compose-prod.yml build

Start the container (it will show the container id):

docker-compose -f docker-compose-prod.yml up -d

Initialize the database by creating the Keyspace and the Tables:

docker exec -it "container id" init

Add X other nodes (it's optional):

docker-compose -f docker-compose-prod.yml scale <name_of_your_app>-cassandra-node=X

Manage nodes with OpsCenter: http://localhost:8888

Before starting your application in production profile, add in your application-prod.yml every IP of containers to the key spring.data.cassandra.contactPoints

1.2.3 - Starting Cassandra the next times

In development profile:

docker-compose up -d

In production profile:

docker-compose -f docker-compose-prod.yml up -d

1.3 - Working with Sonar

When generating your application, the docker/sonar.yml is generated in your folder project. So you can start a sonar instance to analyze your code:

Start a sonar instance:

docker-compose -f docker/sonar.yml up -d

Analyze your code with Maven:

mvn sonar:sonar

Analyze your code with Gradle:

./gradlew sonar

You can access to sonar: http://localhost:9000

1.4 - Common commands

1.4.1 - List the containers

You can use docker ps -a to list all the containers

$ docker ps -a
CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
fc35e1090021        mysql               "/entrypoint.sh mysql"   4 seconds ago       Up 4 seconds        0.0.0.0:3306->3306/tcp   sampleapplication-mysql

1.4.2 - Stop the containers

In development profile:

docker-compose stop

In production profile:

docker-compose -f docker-compose-prod.yml stop

You can use directly docker:

docker stop "container id"

When you stop a container, the data are not deleted, unless you delete the container.

1.4.3 - Delete a container

:warning: Warning! All data will be deleted (unless you used volumes):

docker rm "container id"

2 - Automated build at the Docker Hub

2.1 - Description

When using the option Generate files for Automated build, Docker Hub will build a Docker image everytime you commit to your repository.

2.2 - Generate the files

• Launch : yo jhipster-docker
• Select the option : Generate files for Automated build at https://hub.docker.com/
• Answer all questions
  • Select the version of your database
  • Select the version of ElasticSearch
  • Put the URL of your Git repository
  • Put your Docker Hub username

2.3 - Set your Docker Hub project

• Go to https://hub.docker.com/r/username/ (replace username by yours)
• Menu Create:
  • Select Create Automated Build
  • Select the repository
  • Put a description, then click on create

• Go to Build Settings
  • Choose your branch or let master by default
  • Put this Dockerfile location: /docker/hub/
  • Click on Save Changes

• Return to this project: git commit and push these changes!
• Go to Build details: it should be a new line with Building
• Go to Repo info and copy/paste in Full description the docker/app-hub.yml

3 - Containerize your application and push image to Docker Hub

3.1 - Description

This option is used to build a Docker image for running the JHipster application. You can read this documentation for more details: spring-boot-docker

If you want, you can push your Docker image to Docker Hub.

:warning: Warning! Don't put your credentials in config files, if you decided to push your application to Docker Hub

3.2 - Containerize your application

• Launch : yo jhipster-docker
• Select the option : Containerize your application and push image to https://hub.docker.com/
• Answer all questions
  • Select the version of your database
  • Select the version of ElasticSearch
  • Put your Docker Hub username
  • Put your the tag
  • Use volume or not
  • Choose if you want to push your image to Docker Hub

:hourglass_flowing_sand: Be patient! This may take several minutes, depending on the speed of your connection.

3.3 - Examples

3.3.1 - Generate a JHipster application

Use this .yo-rc.json to generate your JHipster application. All options are default, except ElasticSearch :

{
  "generator-jhipster": {
    "baseName": "jhipster",
    "packageName": "com.mycompany.myapp",
    "packageFolder": "com/mycompany/myapp",
    "authenticationType": "session",
    "hibernateCache": "ehcache",
    "clusteredHttpSession": "no",
    "websocket": "no",
    "databaseType": "sql",
    "devDatabaseType": "h2Disk",
    "prodDatabaseType": "mysql",
    "searchEngine": "elasticsearch",
    "useSass": false,
    "buildTool": "maven",
    "frontendBuilder": "grunt",
    "enableTranslation": true,
    "enableSocialSignIn": false,
    "rememberMeKey": "24d8cfa8a79d120b76c5b6076a766fa4eaee525f",
    "testFrameworks": [
      "gatling"
    ]
  }
}

3.3.2 - Containerize your JHipster application

• Launch : yo jhipster-docker
• Select the option : Containerize your application and push image to https://hub.docker.com/
• Answer all questions
  • Select the version of your database : use default
  • Select the version of ElasticSearch : use default
  • Put your Docker Hub username : put example
  • Put your the tag : use default (latest)
  • Use volume or not : use default (No)
  • Choose if you want to push your image to Docker Hub : use default (No)

3.3.3 - Use docker/app.yml

The docker/app.yml is generated:

jhipster-app-elasticsearch:
  container_name: jhipster-app-elasticsearch
  image: elasticsearch:1.7.3
  ports:
    - "9200:9200"
    - "9300:9300"
jhipster-app-mysql:
  container_name: jhipster-app-mysql
  image: mysql:5.7.9
  environment:
    - MYSQL_USER=root
    - MYSQL_ALLOW_EMPTY_PASSWORD=yes
    - MYSQL_DATABASE=jhipster
  ports:
    - "3306:3306"
  command: mysqld --lower_case_table_names=1
jhipster-app:
  container_name: jhipster-app
  image: example/jhipster:latest
  ports:
    - "8080:8080"
  links:
    - "jhipster-app-elasticsearch:elastic"
    - "jhipster-app-mysql:mysql"

You can use this file to start ElasticSearch, MySQL. Then, your JHipster application will start after 20sec:

docker-compose -f docker/app.yml up

3.3.4 - Add spring properties

You can add other spring-boot properties, using this variable environment JHIPSTER_SPRING_ADD. For example, to redefine the server.port:

jhipster-app-elasticsearch:
  container_name: jhipster-app-elasticsearch
  image: elasticsearch:1.7.3
  ports:
    - "9200:9200"
    - "9300:9300"
jhipster-app-mysql:
  container_name: jhipster-app-mysql
  image: mysql:5.7.9
  environment:
    - MYSQL_USER=root
    - MYSQL_ALLOW_EMPTY_PASSWORD=yes
    - MYSQL_DATABASE=jhipster
  ports:
    - "3306:3306"
  command: mysqld --lower_case_table_names=1
jhipster-app:
  container_name: jhipster-app
  image: example/jhipster:latest
  environment:
    - JHIPSTER_SPRING_ADD=--server.port=18080
  ports:
    - "8080:18080"
  links:
    - "jhipster-app-elasticsearch:elastic"
    - "jhipster-app-mysql:mysql"

3.3.5 - Start in dev profile

You can use this variable environment JHIPSTER_SPRING to redefine all spring-boot properties when starting the JHipster application. For example, you can start this application in dev profile, without ElasticSearch and MySQL. The application will use H2 database:

jhipster-app:
  container_name: jhipster-app
  image: example/jhipster:latest
  environment:
    - JHIPSTER_SLEEP=1
    - JHIPSTER_SPRING=--spring.profiles.active=dev
  ports:
    - "8080:8080"

License

Apache-2.0 © Pascal Grimaud