Package Exports

generator-jhipster-docker

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (generator-jhipster-docker) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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](#prerequisites" aria-hidden="true"><span aria-hidden="true)
[Installation](#installation" aria-hidden="true"><span aria-hidden="true)
[Usage](#usage" aria-hidden="true"><span aria-hidden="true)
[License](#license" aria-hidden="true"><span aria-hidden="true)

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:

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:

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:

src/main/docker/dev.yml
src/main/docker/prod.yml
src/main/docker/sonar.yml

If your project uses Elasticsearch as search engine, the configuration will be included in the src/main/docker/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 -f src/main/docker/dev.yml up -d

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

docker-compose -f src/main/docker/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 -f src/main/docker/dev.yml build

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

docker-compose -f src/main/docker/dev.yml up -d

Copy the cql scripts inside the container:

docker cp src/main/resources/config/cql/ "container id":/

Initialize the database by creating the Keyspace and the Tables:

docker exec -it "container id" init

After using entity sub generator, update the cql scripts inside the container:

docker cp src/main/resources/config/cql/ "container id":/

Create the tables:

docker exec -it "container id" entities

In production profile (with Clusters):

Build the image:

docker-compose -f src/main/docker/prod.yml build

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

docker-compose -f src/main/docker/prod.yml up -d

Copy the cql scripts inside the container:

docker cp src/main/resources/config/cql/ "container id":/

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 src/main/docker/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

After using entity sub generator, update the cql scripts inside the container:

docker cp src/main/resources/config/cql/ "container id":/

Create the tables:

docker exec -it "container id" entities

1.2.3 - Starting Cassandra the next times

In development profile:

docker-compose -f src/main/docker/dev.yml up -d

In production profile:

docker-compose -f src/main/docker/prod.yml up -d

1.3 - Working with Sonar

When generating your application, the src/main/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 src/main/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 -f src/main/docker/dev.yml stop

In production profile:

docker-compose -f src/main/docker/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! 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: src/main/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 src/main/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! 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 base image
- If you selected Tomcat or WildFly, put the url
- Select the version of your database
- Select the version of ElasticSearch
- Use volume or not
- Put your Docker Hub username
- Put your the tag
- Choose if you want to push your image to Docker Hub

⏳ 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 base image : use default (Java)
- Select the version of your database : use default
- Select the version of ElasticSearch : use default
- Use volume or not : use default (No)
- Put your Docker Hub username : put example
- Put your the tag : use default (latest)
- Choose if you want to push your image to Docker Hub : use default (No)

3.3.3 - Use src/main/docker/app.yml

The src/main/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 src/main/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"