Installing JHipster
Installation types
We provide 6 ways of working with JHipster. If in doubt, choose our 2nd option, “Local installation with Yarn”:
- JHipster Online is a simple way to generate an application without installing JHipster in the first place.
- “Local installation with Yarn” 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.
- “Local installation with NPM” is the same as classical “local installation with Yarn”, but using NPM instead of Yarn
- “Installation with a package manager” is only available for Mac OS X and Windows. This is a very simple installation method, if you use a package manager, but it is still in BETA.
- The Vagrant-based “development box”, with all tools already set up in a Ubuntu-based virtual machine.
- The “Docker” container, which brings you a lightweight container with JHipster installed.
JHipster Online (for users wanting a simplified way to run JHipster)
JHipster Online allows you to easily generate JHipster applications, without having to install JHipster.
This is intended for people trying JHipster for the first time, or who just want to have a look at what JHipster provides.
While it is easier to use, it is not the “full JHipster experience”, and once your application is generated you will still need to follow most of the steps from the next section (“Local installation with Yarn”), as you will still need Java (to run your application) and Yarn (to manage your front-end code).
In the future, we expect JHipster Online to provide more features, of course.
Local installation with Yarn (recommended for normal users)
Quick setup
- Install Java 8 from the Oracle website.
- Install Node.js from the Node.js website (prefer an LTS 64-bit version)
- Install Yarn from the Yarn website
- If you want to use the JHipster Marketplace, install Yeoman:
yarn global add yo
- Install JHipster:
yarn global add generator-jhipster
Now that JHipster is installed, your next step is to create an application
Optional installations
- 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.
- JHipster will try to commit your project to Git, if it is installed.
- The JHipster upgrade sub-generator requires to have Git installed.
Troubleshooting
If you have problems using Yarn globally, be sure to have $HOME/.config/yarn/global/node_modules/.bin
in your path.
On Mac or Linux: export PATH="$PATH:`yarn global bin`:$HOME/.config/yarn/global/node_modules/.bin"
JHipster uses Yeoman for code generation. To find more information, tips and help, please have a look at the Yeoman “getting starting” guide and at the Yarn documentation before submitting a bug.
Local installation with NPM (alternative to Yarn)
This is the same procedure as using Yarn, with two differences:
- Instead of installing Yarn in step 3, update NPM:
npm install -g npm
- Use
npm install -g
instead ofyarn global add
, for example:- To install Yeoman, type:
npm install -g yo
- To install JHipster, type:
npm install -g generator-jhipster
- To install Yeoman, type:
You can find more information in the NPM documentation.
Installation with a package manager
Please note this is a BETA feature! If you selected this installation, don’t hesitate to send us a bug report or feedback on @java_hipster.
Installation with Homebrew on Mac OS X
JHipster provides a Homebrew package, available on http://formulae.brew.sh/formula/jhipster.
To install JHipster (as well as Node and Yarn), just type:
brew install jhipster
New versions of this package are published each time a new JHipster release is created, but it might take time for the Homebrew team to validate this package - so if you have an older JHipster release, please be patient or use the Yarn installation above.
Installation with Chocolatey on Windows
JHipster provides a Chocolatey package, available on https://chocolatey.org/packages/jhipster.
To install JHipster (as well as Node, Yarn, Yeoman, Java and Git), just type:
choco install jhipster
New versions of this package are published each time a new JHipster release is created, but it might take time for the Chocolatey team to validate this package - so if you have an older JHipster release, please be patient or use the Yarn installation above.
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.
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
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 image pull jhipster/jhipster
Pull the development JHipster Docker image:
docker image pull jhipster/jhipster:master
You can see all tags here
Run the image
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 the Java application, 9000 for BrowserSync, 3001 for the BrowserSync UI)
docker container run --name jhipster -v ~/jhipster:/home/jhipster/app -v ~/.m2:/home/jhipster/.m2 -p 8080:8080 -p 9000:9000 -p 3001:3001 -d -t jhipster/jhipster
Check if the container is running
To check that your container is running, use the command docker container 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:9000-3001->9000-3001/tcp, 0.0.0.0:8080->8080/tcp jhipster
Common operations
- To stop the container execute:
docker container stop jhipster
- And to start again, execute:
docker container 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 container stop jhipster
docker container rm jhipster
docker image pull jhipster/jhipster
docker container run --name jhipster -v ~/jhipster:/home/jhipster/app -v ~/.m2:/home/jhipster/.m2 -p 8080:8080 -p 9000:9000 -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 container 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 container exec -it jhipster bash
You will log in as the “jhipster” user.
If you want to log in as “root”, as the sudo
command isn’t available in Ubuntu Xenial, you need to run:
docker container exec -it --user root jhipster bash
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
jhipster
jhipster --npm
, to use NPM instead of Yarn.
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
jhipster/jhipster
image.
So you won't be able to:
- use the docker-compose files
- build a Docker image (Maven goal:
dockerfile:build
or Gradle task:buildDocker
)