Installing JHipster

Installation types

We provide 3 ways of working with JHipster:

A “local installation”, which is the classical way of working with JHipster. Everything is installed on your machine, which can be a little complex to set up, but that’s how most people usually work. In case of doubt, choose this installation.
A Vagrant-based “development box”, with all tools already set up in a Ubuntu-based virtual machine.
A “Docker” container, which brings you a lightweight, virtualized container with JHipster installed.

Local installation (recommended for normal users)

Install Java 8 from the Oracle website.
(Optional) Install a Java build tool.
- Whether you choose to use Maven or Gradle, you normally don’t have to install anything, as JHipster will automatically install the Maven Wrapper or the Gradle Wrapper for you.
- If you don’t want to use those wrappers, go to the official Maven website or Gradle website to do your own installation.
Install Git from git-scm.com. We recommend you also use a tool like SourceTree if you are starting with Git.
Install Node.js from the Node.js website (prefer an LTS version). This will also install npm, which is the node package manager we are using in the next commands.
Install Yeoman: npm install -g yo
Install Bower: npm install -g bower
Install Gulp: npm install -g gulp-cli (If you have previously installed a version of gulp globally, please run npm rm -g gulp to make sure your old version doesn’t collide with gulp-cli)
Install JHipster: npm install -g generator-jhipster

To find more information, tips and help, please have a look at the Yeoman “getting starting” guide and at the NPM documentation before submitting a bug.

Now that JHipster is installed, your next step is to create an application

Vagrant box installation

The JHipster development box project gives you a virtual machine with all the necessary tools to develop your JHipster project.

It’s an easy way to get up and running very quickly with JHipster.

Besides JHipster, this virtual machine includes many development tools, as well as Docker, so you should have everything ready for working.

Please go to the JHipster development box page for installation and configuration information.

Docker installation (for advanced users only)

Please note: this Docker image is for running the JHipster generator inside a container. It’s completely different from the Docker and Docker Compose configurations that JHipster will generate, which goal is to run your generated application inside a container

Information

JHipster has a specific Dockerfile, which provides a Docker image.

It makes a Docker “Automated build” that is available on: https://hub.docker.com/r/jhipster/jhipster/

This image will allow you to run JHipster inside Docker.

Prerequisites

This depends on your operating system.

Linux: Linux supports Docker out-of-box. You just need to follow the tutorial on the Docker website.
Mac & Windows: install the Docker Toolbox to get Docker installed easily.

As the generated files are in your shared folder, they will not be deleted if you stop your Docker container. However, if you don’t want Docker to keep downloading all the Maven and NPM dependencies every time you start the container, you should commit its state or mount a volume.

Warning: Based on your OS, your DOCKER_HOST will differ. On Linux, it will be simply your localhost. For Mac/Windows, you will have to obtain the IP using following command: docker-machine ip default

Tip: Kitematic is an easy-to-use graphical interface provided with the Docker Toolbox, which will makes this installation a lot easier.

On Linux, you might need to run the docker command as root user if your user is not part of docker group. It’s a good idea to add your user to docker group so that you can run docker commands as a non-root user. Follow the steps on http://askubuntu.com/a/477554 to do so.

Usage on Linux/Mac Windows (using Docker Toolbox)

Pull the image

Pull the latest JHipster Docker image:

docker pull jhipster/jhipster

Pull the development JHipster Docker image:

docker pull jhipster/jhipster:master

You can see all tags here

Run the image

Warning: If you are using Docker Machine on Mac or Windows, your Docker daemon has only limited access to your OS X or Windows file system. Docker Machine tries to auto-share your /Users (OS X) or C:\Users\<username> (Windows) directory. So you have to create the project folder under these directory to avoid any volume mounting issues.

Create a “jhipster” folder in your home directory:

mkdir ~/jhipster

Run the Docker image, with the following options:

The Docker “/home/jhipster/app” folder is shared to the local “~/jhipster” folder
Forward all ports exposed by Docker (8080 for Tomcat, 3000 for BrowserSync from the “gulp serve” task, 3001 for the BrowserSync UI)

docker run --name jhipster -v ~/jhipster:/home/jhipster/app -v ~/.m2:/home/jhipster/.m2 -p 8080:8080 -p 3000:3000 -p 3001:3001 -d -t jhipster/jhipster

Tip: If you have already started the container once before, you do not need to run the above command, you can simply start/stop the existing container.

Check if the container is running

To check that your container is running, use the command docker ps:

CONTAINER ID    IMAGE               COMMAND                 CREATED         STATUS          PORTS                                                       NAMES
4ae16c0539a3    jhipster/jhipster   "tail -f /home/jhipst"  4 seconds ago   Up 3 seconds    0.0.0.0:3000-3001->3000-3001/tcp, 0.0.0.0:8080->8080/tcp    jhipster

Common operations

To stop the container execute: docker stop jhipster
And to start again, execute: docker start jhipster

In case you update the Docker image (rebuild or pull from the Docker hub), it’s better to remove the existing container, and run the container all over again. To do so, first stop the container, remove it and then run it again:

docker stop jhipster
docker rm jhipster
docker pull jhipster/jhipster
docker run --name jhipster -v ~/jhipster:/home/jhipster/app -v ~/.m2:/home/jhipster/.m2 -p 8080:8080 -p 3000:3000 -p 3001:3001 -d -t jhipster/jhipster

Accessing the container

The easiest way to log into the running container is by executing following command:

docker exec -it <container_name> bash

If you copy-pasted the above command to run the container, notice that you have to specify jhipster as the container name:

docker exec -it jhipster bash

You will login as “jhipster” user. In case you need to do a sudo, the password for the user is the same as the username (jhipster).

Your first project

You can then go to the /home/jhipster/app directory in your container, and start building your app inside Docker:

cd /home/jhipster/app

yo jhipster

Once your application is created, you can run all the normal gulp/bower/maven commands, for example:

./mvnw

Congratulations! You’ve launched your JHipster app inside Docker!

On your host machine, you should be able to :

Access the running application at http://DOCKER_HOST:8080
Get all the generated files inside your shared folder