## 1. Project Overview & Quickstart (jhipster/DONT_COMMENT_ON_OLD_ISSUE) # DONT_COMMENT_ON_OLD_ISSUE Open-source repository jhipster/DONT_COMMENT_ON_OLD_ISSUE ### Repository Details - **Repository:** [jhipster/DONT_COMMENT_ON_OLD_ISSUE](https://github.com/jhipster/DONT_COMMENT_ON_OLD_ISSUE) - **Primary Language:** Code *Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.* ## 2. Official Technical Reference & Guides (jhipster/jhipster.github.io) ## File: README.md ### Installation ``` npm install ``` ### Local Development ``` npm start ``` This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. ### Build ``` npm run build -- --locale en ``` This command generates static content into the `build` directory and can be served using any static content hosting service. ### Deployment Using SSH: ``` USE_SSH=true npm run deploy ``` Not using SSH: ``` GIT_USER= npm run deploy ``` If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. --- ## File: package.json { "name": "jhipster-website", "version": "2.0.0", "private": true, "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", "serve": "docusaurus serve", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids", "typecheck": "tsc", "analyze": "docusaurus build --bundle-analyzer" }, "dependencies": { "@docusaurus/core": "^3.10.2", "@docusaurus/plugin-client-redirects": "^3.10.2", "@docusaurus/preset-classic": "^3.10.2", "@kbox-labs/react-echarts": "^1.4.2", "@mdx-js/react": "^3.1.1", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "dayjs": "^1.11.23", "docusaurus-plugin-sass": "^0.2.7", "echarts": "^6.1.0", "embla-carousel-auto-scroll": "^8.6.0", "embla-carousel-react": "^8.6.0", "fetch-jsonp": "^1.4.0", "plugin-image-zoom": "^1.2.0", "prism-react-renderer": "^2.4.1", "react": "^19.3.1", "react-dom": "^19.3.1", "react-icons": "^5.7.0", "sass": "^1.105.2" }, "devDependencies": { "@docusaurus/module-type-aliases": "^3.6.0", "@docusaurus/tsconfig": "^3.10.2", "@docusaurus/types": "^3.6.0", "prettier": "^3.9.10", "typescript": "~7.0.2" }, "browserslist": { "production": [ ">0.5%", "not dead", "not op_mini all" ], "development": [ "last 3 chrome version", "last 3 firefox version", "last 5 safari version" ] }, "engines": { "node": ">=20.0" }, "overrides": { "@kbox-labs/react-echarts": { "echarts": "$echarts" } } } --- ## File: tsconfig.json { // This file is not used in compilation. It is here just for a nice editor experience. "extends": "@docusaurus/tsconfig", "compilerOptions": { "target": "ESNext", "baseUrl": ".", "types": ["docusaurus-plugin-sass"] } } --- ## File: docs/artwork.mdx --- title: Artwork slug: /artwork/ last_update: date: 2015-07-10T00:00:00-00:00 --- import useBaseUrl from '@docusaurus/useBaseUrl'; All our artwork can be found in our [artwork repository](https://github.com/jhipster/jhipster-artwork). ## The JHipster Logo ## The JHipster Banner ## The JHipster Family Below are some examples of the JHipster family members. ## Inclusiveness As with all JHipster projects, the JHipster Artwork project follows the [JHipster code of conduct](https://github.com/jhipster/generator-jhipster/blob/main/CODE_OF_CONDUCT.md). One of our goals is to have inclusive artwork: at the moment the "JHipster family" has a few members, but the idea is that this family grows, with many different members, as expressed in our code of conduct. If you want to help the project, you can either participate as an artist (the source files from all images are available in the [github repository](https://github.com/jhipster/jhipster-artwork)) or as a sponsor (so we can pay an artist to create those new images). All images are validated by [Audrey Neveu](https://x.com/Audrey_Neveu), who is well-known in the Java community for her involvement in [Devoxx4Kids](http://www.devoxx4kids.org/) and [Duchess France](https://www.duchess-france.org/). ## Logos and images usage All logos and images are available under the [Apache 2 license](pathname:///LICENSE.txt), and belong to the JHipster project. --- ## File: docs/association.mdx [Binary file] --- ## File: docs/fisherman.mdx --- title: Using Fisherman slug: /fisherman/ last_update: date: 2016-08-14T18:40:00-00:00 --- Fisherman has been renamed to [fisher](https://github.com/jorgebucaran/fisher). See the the [Fisher JHipster plugin](/fisher) documentation for details. --- ## File: docs/gcp.mdx --- title: Deploying to Google Cloud Platform displayed_sidebar: docsSidebar slug: /gcp/ last_update: date: 2023-12-19T00:00:00-00:00 --- [](https://cloud.google.com) You can deploy JHipster applications to Google Cloud Platform and run on: - Virtual machines with [Google Compute Engine](https://cloud.google.com/compute/) - Containers in Kubernetes with [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/) - Platform as a Service with [Google App Engine](https://cloud.google.com/appengine/) You can obtain [Google Cloud Platform free trial](https://cloud.google.com/free) to deploy your applications. Please check the [Always Free](https://cloud.google.com/free/) tiers for free usages up to the specified usage limits during and past the free trial. ## Before you start Install and authenticate with the gcloud SDK on your local environment to access `gcloud` CLI. For more information, visit this link: - [Install gcloud SDK](https://cloud.google.com/sdk/install) ## Deploy to Google Kubernetes Engine Google Kubernetes Engine is a fully managed Kubernetes cluster as a service. Once provisioned, you can deploy your containers and JHipster applications using standard Kubernetes commands. 1. Enable API: `gcloud services enable container.googleapis.com containerregistry.googleapis.com` 1. Install `kubectl` CLI if not already installed: `gcloud components install kubectl` 1. Create a new Google Kubernetes Engine cluster: `gcloud container clusters create mycluster --zone us-central1-a --machine-type n1-standard-4` _See GCP's [zones](https://cloud.google.com/compute/docs/regions-zones/) and [machine-types](https://cloud.google.com/compute/docs/machine-types/) for other options._ Once the cluster is created, you can use JHipster Kubernetes generator to generate the deployment descriptors. 1. Generate Kubernetes deployment files: `jhipster kubernetes` 1. If you want to use Google Container Registry to publish container images in a private registry: 1. **What should we use for the base Docker repository name** set to `gcr.io/YOUR_PROJECT_ID` Build the container image. 1. If you use Google Container Registry, you can build directly to the registry without local Docker daemon: `./mvnw package -Pprod jib:build` 1. Otherwise, build to Docker daemon: `./mvnw package -Pprod jib:dockerBuild` Deploy to Kubernetes cluster: 1. Apply the Kubernetes configurations: `./kubectl-apply.sh` For full Kubernetes generator features, see [Deploying to Kubernetes](/kubernetes). ## Enable HTTPS To enable HTTPS for your cluster, see Ray Tsang's [External Load Balancing docs](https://spring-gcp.saturnism.me/deployment/kubernetes/load-balancing/external-load-balancing). You can force the use of HTTPS by adding the following configuration to your `SecurityConfiguration.java`. ```java // Spring MVC http.requiresChannel(channel -> channel .requestMatchers(r -> r.getHeader("X-Forwarded-Proto") != null).requiresSecure()); // WebFlux http.redirectToHttps(redirect -> redirect .httpsRedirectWhen(e -> e.getRequest().getHeaders().containsKey("X-Forwarded-Proto"))); ``` See Spring Security's [Servlet](https://docs.spring.io/spring-security/site/docs/5.5.x/reference/html5/#servlet-http-redirect) and [WebFlux](https://docs.spring.io/spring-security/site/docs/5.5.x/reference/html5/#webflux-http-redirect) documentation for more information. --- ## File: docs/getting-started.mdx --- title: Getting Started --- import EmbeddedVideo from '@site/src/components/EmbeddedVideo' import Books from '@site/src/components/sections/docs/Books' ## JHipster Quick Start 1. Install [Java 21](https://adoptium.net/temurin/releases/?version=21), [Node.js](http://nodejs.org/), [Git](http://git-scm.com/) (recommended) and [Docker](docker-compose/) (recommended) 2. Install JHipster `npm install generator-jhipster` 3. Create a new directory and go into it `mkdir myApp && cd myApp` 4. Run JHipster and follow instructions on screen `jhipster` 5. Model your entities with [JDL Studio](https://start.jhipster.tech/jdl-studio/) and download the resulting `jhipster-jdl.jdl` file 6. Generate your entities with `jhipster import-jdl jhipster-jdl.jdl` ## Learn JHipster In 15 Minutes [Matt Raible](https://x.com/mraible) created a screencast that shows how to use JHipster 8 to develop a Spring Boot + Angular application. ## Books ## Community Tutorials and Trainings - [Play by Play: Developing Microservices and Mobile Apps with JHipster](https://www.pluralsight.com/courses/play-by-play-developing-microservices-mobile-apps-jhipster) by [Matt Raible](https://x.com/mraible) and [Michael Hoffman](https://x.com/mhi_inc) - [Angular 4 Java Developers by Dan Vega and John Thompson](https://therealdanvega.teachable.com/p/jhipster/?product_id=456739&coupon_code=JHIPSTER) - JHipster: Build and Deploy Spring Boot Microservices by Chris Anatalio ([LinkedIn Learning](https://www.linkedin.com/learning/jhipster-build-and-deploy-spring-boot-microservices), [Lynda.com](https://www.lynda.com/course-tutorials/JHipster-Build-Deploy-Microservices/624352-2.html)) - [Better Java Projects Faster with JHipster and Docker](https://betterprojectsfaster.com/learn/tutorial-jhipster-docker-01) (3 part series) by [Karsten Silz](https://betterprojectsfaster.com/about/) --- ## File: docs/jhipster-app.mdx --- title: JHipster App displayed_sidebar: docsSidebar slug: /jhipster-app/ last_update: date: 2016-08-29T12:40:00-00:00 --- **DEPRECATED** Due to lack of success, the JHipster App is now deprecated. You can still find it on [the JHipster App GitHub repository](https://github.com/jhipster/jhipster-app). ## Downloads The application binaries (for Mac, Windows and Linux) are available on [the GitHub release page](https://github.com/jhipster/jhipster-app/releases). --- ## File: docs/jhipster-lite.mdx --- title: JHipster Lite slug: /jhipster-lite/ last_update: date: 2022-09-14T00:00:00-00:00 --- ## What is JHipster Lite? :::warning JHipster Lite maintenance has been transferred to the [Seed4J organization][Seed4J repository], and the project has been renamed to [Seed4J][Seed4J website]. ::: As JHipster, **JHipster Lite ⚑** will help you to start your project, focusing on generating step by step only what you need. Some details about the solution: - The generated code uses [Hexagonal Architecture] - The technical code is separated from your business code - You will only generate the code you want, no additional unused code - The best quality as possible: πŸ’―% code coverage, 0 code smell, no duplication 😎 - This generator is a webapp using Java (Spring Boot) and Vue.js ## Some videos - [What is JHipster Lite and why should you care?][devoxx-jhlite] by [Julien Dubois][jdubois] - [Simple WebServices with JHipster Lite][webservices-with-jhlite] by [Colin Damon][cdamon] ## Choosing between JHipster and JHipster Lite The original JHipster and JHLite are **not the same thing**, they are **not generating the same code** and **not serving the same purpose**! Here are some elements you can take into account: ## Discover JHipster Lite Join us on [GitHub][GitHub repository]! You will be able to run your JHipster Lite instance locally. [Hexagonal Architecture]: https://github.com/jhipster/jhipster-lite/blob/main/documentation/hexagonal-architecture.md [GitHub repository]: https://github.com/jhipster/jhipster-lite [Seed4J website]: https://seed4j.com/ [Seed4J repository]: https://github.com/seed4j/seed4j [devoxx-jhlite]: https://youtu.be/RnLGnY-vzLI [jdubois]: https://twitter.com/juliendubois [webservices-with-jhlite]: https://youtu.be/mEECPRZjajI [cdamon]: https://www.linkedin.com/in/colin-damon/ --- ## File: docs/meetups.mdx --- title: JHipster meetups slug: /meetups/ last_update: date: 2017-05-15T00:00:00-00:00 --- We are currently creating JHipster meetups all around the world! - If you want to create your own meetup do a pull request on [this Web page](https://github.com/jhipster/jhipster.github.io/blob/main/pages/meetups.md) to add your meetup directly. - There is no rule for meetups: you can schedule them when you want, let it happen where you want, and invite who you want. - The JHipster team will do its best to support you: we'll RT you on Twitter, put your event on our main page, etc. ## Existing meetups **North America** - [New York, USA - JHipster meetup](https://www.meetup.com/JHipster-NYC/) **Europe** - [Dublin, Ireland - JHipster meetup](https://www.meetup.com/JHipsterDublin/) - [Lyon, France - JHipster meetup](https://www.meetup.com/JHipster-Lyon/) - [Paris, France - JHipster meetup](https://www.meetup.com/JHipster-User-Group/) - [Zurich, Switzerland - JHipster meetup](https://www.meetup.com/JHipster/) **Oceania** - [Melbourne, Australia - JHipster meetup](https://www.meetup.com/fr-FR/jHipster-Melbourne/) **Middle East** - [Dubai, United Arab Emirates - JHipster meetup](https://www.meetup.com/JHipster-Dubai/) **Africa** - [Lagos, Nigeria - JHipster meetup](https://www.meetup.com/JHipster-Nigeria/) ## Meetups being created *Contact the team if you want to help creating one of those meetups* - Amsterdam, Netherlands JHipster meetup - Brussels, Belgium JHipster meetup --- ## File: docs/policies.mdx --- title: Policies displayed_sidebar: docsSidebar slug: /policies/ last_update: date: 2015-07-31T18:40:00-00:00 --- The JHipster development team follows some coding policies. You can see them as "best practices" or "guidelines". They are enforced on the project itself, not on the generated code: if you use JHipster to generate your project, you absolutely do not have to follow them! Those policies are followed by the [development team](/team), and you should follow them if you submit a pull request. ## Policy 0: Policies are voted by the development team Each policy can be discussed or modified by the development team on the [mailing list](https://groups.google.com/forum/?hl=en#!forum/jhipster-dev). Any significant change must be voted (+1 if you agree, -1 if you disagree). ## Policy 1: Technologies used by JHipster have their default configuration and best practices used as much as possible For example, we use JPA, Spring, Angular and React the "usual way", without some heavy configuration options and with their usual naming and coding conventions. We do this as: - Each technology usually has a very good reason to have those defaults - It’s much easier to understand how JHipster works if we don’t re-configure everything We might only change a default configuration if it produces some issue with the other technologies used by JHipster. For example, to have Spring Security and Angular working together, we had to change Spring Security’s default configuration or if the default configuration makes our EJS templates extremely complex ## Policy 2: Only add options/features when there is sufficient added-value in the generated code JHipster has many options when generating a project. We only add those options when they are complex and imply configuring or coding several components. Adding an option only because it saves a couple of lines to code isn't a good usage of JHipster: - It's easier to code those lines manually than to learn a new JHipster option - It will only make our generator more complex without adding any value ## Policy 3: Use strict versions for third-party libraries on server side and client side Only exception is dependencies on our libraries where relative versions work better. We’ve had many issues with library versions making conflicts. This is mostly a JavaScript issue, so to be clear: we use fixed libraries versions in `package.json` files that are generated. ## Policy 4: We provide similar user/developer experience across different options provided for the same purpose as much as possible An important aspect of JHipster is our user and developer experience and the ease with which you can swap one technology to another (ex: Client framework, Authentication, Database, etc) and hence it would be easier for developers if they are configured/coded as similar as possible. We can make exceptions when it violates other policies. ## Policy 5: Developer experience can take precedence over policy 1, 2, 3 & 4 This means that we need to make sure developer experience is not affected by below as much as possible - Feature additions - Hype driven development - Contributor convenience - Technology enthusiasm Developer experience is subjective hence the below can be a rough guide for the JHipster community. It will be the overall experience of using JHipster as a product and a platform. That includes - The JHipster CLI experience (ease of use, intuitiveness, speed etc) - Generated code (quality, simplicity, readability, maintenance ease, upgradability, familiarity etc) - UX of Tools like JHipster online, JDL studio - Docs (Website & generated Readme) When there is a disagreement on enforcement of this policy, there can be a case to case debate and vote on the [mailing list](https://groups.google.com/forum/?hl=en#!forum/jhipster-dev) to resolve it. --- ## File: docs/tech-board.mdx --- title: Technology Advisory Board slug: /tech-board/ last_update: date: 2021-03-31T00:00:00-00:00 --- JHipster is supported by a technical board that ensures the platform continues to reflect and serve its diverse and growing user community. The Board discusses and makes recommendations regarding the roadmap and technical directions. The meetings review and advise on industry trends, market strategy, project strategy and roadmap, ecosystem development. This board helps the project by giving advice and feedback on how the project and the related technologies are going. For the same reason, the board helps target incoming technologies and help to build the future of the project. In the end, this should help the project to raise resources to make those choices real by focusing on specific features, helps on finding new contributors, and advertise on the next project decisions… The decisions and materials produced by the committee are public and used to benefit the community rather than private interests. The board meets quarterly, with the ability to meet more frequently if needed. ## Board Membership Current members: - Julien Dubois (Microsoft) - Deepu K Sasidharan (Okta) - Matt Raible - Paul Hinz - Alina Yurenko (Oracle) The members are chosen by the project leaders and should come from: - representative industry companies and leaders - representative organisations that use JHipster - open-source project leaders - community and technology leaders - people from academia If you are interested to be part of this technical board, please contact us. --- ## File: docs/user-entity.mdx --- title: The User entity slug: /user-entity/ last_update: date: 2020-09-14T00:00:42-00:00 --- :::note This is not created for microservices using some kinds of security, as detailed [here](/creating-microservices). ::: This entity is a special entity as JHipster creates and manages it internally. It contains some basic information: - a first name and a last name, - a login, - an email address, - a password (not in clear text), - authorities, - etc. Creating an application from scratch will generate you some default users like the `admin` or the `guest` users. ## Possible relationships Here are the possible relationships from/to this entity: - `many-to-one` relationships to this entity (a `Car` can have a many-to-one relationship to a `User`). This will generate a specific query in your new entity repository, so you can filter your entity on the current security user, which is a common requirement. On the generated Angular/React client UI you will have a dropdown in `Car` to select a `User`. - `many-to-many` and `one-to-one` relationships to the `User` entity, but the other entity __must__ be the owner of the relationship (a `Team` can have a many-to-many relationship to `User`, but only the team can add/remove users, and a user cannot add/remove a team). On the front-end client UI, you will also be able to select a `User` in a multi-select box. ## Modifying the User entity If you encounter a problem where you need to alter the `User` entity, we recommend not doing that. Modifying this default entity might break your app depending on the nature of the changes. Instead, there are other available solutions like: - creating an entity composed of the `User` entity, - extending the `User` entity ### Using composition If you need to add a new field to the entity, or add relationships to it, all you need do is create another entity, for instance: ```jdl entity ApplicationUser { additionalField Integer min(42) max(42) } relationship OneToOne { ApplicationUser{internalUser(login)} to @OnDelete("CASCADE") @Id User with builtInEntity } ``` Here's what this snippet does: - create a new entity named `ApplicationUser` with a field, - create a relationship from this entity to the standard `User` entity: - we use a `OneToOne` relationship to link a JHipster-created entity to this new one, - we use a unidirectional relationship in order not to modify the internally-managed `User` entity. This is the recommended solution as it's doable using the JDL. This solution is great for adding new fields and relationships (amongst other things) to the `User` entity without actually modifying it. ### Using inheritance This solution does the same thing as the previous one, but isn't as straightforward as the first one because you need to: - create a new entity by hand, - adapt the code to make it use this new entity, - potentially manage yourself the database migration to persist this new entity (depending on the nature of the changes). It possesses, however, the same advantage as the previous one: you needn't change the `User` entity by hand. ### Creating your own default User entity This one isn't actually recommended, but is possible through the use of the user management skipping option (`skipUserManagement` application option in the JDL). JHipster uses this option internally in some cases (for some options), and using it will: - not generate any user management code (front-end & back-end), - allow you to update the `User` entity (add/delete any field to it), Additionally, you'll have to create the entity and handle user management yourself. **It's better to keep it `false` as the first two solutions are quite easy to do**. --- ## File: docs/using-angularjs.mdx --- title: Using AngularJS slug: /using-angularjs/ last_update: date: 2015-01-29T23:41:00-00:00 --- As of JHipster 5, AngularJS is not supported anymore with JHipster. We have great support for [Angular](/using-angular) and [React](/using-react), which are both more modern tools, we hope you will enjoy them! If you still need to use AngularJS 1.x, please have a look at [our archives](https://www.jhipster.tech/documentation-archive/). --- ## File: docs/using-uaa.mdx --- title: Using JHipster UAA for Microservice Security slug: /using-uaa/ last_update: date: 2016-08-25T00:00:00-00:00 --- JHipster UAA is a user accounting and authorizing service for securing JHipster microservices using the OAuth2 authorization protocol. To distinguish JHipster UAA from other "UAA"s such as [Cloudfoundry UAA](https://github.com/cloudfoundry/uaa), JHipster UAA is a fully configured OAuth2 authorization server with the users and roles endpoints inside, wrapped into a usual JHipster application. This allows the developer to deeply configure every aspect of the user domain, without restricting on policies by other ready-to-use UAAs. ## Architecture diagram ## 1. Security claims of microservice architecture Before digging into OAuth2 and its application on JHipster microservices, it's important to clarify the claims to a solid security solution. ### 1. Central authentication Since microservices is about building mostly independent and autonomous applications, we want to have a consistent authentication experience, so the users won't notice their requests are served by different applications with possibly individual security configuration. ### 2. Statelessness The core benefit of building microservices is scalability. So the chosen security solution shouldn't affect this. Holding the users session state on server becomes a tricky task, so a stateless solution is highly preferred in this scenario. ### 3. User/machine access distinction There is a need of having a clear distinction of different users, and also different machines. Using microservice architecture leads to building a large multi-purpose data-center of different domains and resources, so there is a need to restrict different clients, such as native apps, multiple single page applications etc. in their access. ### 4. Fine-grained access control While maintaining centralized roles, there is a need of configuring detailed access control policies in each microservice. A microservice should be unaware of the responsibility of recognizing users, and must authorize incoming requests. ### 5. Safe from attacks No matter how much problems a security solution may solve, it should be strong against vulnerabilities as best as possible. ### 6. Scalability Using stateless protocols is not a warranty of the security solution is scalable. In the end, there should not be any single point of failure. A counter-example is a shared auth database or single auth-server-instance, which is hit once per request. ## 2. Understanding OAuth2 in this context Using the OAuth2 protocol (note: it's a **protocol**, not a framework, not an application) is satisfying all 6 claims. It follows strict standards, what makes this solution compatible to other microservices as well, and remote systems, too. JHipster provides a couple of solutions, based on the following security design: - Every request to any endpoint of the architecture is performed via an "client" - A "client" is an abstract word for things like "Angular $http client", some "REST-Client", "curl", or anything able to perform requests. - A "client" may also be used in conjunction with user authentication, like the Angular $http in the frontend client application - Every microservice serving resources on endpoints (including the UAA), are resource servers - Blue arrows show clients authenticate on an Oauth authorization server - Green arrows show requests on resource servers performed by the client - The UAA server is a combination of authorization server and resource server - The UAA server is the owner of all the data inside the microservice applications (it approves automatically access to resource servers) - Clients accessing resources with user authentication, are authenticated using "password grant" with the client ID and secret safely stored in the gateway configuration files - Clients accessing resources without user, are authenticated using "client credentials grant" - Every client is defined inside UAA (web-app, internal, ...) This design may be applied to any microservice architecture independent from language or framework. As an addition, the following rules can be applied for access control: - User access is configured using "roles" and [RBAC][] - Machines access is configured using "scopes" and [RBAC][] - Complex access configuration is expressed using [ABAC][], using boolean expressions over both "roles" and "scopes" - example: hasRole("ADMIN") and hasScope("shop-manager.read", "shop-manager.write") ## 3. Using JHipster UAA When scaffolding a JHipster microservice, you may choose the UAA options instead of JWT authentication. **Note**: the UAA solution is also using JWT, which are addressable to custom configuration as well as JWT, using default Spring Cloud Security. ### Basic setup The very basic setup consists of: 1. A JHipster UAA server (as type of application) 2. At least one other microservice (using UAA authentication) 3. A JHipster gateway (using UAA authentication) This is the order in which it should be generated. In addition to the authentication type, the location of the UAA must be provided. For very basic usage, this setup is working the same way as it does for JWT authentication type, but with one more service. ### Understanding the components The JHipster UAA server does three things out of the box: - It serves the default JHipster user domain, containing user and account resource (this is done by gateway in JWT authentication) - It implements `AuthorizationServerConfigurerAdapter` for OAuth2 and is defining basic clients ("web_app" and "internal") - It serves the JWT public key on `/oauth/token_key`, which has to be consumed by all other microservices The choices of a database, cache solution, search engine, build tools and further JHipster options are open to the developer. When a microservice boots up, it usually expects the UAA server is already up to share its public key. The service first calls `/oauth/token_key` to fetch the public key and configure it for key signing (`JwtAccessTokenConverter`). If the UAA is not up, the application will continue to start and fetch the public key at a later time. There are two properties - `uaa.signature-verification.ttl` controls how long the key lives before it is fetched again, `uaa.signature-verification.public-key-refresh-rate-limit` limits requests to UAA to avoid spamming it. These values are usually left at their default values. In any case, if verification fails, then the microservice will check if there's a new key. That way, keys can be replaced on the UAA and the services will catch up. From this point there are two use cases that may happen in this basic setup: user calls and machine calls. For the user calls, a login request is sent to the gateway's `/auth/login` endpoint. This endpoint uses `OAuth2TokenEndpointClientAdapter` to send a request to the UAA authenticating with the "password" grant. Because this request happens on the gateway, the client ID and secret are not stored in any client-side code and are inaccessible to users. The gateway returns a new Cookie containing the token, and this cookie is sent with each request performed from the client to the JHipster backend. For the machine calls, the machine has to authenticate as a UAA using client credentials grant. JHipster provides a standard solution, described in [secure inter-service-communication using feign clients](#4-secure-inter-service-communication-using-feign-clients) ### Refresh Tokens The general flow for refreshing access tokens happens on the gateway and is as follows: - Authentication is done via `AuthResource` calling `OAuth2AuthenticationService`'s authenticate which will set Cookies. - For each request, the `RefreshTokenFilter` (installed by `RefreshTokenFilterConfigurer`) checks whether the access token is expired and whether it has a valid refresh token. - If so, then it triggers the refresh process via `OAuth2AuthenticationService` refreshToken. - This uses the `OAuth2TokenEndpointClient` interface to send a refresh token grant to the OAuth2 server of choice, in our case UAA (via `UaaTokenEndpointClient`). - The result of the refresh grant is then used downstream as new cookies and set upstream (to the browser) as new cookies. ### Common mistakes Here is a brief list of the very major things a developer should be aware of. #### **_Using the same signing key for production and staging_** It is strictly recommended to use different signing keys as much as possible. Once a signing key gets into wrong hands, it is possible to generate full access granting key without knowing login credentials of any user. #### **_Not using TLS_** If attackers manage to intercept an access token, they will gain all the rights authorized to this token, until the token expires. There are a lot of ways to achieve that, in particular when there is no TLS encryption. This was not a problem in the days of version 1 of OAuth, because protocol level encryption was forced. #### **_Using access tokens in URL_** As of standard, access tokens can be either passed by URL, in headers, or in a cookie. From the TLS point of view, all three ways are secure. In practice passing tokens via URL is less secure, since there several ways of getting the URL from records. #### **_Switching to symmetric signing keys_** RSA is not required for JWT signing, and Spring Security does provide symmetric token signing as well. This also solves some problems, which make development harder. But this is insecure, since an attacker needs to get into one single microservice to be able to generate its own JWT tokens. ## 4. Secure inter-service-communication using Feign clients Currently only JHipster UAA is providing an scalable approach of secure inter-service-communication. Using JWT authentication without manually forwarding JWTs from request to internal request forces microservices to call other microservices over the gateway, which involves additional internal requests per one master requests. But even with forwarding, it's not possible to cleanly separate user and machine authentication. Since JHipster UAA is based on OAuth2, all these problems are solved on protocol definition. This chapter covers how to get started with this. ### Using Eureka, Ribbon, Hystrix and Feign When one service wants to request data from another, finally all these four players come into play. So it is important, to briefly know what each of them is responsible for: - Eureka: this is where services (un-)register, so you can ask "foo-service" and get a set of IPs of instances of the foo-service, registered in Eureka. - Ribbon: when someone asked for "foo-service" and already retrieved a set of IPs, Ribbon does the load balancing over these IPs. So to sum up, when we got a URL like "http://uaa/oauth/token/" with 2 instances of JHipster UAA server running on 10.10.10.1:9999 and 10.10.10.2:9999, we may use Eureka and Ribbon to quickly transform that URL either to "http://10.10.10.1:9999/oauth/token" or "http://10.10.10.2:9999/oauth/token" using a Round Robin algorithm. - Hystrix: a circuit breaker system solving fall-back scenarios on service fails - Feign: using all that in a declarative style In real world, there is no warranty of all instances of all services to be up. So Hystrix works as a circuit breaker, to handle failure scenarios in a well-defined way, using fallbacks. But wiring and coding all these things manually is a lot of work: Feign provides the option of writing **_Ribbon_** load balanced REST clients for endpoints registered in **_Eureka_**, with fallback implementations controlled using **_Hystrix_**, using nothing more then an Java interfaces with some annotations. So for inter-service-communication, Feign clients are very helpful. When one service needs a REST client to access an "other-service", serving some "other-resource", it's possible to declare an interface like: ```java @FeignClient(name = "other-service") interface OtherServiceClient { @RequestMapping(value = "/api/other-resources") List getResourcesFromOtherService(); } ``` And then, using it via dependency injection, like: ```java @Service class SomeService { private OtherServiceClient otherServiceClient; @Inject public SomeService(OtherServiceClient otherServiceClient) { this.otherServiceClient = otherServiceClient; } } ``` Similar to Spring Data JPA, there is no need to implement that interface. But you may do so, if using Hystrix. Implemented classes of Feign client interfaces act as fallback implementations. One open issue is, to make this communication secure using UAA. To accomplish this, there should be some request interceptor for Feign, which implements the client credentials flow from OAuth, to authorize the current service for requesting the other service. In JHipster, you use `@AuthorizedFeignClients` instead. This is an annotation provided by JHipster, which does exactly that. ### Using `@AuthorizedFeignClients` Considering the above Feign client should be used to an "other-service", which serves protected resources, the interface must be annotated like this: ```java @AuthorizedFeignClient(name = "other-service") interface OtherServiceClient { @RequestMapping(value = "/api/other-resources") List getResourcesFromOtherService(); } ``` **note**: Due to a bug in Spring Cloud, it's currently not possible to use a different notation for the service name, as ```java @AuthorizedFeignClient("other-service") ``` or ```java @AuthorizedFeignClient(value = "other-service") ``` The REST client automatically gets authorized with your UAA server, when there is no valid access token stored in memory. This approach addresses a scenario when machine request run over a separate OAuth client not referring to an user session. This is important, in particular when entity auditing is used on a request, issued by another request in another service. As an alternative, the access token of the initial request may be forwarded to further calls. Currently, there is no "default solution" provided by JHipster. ## 5. Testing UAA applications ### Mocking Feign clients Components working with Feign clients should be testable. Using Feign in tests the same way it is used in production would force the JHipster Registry and the UAA server to be up and reachable to the same machine where the tests are run. But in most cases, you don't want to test that Feign itself works (it usually does), but your components using Feign clients. To test components, which are using feign clients inside is possible using `@MockBean`, which is part of spring boot since 1.4.0. Here is an example, testing `SomeService` works as expected, with mocked values for the client: ```java @RunWith(SpringRunner.class) @SpringBootTest(App.class) public class SomeServiceTest { @MockBean private OtherServiceClient otherServiceClient; @Inject private SomeService someService; @Test public void testSomeService() { given(otherServiceClient.getResourcesFromOtherService()) .willReturn(Arrays.asList(new OtherResource(...)); someService.performActionWhichInkvokesTheAboveMentionedMethod(); //assert that your application is in the desired state } } ``` So with this technology you are simulating the behavior of the other service, and provide expected resource entity, which would come from the origin. All Beans injecting a client will behave as mocked, so you can focus on the logic of these Beans. ### Emulating OAuth2 authentication Using Spring's integration tests against the REST controllers is usually bypassing the security configuration, since it would make testing hard, when the only intention is to prove the controller is functional doing what it should do. But sometimes, testing a controller's security behavior is part of testing, too. For this use-case, JHipster is providing an component called `OAuth2TokenMockUtil`, which can emulate a valid authentication without forcing the user or client to exist. To use this feature, two things have to be done: #### 1. Enabling security in the mock Spring MVC context and inject the mock util ```java @Inject private OAuth2TokenMockUtil tokenUtil; @PostConstruct public void setup() { this.restMockMvc = MockMvcBuilders .webAppContextSetup(context) .apply(springSecurity()) .build(); } ``` **_In this test no single instance of the controller has to be mocked, but the application's `WebApplicationContext`_** #### 2. Using the `OAuth2TokenMockUtil` The util offers a method "oaut2authentication", which is usable to MockMvc "with" notation. Currently it can be configured to mock a authentication with the following fields: - username - roles (Set\) - scope (Set\) Here is an example: ```java @Test public void testInsufficientRoles() { restMockMvc.peform( get("url/requiring/ADMIN/role") .with(tokenUtil.oauth2Authentication("unpriveleged.user@example.com", Sets.newSet("some-scope"), Sets.newSet("ROLE_USER"))) ).andExpect(status().isForbidden()); } ``` [RBAC]: https://de.wikipedia.org/wiki/Role_Based_Access_Control [ABAC]: https://en.wikipedia.org/wiki/Attribute-Based_Access_Control --- ## File: docs/about/companies-using-jhipster.mdx --- title: Companies using JHipster slug: /companies-using-jhipster/ hide_table_of_contents: true last_update: date: 2015-12-10T00:00:00-00:00 --- import WhoUsesWithSearch from '@site/src/components/sections/docs/WhoUsesWithSearch' JHipster has got a [lot of downloads](https://npmcharts.com/compare/generator-jhipster), and as it's Open Source it's impossible to have a complete list of who uses it. We have made this list from what people tell us, and from resources available on the Internet (conferences, GitHub tickets, StackOverflow questions). If you want to add a company to the list, please [Fill up this form](https://docs.google.com/forms/d/1-Ut-U2NtOAcT9yEZcETnxsxMAsyS-DkBK9zlXLGW1zs). --- ## File: docs/about/screenshots.mdx --- title: Screenshots of the generated application slug: /screenshots/ last_update: date: 2014-02-17T00:00:00-00:00 --- ## The welcome screen ## The monitoring screen ## One of the generated forms ## The log management screen ## The generated "Book" entity --- ## File: docs/about/showcase.mdx --- title: Showcase hide_table_of_contents: true slug: /showcase/ last_update: date: 2020-06-12T00:00:00-00:00 --- import Showcase from '@site/src/components/sections/docs/Showcase' A showcase of awesome applications built with JHipster. If you want your application to be featured here submit a PR to the [website](https://github.com/jhipster/jhipster.github.io) or let us know via Twitter by mentioning the [@jhipster](https://twitter.com/jhipster) handle. --- ## File: docs/about/tech-stack.mdx --- title: Technology stack slug: /tech-stack/ last_update: date: 2021-03-08T12:00:00-00:00 --- ## Technology stack on the client side Single Web page application: * [Angular](https://angular.io/) or [React](https://reactjs.org/) or [Vue](https://vuejs.org/) * Responsive Web Design with [Twitter Bootstrap](http://getbootstrap.com/) * [HTML5 Boilerplate](http://html5boilerplate.com/) * Compatible with modern browsers (Chrome, FireFox, Microsoft Edge...) * Full internationalization support * Optional [Sass](https://www.npmjs.com/package/node-sass) support for CSS design * Optional WebSocket support with Spring Websocket With the great development workflow: * Installation of new JavaScript libraries with [NPM](https://www.npmjs.com/get-npm) * Build, optimization and live reload with [Webpack](https://webpack.js.org/) * Testing with [Jest](https://facebook.github.io/jest/) and [Protractor](http://www.protractortest.org) And what if a single Web page application isn't enough for your needs? * Support for the [Thymeleaf](http://www.thymeleaf.org/) template engine, to generate Web pages on the server side ## Technology stack on the server side A complete [Spring application](http://spring.io/): * [Spring Boot](http://projects.spring.io/spring-boot/) for application configuration * [Maven](http://maven.apache.org/) or [Gradle](http://www.gradle.org/) configuration for building, testing and running the application * ["development" and "production" profiles](/profiles) (both for Maven and Gradle) * [Spring Security](http://docs.spring.io/spring-security/site/index.html) * [Spring MVC REST](http://spring.io/guides/gs/rest-service/) + [Jackson](https://github.com/FasterXML/jackson) * Optional WebSocket support with Spring Websocket * [Spring Data JPA](http://projects.spring.io/spring-data-jpa/) + Bean Validation * Database updates with [Liquibase](http://www.liquibase.org/) * [Elasticsearch](https://github.com/elastic/elasticsearch) support if you want to have search capabilities on top of your database * [MongoDB](http://www.mongodb.org) and [Couchbase](https://www.couchbase.com) support if you'd rather use a document-oriented NoSQL database instead of JPA * [Cassandra](http://cassandra.apache.org/) support if you'd rather use a column-oriented NoSQL database instead of JPA * [Kafka](http://kafka.apache.org/) and [Pulsar](http://pulsar.apache.org/) support if you want to use a publish-subscribe messaging system ## Technology stack for microservices Microservices are optional, and fully supported: * HTTP routing using [Spring Cloud Gateway](https://github.com/spring-cloud/spring-cloud-gateway) * Service discovery using [HashiCorp Consul](https://www.consul.io/) or [Netflix Eureka](https://github.com/Netflix/eureka) ## Ready to go into production: * Monitoring with [Metrics](http://metrics.dropwizard.io/) and [the ELK Stack](https://www.elastic.co/products) * Caching with [ehcache](http://ehcache.org/) (local cache), [Caffeine](https://github.com/ben-manes/caffeine) (local cache), [Hazelcast](http://www.hazelcast.com/), [Infinispan](http://infinispan.org/), [Memcached](https://memcached.org/) or [Redis](https://redis.io/) * Optimized static resources (gzip filter, HTTP cache headers) * Log management with [Logback](http://logback.qos.ch/), configurable at runtime * Connection pooling with [HikariCP](https://github.com/brettwooldridge/HikariCP) for optimum performance * Builds a standard WAR file or an executable JAR file * Full Docker and Docker Compose support * Support for all major cloud providers: AWS, GCP, Heroku, Kubernetes, OpenShift, Azure, Docker... --- ## File: docs/about/video-tutorial.mdx --- title: Video tutorial hide_table_of_contents: true slug: /video-tutorial/ last_update: date: 2014-10-18T00:00:00-00:00 --- import VideoTutorial from '@site/src/components/sections/docs/VideoTutorial' --- ## File: docs/blueprints/quarkus/creating-an-application.mdx --- title: Creating an application slug: /blueprints/quarkus/002_creating_an_application.html last_update: date: 2021-01-07T08:40:00-00:00 --- ## Quick start First of all, create an empty directory in which you will create your application: `mkdir my-quarkus-application` Go to that directory: `cd my-quarkus-application` To generate your JHipster Quarkus application, type: `jhipster-quarkus` ## Advanced `jhipster-quarkus` embeds the `jhipster` dependency which means you don’t have to install `jhipster` by your own. The main benefits of `jhipster-quarkus` is to ensure the compatibility between the JHipster Quarkus blueprint and the underneath JHipster. However, if you want to use a custom `jhipster` installation, you can use the `--blueprint` flag as follow: `jhipster --blueprints quarkus` Please, keep in mind that in this configuration you may face compatibility issues, that’s why we do not recommend this usage. ## Questions asked when generating an application The question asked during JHipster Quarkus creation are identical to standard Quarkus. Please refer to the according documentation: [Questions asked when generating an application](/creating-an-app/#questions-asked-when-generating-an-application) --- ## File: docs/blueprints/quarkus/creating-an-entity.mdx --- title: Creating an entity slug: /blueprints/quarkus/003_creating_an_entity.html last_update: date: 2021-01-07T08:40:00-00:00 --- ## Introduction JHipster Quarkus entity creations permits to generate - A database table - A Liquibase change set - A JPA Entity - A Quarkus Panache Active Record or Repository - A Resteasy Controller, which has the basic CRUD operations - Data Transfer Objects (DTOs) - Pagination - Tests and delegates to JHipster the client side components generation ## Example ``` $ jhipster-quarkus entity Book INFO! Using JHipster version installed locally in current project's node_modules INFO! No custom sharedOptions found within blueprint: generator-jhipster-quarkus at /Users/daniel/workspace/jhipster/jhipster-eleven/node_modules/generator-jhipster-quarkus INFO! No custom commands found within blueprint: generator-jhipster-quarkus at /Users/daniel/workspace/jhipster/jhipster-eleven/node_modules/generator-jhipster-quarkus INFO! Executing jhipster:entity Book info Using blueprint generator-jhipster-quarkus for entity subgenerator The entity Book is being created. Generating field #1 ? Do you want to add a field to your entity? Yes ? What is the name of your field? isbn ? What is the type of your field? String ? Do you want to add validation rules to your field? Yes ? Which validation rules do you want to add? Required ================= Book ================= Fields isbn (String) required Generating field #2 ? Do you want to add a field to your entity? No ================= Book ================= Fields isbn (String) required Generating relationships to other entities ? Do you want to add a relationship to another entity? No ================= Book ================= Fields isbn (String) required ? Do you want to use separate repository class for your data access? No, the Entity will be used as an Active Record ? Do you want to use separate service class for your business logic? No, the REST controller should use the active record/repository directly ? Do you want pagination on your entity? Yes, with pagination links Everything is configured, generating the entity... ``` ## JHipster UML and JDL Studio JHipster Quarkus supports JDL imports. Refer to the according JHipster UML and JDL Studio section in the [creating-an-entity](/creating-an-entity) tutorial. --- ## File: docs/blueprints/quarkus/index.mdx --- title: Quarkus slug: /blueprints/quarkus/ last_update: date: 2021-01-07T08:40:00-00:00 --- [JHipster Quarkus blueprint](https://github.com/jhipster/generator-jhipster-quarkus) to leverage JHipster to create a [Quarkus](https://quarkus.io/) application. The following documentation will focus only the differences between JHipster Quarkus and the main JHipster generator. For common aspects, please refer to the standard JHipster’s documentation. - [Installing JHipster Quarkus Blueprint](/blueprints/quarkus/001_installing_jhipster_quarkus.html) - [Creating an application](/blueprints/quarkus/002_creating_an_application.html) - [Creating an entity](/blueprints/quarkus/003_creating_an_entity.html) --- ## File: docs/blueprints/quarkus/installing-jhipster-quarkus.mdx --- title: Installing JHipster Quarkus slug: /blueprints/quarkus/001_installing_jhipster_quarkus.html last_update: date: 2021-01-07T08:40:00-00:00 --- Before using JHipster Quarkus, you have to prepare your environment (Java, Node) and install JHipster. Please refer to the section Local installation with NPM (recommended for normal users) of the documentation https://www.jhipster.tech/installation/. You can now install the JHipster Quarkus blueprint: `npm install generator-jhipster-quarkus` You can validate the installation by checking the presence of the `jhipster-quarkus` command: `which jhipster-quarkus` (for Mac/Linux). You’re done. You can now start creating Quarkus applications with JHipster. --- ## File: docs/contributing/contributing-companies.mdx --- title: Contributing Companies slug: /contributing-companies/ last_update: date: 2017-11-29T00:00:00-00:00 --- ## Companies contributing to JHipster * [Microsoft](https://www.microsoft.com/), which provides time and hardware to [@juliendubois](https://x.com/juliendubois) to improve the project. * [Okta](https://developer.okta.com/) contributed time and hardware to [@mraible](https://x.com/mraible) to improve the project. They also contributed the [OIDC support](/security/#oauth-20-and-openid-connect) and [Ionic blueprint](/modules/marketplace/details/generator-jhipster-ionic/). * [Google](https://google.com) contributed the [Kubernetes sub-generator](/kubernetes/). It is maintained by [Ray Tsang](https://x.com/saturnism). * [Heroku](https://www.heroku.com/) contributed the [Heroku sub-generator](/heroku/). It is maintained by [Joe Kutner](https://x.com/codefinger). * [CloudCaptain](https://cloudcaptain.sh/) has added [specific support for JHipster](/cloudcaptain/). It is maintained by [Axel Fontaine](https://x.com/axelfontaine). * [Software AG](http://www.softwareag.com/), which sponsors Ehcache, contributed to greatly improve our Ehcache support. * [Hazelcast](https://hazelcast.com/) contributed to greatly improve our Hazelcast support. * [Liquibase](http://www.liquibase.com/) has continuously helped us and corrected bugs for our Liquibase support. * [Redhat](https://www.redhat.com/en) contributed the Openshift sub-generator and Infinispan support. * [JFrog](https://jfrog.com/) which provides us with a free Artifactory instance, which is used for our builds and our releases. ## Companies helping to develop JHipster These companies help us to develop JHipster * [Google](https://google.com), which has given the project $7,000 worth of "Google cloud credits" since 2016. * Pivotal, which gives us free credits on their [Pivotal Web Services](http://run.pivotal.io/) cloud. * [ElephantSQL](http://www.elephantsql.com/), which gives us several of their "Pretty Panda" Postgresql databases. * YourKit, LLC, which gives us free licenses for the [YourKit Java profiler](http://www.yourkit.com/java/profiler/index.jsp). * EJ Technologies, which gives us free licenses for the [JProfiler Java profiler](http://www.ej-technologies.com/products/jprofiler/overview.html). ## Projects and communities contributing to JHipster JHipster works closely with other OSS communities, which often contributes code, advice and reviews to the project. Important contributions have been made by: * [Webpack](https://webpack.github.io/), the module bundler that JHipster uses for its Angular and React support. * [Gradle](https://gradle.org/), one of the build tools supported by JHipster. * [Angular](https://angular.io/). * [UI Router](https://ui-router.github.io/), the Angular router used until JHipster 4. ## Special thanks And a very special thanks to the development team from [Galeries Lafayette](http://www.galerieslafayette.com/), which had the original idea of making Grunt work with Ant, and create a modern Web front-end on top of a more classical Spring MVC application. --- ## File: docs/contributing/contributing-individuals.mdx --- title: Individual contributions slug: /contributing-individuals/ last_update: date: 2017-11-29T00:00:00-00:00 --- JHipster has a lot of [contributors](https://github.com/jhipster/generator-jhipster/graphs/contributors), and we make our best to help people contribute! We'd love to have you on board! ## Code of conduct Before you contribute, please read our [Code of Conduct](https://github.com/jhipster/generator-jhipster/blob/main/CODE_OF_CONDUCT.md). ## Reaching for help As anybody on the project, you can reach for help using our usual support channels, as listed on our [Help page](/help). Whatever you do, the team will do its best to help you by: - Commenting your tickets - Reviewing your pull requests ## How to contribute Our [Contributing guide](https://github.com/jhipster/generator-jhipster/blob/main/CONTRIBUTING.md) should give you all the pointers to get started and do your first pull request. --- ## File: docs/contributing/sponsors.mdx --- title: Sponsors slug: /sponsors/ last_update: date: 2025-02-01T00:00:00-00:00 --- JHipster uses [Open Collective](https://opencollective.com/generator-jhipster) to gather money. This money is used to cover project expenses (like running this website) in a transparent way ([See the Open Collective documentation](https://opencollective.com/how-it-works)), and your donation will help the project live and grow successfully. Please go to our [Open Collective page](https://opencollective.com/generator-jhipster) to become a backer or a sponsor. ## Disclaimer This is a donation. No goods or services are expected in return. Any requests for refunds for those purposes will be rejected. We are a French non-profit organization, as described in our [status](/association/), and we're not interested in business partnerships. ## Benefits of being a backer Backers donate $2 per month to the project. We use the Open Collective APIs to automatically display backers on our main page: - On the front page of [https://www.jhipster.tech](https://www.jhipster.tech) in the "backers" section (about 110,000 views/month). - On the GitHub main project page in the "backers" section (about 15,000 views/month). ## Benefits of being a bronze sponsor Bronze sponsors donate $100 per month to the project. We use the Open Collective APIs to automatically display bronze sponsors on our main page: - On the front page of [https://www.jhipster.tech](https://www.jhipster.tech) in the "sponsors" section (about 110,000 views/month). - On the GitHub main project page in the "sponsors" section (about 15,000 views/month). ## Benefits of being a silver sponsor There is a limit to 10 silver sponsors. Silver sponsors donate $500 per month to the project. We use the Open Collective APIs to automatically display silver sponsors on our main page: - On the front page of [https://www.jhipster.tech](https://www.jhipster.tech) in the "sponsors" section (about 110,000 views/month). - On the GitHub main project page in the "sponsors" section (about 15,000 views/month). ## Benefits of being a gold sponsor There is a limit to 3 gold sponsors. Gold sponsors donate $1,000 per month to the project. We use the Open Collective APIs to automatically display gold sponsors on our main page: - On the front page of [https://www.jhipster.tech](https://www.jhipster.tech) in the "sponsors" section (about 110,000 views/month). - On the GitHub main project page in the "sponsors" section (about 15,000 views/month). ## Benefits of being a platinum sponsor There is a limit to only 1 platinum sponsor. Platinum sponsors donate $2,500 per month to the project. We use the Open Collective APIs to automatically display platinum sponsors on our main page: - On the front page of [https://www.jhipster.tech](https://www.jhipster.tech) in the "sponsors" section (about 110,000 views/month). - On the GitHub main project page in the "sponsors" section (about 15,000 views/month). ## What will the project do with the money? As you can read in [the Open Collective documentation](https://docs.opencollective.com), the way your money will be used will be public and totally transparent. Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed. Money will first be used to cover direct project costs: - [Bug bounties](/bug-bounties) - Website hosting - Developer tooling - Legal protection Then, money will be used to: - Pay for project goodies - Pay Meetup fees - Pay expenses for developer gatherings: travel & food expenses for core team meetings ## Help! I'm a sponsor and my logo doesn't appear! For each sponsorship level, we use the Open Collective APIs to automatically display sponsors on our main page. So if your logo doesn't appear: - Check that you selected a correct sponsorship tier. This needs to be one of the tiers listed above, not a custom contribution. - Check your Open Collective profile to ensure that your logo is uploaded: this is what we'll use to automatically display your logo on our main page. - Wait a few minutes: the Open Collective APIs are cached, so it might take a few minutes for your logo to appear. If those steps don't work, please contact Open Collective support, as we don't have control over their APIs. They might have a bug or a technical issue that they need to fix. And please remember the disclaimer at the top of this page: "This is a donation. No goods or services are expected in return. Any requests for refunds for those purposes will be rejected.". --- ## File: docs/core-tasks/creating-an-app.mdx --- title: Creating an application slug: /creating-an-app/ last_update: date: 2018-03-18T18:20:00-00:00 --- _**Please check our [video tutorial](/video-tutorial/) on creating a new JHipster application!**_ ## Quick start First of all, create an empty directory in which you will create your application: `mkdir myapplication` Go to that directory: `cd myapplication/` To generate your application, type: `jhipster` Answer the questions asked by the generator to create an application tailored to your needs. Those options are described in [the next section](#questions-asked-when-generating-an-application). Once the application is generated, you can launch it using Maven (`./mvnw` on Linux/MacOS/Windows PowerShell, `mvnw` on Windows Cmd) or Gradle (`./gradlew` on Linux/MacOS/Windows PowerShell, `gradlew` on Windows Cmd). :::note If you are using Maven and changed front end files after first run of the `./mvnw` command then you must run `./mvnw -Pwebapp` to see the latest front end version (Gradle detects front end changes automatically and recompiles front end if needed). ::: The application will be available on [http://localhost:8080](http://localhost:8080) :::warning If you want to have "live reload" of your JavaScript/TypeScript code, you will need run `npm start`. You can go to the [Using JHipster in development](/development/) page for more information. ::: If you are using "live reload" then you can speed up server start up by excluding client side tasks by `./mvnw -P-webapp` or `./gradlew -x webapp`. It speeds up especially Gradle. ## Questions asked when generating an application _Some questions change depending on the previous choices you have made. For example, you won't need to configure an Hibernate cache if you didn't select an SQL database._ ### Which _type_ of application would you like to create? Your type of application depends on whether you wish to use a microservices architecture or not. A full explanation on microservices is [available here](/microservices-architecture/), if unsure use the default "Monolithic application". You can either use: * Monolithic application: this a classical, one-size-fits-all application. It's easier to use and develop, and is our recommended default. * Microservice application: in a microservices architecture, this is one of the services. * Microservice gateway: in a microservices architecture, this is an edge server that routes and secures requests. ### What is the base name of your application? This is the name of your application. ### What is your default Java package name? Your Java application will use this as its root package. This value is stored by Yeoman so that the next time you run the generator the last value will become default. You can override it by providing a new value. ### Which _type_ of authentication would you like to use? Here are all the possible options: * JWT authentication: use a [JSON Web Token (JWT)](https://jwt.io/), which is the default choice and what most people use. * OAuth 2.0 / OIDC Authentication: this uses an OpenID Connect server, like [Keycloak](https://www.keycloak.org/), [Auth0](https://developer.auth0.com), or [Okta](https://developer.okta.com), which handles authentication outside the application. This is more secured than JWT, but it requires to set up an OpenID Connect server, so it's a bit more complex. Please note that by default JHipster will synchronize the user data from the OpenID Connect server, and for this it will need a database. * HTTP Session Authentication: the classical session-based authentication mechanism, which is what people usually do with [Spring Security](http://docs.spring.io/spring-security/site/index.html). You can find more information on our [securing your application](/security/) page. ### Which _type_ of database would you like to use? You can choose between: - An SQL database (H2, MySQL, MariaDB, PostgreSQL, MSSQL, Oracle), which you will access with Spring Data JPA - [MongoDB](/using-mongodb/) - [Cassandra](/using-cassandra/) - [Couchbase](/using-couchbase/) - [Neo4j](/using-neo4j/) - No database (only available when using a [microservice application](/microservices-architecture/) with JWT authentication) ### Which _production_ database would you like to use? This is the database you will use with your "production" profile. To configure it, please modify your `src/main/resources/config/application-prod.yml` file. If you want to use Oracle, you might need to be aware of current limitations when [using Oracle database](/using-oracle/). ### Which _development_ database would you like to use? This is the database you will use with your "development" profile. You can either use: * H2, running in-memory. This is the easiest way to use JHipster, but your data will be lost when you restart your server. * H2, with its data stored on disk. This is a better option than running in-memory, as you won't lose your data upon application restart. * The same database as the one you chose for production: it's a bit more complex to set up, but it should be better in the end to work on the same database as the one you will use in production. This is also the best way to use liquibase-hibernate as described in [the development guide](/development/). To configure it, please modify your `src/main/resources/config/application-dev.yml` file. ### Do you want to use the Spring cache abstraction? The Spring cache abstraction allows to use different cache implementations: you can use [ehcache](http://ehcache.org/) (local cache), [Caffeine](https://github.com/ben-manes/caffeine) (local cache), [Hazelcast](http://www.hazelcast.com/) (distributed cache), [Infinispan](http://infinispan.org/) (distributed cache), [Memcached](https://memcached.org/) (another distributed cache) or [Redis](https://redis.io/) (configured as a single server cache). This can have a very positive impact on your application's performance, and hence it is a recommended option. ### Do you want to use Hibernate 2nd level cache? This option will only be available if you selected to use an SQL database (as JHipster will use Spring Data JPA to access it) and selected a cache provider in the previous question. [Hibernate](http://hibernate.org/) is the JPA provider used by JHipster, and it can use a cache provider to greatly improve its performance. As a result, we highly recommend you to use this option, and to tune your cache implementation according to your application's needs. ### Would you like to use Maven or Gradle? You can build your generated Java application either with [Maven](http://maven.apache.org/) or [Gradle](http://www.gradle.org/). Maven is more stable and more mature. Gradle is more flexible, easier to extend, and more hype. ### Which other technologies would you like to use? This is a multi-select answer, to add one or several other technologies to the application. Available technologies are: #### API first development using swagger-codegen This option lets you do [API-first development](/doing-api-first-development) for your application by integrating the [Swagger-Codegen](https://github.com/swagger-api/swagger-codegen) into the build. #### Search engine using ElasticSearch [Elasticsearch](https://github.com/elastic/elasticsearch) will be configured using Spring Data Elasticsearch. You can find more information on our [Elasticsearch guide](/using-elasticsearch/). #### Clustered HTTP sessions using Hazelcast By default, JHipster uses a HTTP session only for storing [Spring Security](http://docs.spring.io/spring-security/site/index.html)'s authentication and authorisation information. You can choose to put more data in your HTTP sessions. Using HTTP sessions will cause issues if you are running in a cluster, especially if you don't use a load balancer with "sticky sessions". If you want to replicate your sessions inside your cluster, choose this option to have [Hazelcast](http://www.hazelcast.com/) configured. #### WebSockets using Spring Websocket Websockets can be enabled using Spring Websocket. We also provide a complete sample to show you how to use the framework efficiently. #### Asynchronous messages using Apache Kafka Use [Apache Kafka](/using-kafka/) as a publish/subscribe message broker. #### Asynchronous messages using Apache Pulsar Use [Apache Pulsar](/using-pulsar/) as a publish/subscribe message broker. ### Which _Framework_ would you like to use for the client? The client-side framework to use. You can either use: * Angular * React * Vue ### Would you like to use a Bootswatch theme? The client theme to use. You can use any themes from [Bootswatch](https://bootswatch.com/) or keep the default one. ### Would you like to use the Sass stylesheet preprocessor for your CSS? [Sass](https://sass-lang.com/) a great solution to simplify designing CSS. To be used efficiently, you will need to run a [Webpack](https://webpack.js.org) dev server, which will be configured automatically. ### Would you like to enable internationalization support? By default JHipster provides excellent internationalization support, both on the client side and on the server side. However, internationalization adds a little overhead, and is a little bit more complex to manage, so you can choose not to install this feature. Please note that JHipster covers only UI internationalization. For data internationalization, you will need to code it yourself in JPA/Hibernate layer. ### Which testing frameworks would you like to use? By default JHipster provide Java unit/integration testing (using Spring's JUnit support) and JavaScript unit testing (using Jest). As an option, you can also add support for: * Performance tests using Gatling * Behaviour tests using Cucumber * Angular integration tests with Protractor You can find more information on our ["Running tests" guide](/running-tests/). ### Would you like to use incremental Liquibase changelogs? JHipster optionally creates incremental changelogs for you, so you don't need to recreate the database or to manually generate Liquibase diff. Run JHipster using `--incremental-changelog` option anytime to enable it. When executing JHipster, entities contain two states: * The old state which is already saved to disk * The new state, which is in the memory (generated from jdl or prompts) A diff is generated between them and changelogs are created. Supported features: * Create/remove fields * Create/remove relationships * JDL and prompts Doesn't support attribute changes like type and constraints. Conflicts with: * `--fork` option, since it saves to disk overriding the old state. ### Would you like to install other generators from the JHipster Marketplace? The [JHipster Marketplace](/modules/marketplace/) is where you can install additional modules, written by third-party developers, to add non-official features to your project. ## Using a blueprint JHipster 5 introduces the concept of a blueprint. Blueprints are JHipster modules that can provide custom client/server side templates that will override the ones from JHipster. For example, the [Kotlin blueprint](https://github.com/jhipster/jhipster-kotlin) replaces most of the Java server side code with Kotlin. For example, to use the Kotlin blueprint pass the name of the blueprint like below while generating an app. ```bash jhipster --blueprint kotlin ``` The name of the blueprint is saved in the `.yo-rc.json` and will be automatically used while executing sub-generators like `entity`, `spring-controller` and `spring-service`. If a blueprint doesn't implement a specific sub-generator, it will be skipped and the JHipster templates for the same sub-generator will be used. **Note:** An application can use only one blueprint, multiple blueprints are not supported yet. ## Command-line options You can also run JHipster with some optional command-line options. Reference for those options can be found by typing `jhipster app --help`. Here are the options you can pass: * `--help` - Print the generator's options and usage * `--blueprint` - Specify a blueprint to use. For example `jhipster --blueprint kotlin` * `--skip-cache` - Do not remember prompt answers (Default: false) * `--skip-git` - Do not add the generated project to Git automatically (Default: false) * `--skip-install` - Do not automatically install dependencies (Default: false) * `--skip-client` - Skip the client-side application generation, so you only have the Spring Boot back-end code generated (Default: false). * `--skip-server` - Skip the server-side application generation, so you only have the front-end code generated (Default: false). * `--skip-user-management` - Skip the user management generation, both on the back-end and on the front-end (Default: false) * `--i18n` - Disable or enable i18n when skipping client side generation, has no effect otherwise (Default: true) * `--auth` - Specify the authentication type when skipping server side generation, has no effect otherwise but mandatory when using `skip-server` * `--db` - Specify the database when skipping server side generation, has no effect otherwise but mandatory when using `skip-server` * `--skip-checks` - Skip the check of the required tools (Default: false) * `--jhi-prefix` - Add prefix before services, components and state/route names (Default: jhi) * `--entity-suffix` - Add suffix after entities class names (Default: empty string) * `--dto-suffix` - Add suffix after DTOs class names (Default: DTO) * `--prettier-java` - Use [prettier-java](https://github.com/jhipster/prettier-java) for formatting all Java classes (Default: false) * `--experimental` - Enable experimental features. Please note that these features may be unstable and may undergo breaking changes at any time * `--skip-fake-data` - Skip generation of fake data for development * `--creation-timestamp` - Set a timestamp for reproducible build. Timestamp should be a parsable js date ex: 2019-01-01. Must be used with --with-entities or import-jdl (generator-jhipster > 6.5.1) ## Tips You can also use the Yeoman command-line options, like `--force` to automatically overwrite existing files. So if you want to regenerate your whole application, including its entities, you can run `jhipster --force`. --- ## File: docs/core-tasks/creating-an-entity.mdx --- title: Creating an entity slug: /creating-an-entity/ last_update: date: 2018-09-04T00:00:00-00:00 --- _**Please check our [video tutorial](/video-tutorial) on creating a new JHipster application!**_ :::warning If you want to have "live reload" of your JavaScript/TypeScript code, you will need to run `npm start`. You can go to the [Using JHipster in development](/development/) page for more information. ::: ## Introduction Once you have created your application, you will want to create _entities_. For example, you might want to create an _Author_ and a _Book_ entity. For each entity, you will need: * A database table * A Liquibase change set * A JPA Entity * A Spring Data JPA Repository * A Spring MVC REST Controller, which has the basic CRUD operations * An Angular router, a component and a service * An HTML view * Integration tests, to validate everything works as expected * Performance tests, to see if everything works smoothly If you have several entities, you will likely want to have relationships between them. For this, you will need: * A database foreign key * Specific JavaScript and HTML code for managing this relationship The "entity" sub-generator will create all the necessary files, and provide a CRUD front-end for each entity (see [Angular project structure](/using-angular/) and [React project structure](/using-react/)). The sub generator can be invoked by running `jhipster entity --[options]`. Reference for those options can be found by typing `jhipster entity --help` Below are the supported options. * `--table-name ` - By default JHipster will generate a table name based on your entity name, if you would like to have a different table name you can do so by passing this option. * `--angular-suffix ` - If you want all your Angular routes to have a custom suffix you can pass that using this option. * `--client-root-folder ` - Use a root folder name for entities on the client side. By default it's empty for monoliths and the name of the microservice for gateways. * `--regenerate` - This will regenerate an existing entity without asking any questions. * `--skip-server` - This will skip the server-side code and will generate only the client-side code. * `--skip-client` - This will skip the client-side code and will generate only the server-side code. * `--skip-db-changelog` - This will skip generation of database changelog (using Liquibase for SQL databases). * `--db` - Specify the database when skipping server side generation, has no effect otherwise. :::warning Don't choose a short name for your entity (see [this ticket](https://github.com/jhipster/generator-jhipster/issues/8446)). ::: ## JHipster UML and JDL Studio This page describes how to create entities with JHipster using the standard command-line interface. If you want to create many entities, you might prefer to use a graphical tool. In that case, two options are available: * [JHipster UML](/jhipster-uml/), which allows you to use an UML editor. * [JDL Studio](https://start.jhipster.tech/jdl-studio/), our online tool to create entities and relationships using our domain-specific language [JDL](/jdl/intro/). If you used the JDL Studio: * You can generate entities from a JDL file using the `jdl` sub-generator, by running `jhipster jdl your-jdl-file.jh`. * If you do not want to regenerate your entities, while importing a JDL, you can use the `--json-only` flag to skip entity creation part and create only the json files in `.jhipster` folder. ```shell jhipster jdl ./my-jdl-file.jdl --json-only ``` * By default `jdl` regenerates only entities which have changed, if you want all your entities to be regenerated then pass in the `--force` flag. Please note that this will overwrite all your local changes to the entity files ```shell jhipster jdl ./my-jdl-file.jdl --force ``` * If you want to use JHipster UML instead of the `jdl` sub-generator, you need to install it by running `npm install jhipster-uml`, and then run `jhipster-uml yourFileName.jh`. ## Entity fields For each entity, you can add as many fields as you want. You will need to input the field names and their types, and JHipster will generate for you all the required code and configuration, from the Angular HTML view to the Liquibase changelog. Those fields cannot contain reserved keywords in the technologies you are using. For example, if you use MySQL: * You cannot use Java reserved keywords (as your code will not compile) * You cannot use MySQL reserved keywords (as your database schema update will fail) ## Field types JHipster supports many field types. This support depends on your database backend, so we use Java types to describe them: a Java `String` will be stored differently in Oracle or Cassandra, and it is one of JHipster's strengths to generate the correct database access code for you. * `String`: A Java String. Its default size depends on the underlying backend (if you use JPA, it's 255 by default), but you can change it using the validation rules (putting a `max` size of 1024, for example). * `Integer`: A Java Integer. * `Long`: A Java Long. * `Float`: A Java Float. * `Double`: A Java Double. * `BigDecimal`: A [java.math.BigDecimal](https://docs.oracle.com/javase/8/docs/api/java/math/BigDecimal.html) object, used when you want exact mathematic calculations (often used for financial operations). * `LocalDate`: A [java.time.LocalDate](https://docs.oracle.com/javase/8/docs/api/java/time/LocalDate.html) object, used to correctly manage dates in Java. * `Instant`: A [java.time.Instant](https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html) object, used to represent a timestamp, an instantaneous point on the time-line. * `ZonedDateTime`: A [java.time.ZonedDateTime](https://docs.oracle.com/javase/8/docs/api/java/time/ZonedDateTime.html) object, used to represent a local date-time in a given timezone (typically a calendar appointment). Note that time zones are neither supported by the REST nor by the persistence layers so you should most probably use `Instant` instead. * `Duration`: A [java.time.Duration](https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html) object, used to represent an amount of time. * `LocalTime`: A [java.time.LocalTime](https://docs.oracle.com/javase/8/docs/api/java/time/LocalTime.html) object, used to represent a local time without timezone. Can be used to define business hours for example. * `UUID`: A [java.util.UUID](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html). * `Boolean`: A Java Boolean. * `Enumeration`: A Java Enumeration object. When this type is selected, the sub-generator will ask you what values you want in your enumeration, and it will create a specific `enum` class to store them. * `Blob`: A Blob object, used to store some binary data. When this type is selected, the sub-generator will ask you if you want to store generic binary data, an image object, or a CLOB (long text). Images will be handled specifically on the Angular side, so they can be displayed to the end-user. ## Validation Validation can be set up for each field. Depending on the field type, different validation options will be available. Validation will be automatically generated on: * the HTML views, using the Angular or React or Vue validation mechanism * the Java domain objects, using [Bean Validation](http://beanvalidation.org/) Bean validation will then be used to automatically validate domain objects when they are used in: * Spring MVC REST controllers (using the `@Valid` annotation) * Hibernate/JPA (entities are automatically validated before being saved) Validation information will also be used to generate more precise database column metadata: * Required fields will be marked non-nullable * Unique fields will create a unique constraint * Fields which have a maximum length will have the same column length Validation has a few limitations: * We don't support all validation options from Angular, React and Bean Validation, as we only support those which are common to both client and server APIs * Regular Expression patterns don't work the same in JavaScript and in Java, so if you configure one, you might need to tweak one of the generated patterns * JHipster generates unit tests that work for generic entities, without knowing your validation rules: it is possible that the generated tests do not pass the validation rules. In that case, you will need to update the sample values used in your unit tests, so that they pass the validation rules. ## Entity relationships Entity relationships are only available for SQL databases. It is a fairly complex subject, which has its own documentation page: [Managing relationships](/managing-relationships/). ## Generating a separate service class for your business logic Having a separate service class allows to have more complex logic compared to using a Spring REST Controller directly. Having a service layer (with or without an interface) will allow you to use DTOs (see next section). This is the same logic as using the Spring service sub-generator. ## Data Transfer Objects (DTOs) By default JHipster entities do not use DTOs, but they are available as an option, if you choose to have a service layer (see previous section). Here is the documentation: [Using DTOs](/using-dtos/). ## Filtering Optionally, entities stored in SQL databases can be filtered using JPA. Here is the documentation: [Filtering your entities](/entities-filtering/). ## Pagination Please note that pagination is not available if you created your application with [Cassandra](/using-cassandra/). This will be added in a future release. Pagination uses [the Link header](http://tools.ietf.org/html/rfc5988), as in the [GitHub API](https://developer.github.com/v3/#pagination). JHipster provides a custom implementation of this specification on both the server (Spring MVC REST) and client (Angular/React) sides. When the entity is generated, JHipster provides 4 pagination options: * No pagination (in that case, the back-end won't be paginated) * A complete pagination system, based on [the Bootstrap pagination component](https://getbootstrap.com/docs/4.3/components/pagination/) * An infinite scroll system, based on [the infinite scroll directive](http://sroze.github.io/ngInfiniteScroll/) ## Updating an existing entity The entity configuration is saved in a specific `.json` file, in the `.jhipster` directory. So if you run the sub-generator again, using an existing entity name, you can update or regenerate the entity. When you run the entity sub-generator for an existing entity, you will be asked a question 'Do you want to update the entity? This will replace the existing files for this entity, all your custom code will be overwritten' with following options: * `Yes, re generate the entity` - This will regenerate your entity. Tip: This can be forced by passing a `--regenerate` flag when running the sub-generator * `Yes, add more fields and relationships` - This will give you questions to add more fields and relationships * `Yes, remove fields and relationships` - This will give you questions to remove existing fields and relationships from the entity * `No, exit` - This will exit the sub-generator without changing anything You might want to update your entity for the following reasons: * You want to add/remove fields and relationships to an existing entity * You want to reset your entity code to its original state * You have updated JHipster, and would like to have your entity generated with the new templates * You have modified the `.json` configuration file (the format is quite close to the questions asked by the generator, so it's not very complicated), so you can have a new version of your entity * You have copy/pasted the `.json` file, and want a new entity that is very close to the copied entity :::tip To regenerate all your entities at once, you can use the following commands (remove the `--force` to have questions asked when files have changed). ::: * Linux & Mac: ``for f in `ls .jhipster`; do jhipster entity ${f%.*} --force ; done`` * Windows: `for %f in (.jhipster/*) do jhipster entity %~nf --force` ## Tutorial This is a short tutorial on creating two entities (a Author and a Book) which have a one-to-many relationship. :::warning If you want to have "live reload" of your JavaScript/TypeScript code, you will need run `npm start`. You can go to the [Using JHipster in development](/development/) page for more information. ::: ### Generate the "Author" entity As we want to have a one-to-many relationship between Authors and Books (one author can write many books), we need to create the Author first. At the database level, JHipster will then be able to add a foreign key on the Book table, linking to the Author table. `jhipster entity author` Answer the next questions concerning the fields of this entity, the author has: * a "name" of type "String" * a "birthDate" of type "LocalDate" Then answer the questions concerning the relationships, the author has: * A one-to-many relationship with the "book" entity (which doesn't exist yet) ### Generate the "Book" entity `jhipster entity book` Answer the next questions concerning the fields of this entity, the book has: * a "title", of type "String" * a "description", of type "String" * a "publicationDate", of type "LocalDate" * a "price", of type "BigDecimal" Then answer the questions concerning the relationships, the book: * Has many-to-one relationship with the "author" entity * And this relationship uses the "name" field (from the Author entity) to be displayed ### Check the generated code Run the generated test suite, with `mvn test`, which will test the Author entity and the Book entity. Launch the application (for example with `mvn`), log in and select the "Author" and "Book" entities in the "entities" menu. Check the database tables, to see if your data is correctly inserted. ### Improve the generated code The generated files contain all the basic CRUD operations, and don't need to be modified if you don't need more than CRUD operations. If you want to modify the generated code or the database schema, you should follow our [development guide](/development/) If you want some more complex business behaviors, you might need to add a Spring `@Service` class, using the service sub-generator. ### You're done! Your generated CRUD page should look like this: --- ## File: docs/core-tasks/installing-new-languages.mdx --- title: Internationalization slug: /installing-new-languages/ last_update: date: 2014-12-10T00:00:00-00:00 --- ## Introduction During the generation of a new project you will be asked whether or not you want to enable internationalization support. If enabling it you will need to select the native language of your application. After that you can choose the additional languages you would like to install. If you don't want to support any additional languages from start you can always add languages later when needed by running the language sub-generator. If you are sure you will never translate this application into another language you should not enable the internationalization. ## Supported languages These are the currently supported languages * Albanian * Arabic (Libya) * Armenian * Belarusian * Bengali * Bulgarian * Catalan * Chinese (Simplified) * Chinese (Traditional) * Czech * Danish * Dutch * English * Estonian * Farsi * Finnish * French * Galician * German * Greek * Hindi * Hungarian * Indonesian * Italian * Japanese * Korean * Marathi * Myanmar * Polish * Portuguese (Brazilian) * Portuguese * Punjabi * Romanian * Russian * Slovak * Serbian * Sinhala * Spanish * Swedish * Turkish * Tamil * Telugu * Thai * Ukrainian * Uzbek (Cyrillic) * Uzbek (Latin) * Vietnamese _Your language is missing in JHipster? Help us improve the project with a PR!_ ## How to add languages after project generation? To do this you can run the languages sub-generator with: `jhipster languages` Note that you will need to regenerate your entities if you would like to have them translated in the language you added right now. ## How to add a new language that is not supported? All languages are saved in the folder `src/main/webapp/i18n` (client side) and `src/main/resources/i18n` (server side) Here are the steps to install a new language called `new_lang`: 1. Duplicate the `src/main/webapp/i18/en` folder to `src/main/webapp/i18/new_lang` (this is where all the front-end translations are stored) 2. Translate all files under the folder `src/main/webapp/i18/new_lang` 3. Add the language code `new_lang` to the `languages` variable defined in `src/main/webapp/app/shared/language/find-language-from-key-pipe.ts` ```ts private languages: { [key: string]: { name: string; rtl?: boolean } } = { en: { name: 'English' }, new_lang: { name: 'New Language' } // jhipster-needle-i18n-language-key-pipe - JHipster will add/remove languages in this object }; ``` 4. In the `src/main/resources/i18n` folder, copy the `messages_en.properties` file to `messages_new_lang.properties` (this is where the server-side translations are stored) 5. Translate all keys in the `messages_new_lang.properties` file 6. Add the new language bundling to `webpack/webpack.common.js` ```js new MergeJsonWebpackPlugin({ output: { groupBy: [ { pattern: "./src/main/webapp/i18n/en/*.json", fileName: "./i18n/en.json" }, { pattern: "./src/main/webapp/i18n/new_lang/*.json", fileName: "./i18n/new_lang.json" } // jhipster-needle-i18n-language-webpack - JHipster will add/remove languages in this array ] } }) ``` The new language `new_lang` is now available in the language menu, and it is available both in the front-end Angular application and in the back-end Spring application. ### Contributing the language to generator-jhipster If you would like to contribute a new language to the generator follow steps below; - Add the language to the `LANGUAGES` constant in [`generators/generator-constants.js`](https://github.com/jhipster/generator-jhipster/blob/main/generators/generator-constants.js) ```js { name: 'New Language', dispName: 'New Language', value: 'nl' } ``` - Duplicate the file [`generators/languages/templates/src/main/resources/i18n/messages_en.properties.ejs`](https://github.com/jhipster/generator-jhipster/blob/main/generators/languages/templates/src/main/resources/i18n/messages_en.properties.ejs) to `generators/languages/templates/src/main/resources/i18n/messages_nl.properties.ejs` and translate all the values to the new language. - Duplicate the folder [`generators/languages/templates/src/main/webapp/i18n/en`](https://github.com/jhipster/generator-jhipster/tree/main/generators/languages/templates/src/main/webapp/i18n/en) to `generators/languages/templates/src/main/webapp/i18n/nl` and translate all the files inside it. - Duplicate the file [`generators/entity-i18n/templates/i18n/entity_en.json.ejs`](https://github.com/jhipster/generator-jhipster/blob/main/generators/entity-i18n/templates/i18n/entity_en.json.ejs) to `generators/entity-i18n/templates/i18n/entity_nl.json.ejs` and translate all the values within it. - Duplicate the file [`generators/languages/templates/src/test/resources/i18n/messages_en.properties.ejs`](https://github.com/jhipster/generator-jhipster/blob/main/generators/server/templates/src/test/resources/i18n/messages_en.properties.ejs) to `generators/languages/templates/src/test/resources/i18n/messages_nl.properties.ejs` and translate all the values within it. - Add the language value `nl` to the `language` array in [`test/templates/all-languages/.yo-rc.json`](https://github.com/jhipster/generator-jhipster/blob/main/test/templates/all-languages/.yo-rc.json). Submit a PR with all these changes. ## How to remove an existing language? Here are the steps to remove a language called `old_lang`: 1. Delete the entire language folder from `src/main/webapp/i18/old_lang` 2. Remove the constant entry for `LANGUAGES` in `src/main/webapp/app/core/language/language.constants.ts` 3. Remove the constant entry for `languages` in `src/main/webapp/app/shared/language/find-language-from-key.pipe.ts` 4. Remove the constant entry for `localesToKeep` in `webpack/webpack.prod.js` 5. Remove the pattern for `MergeJsonWebpackPlugin` in `webpack/webpack.common.js` 6. Delete the `src/main/resources/i18n/messages_old_lang.properties` file 7. Delete the `src/test/resources/i18n/messages_old_lang.properties` file --- ## File: docs/core-tasks/managing-relationships.mdx --- title: Managing relationships slug: /managing-relationships/ last_update: date: 2020-11-25T09:07:00-00:00 --- When JPA is used, the [entity sub-generator](/creating-an-entity) can create relationships between entities. ## Presentation Relationships only work when JPA is used. If you choose to use [Cassandra](/using-cassandra) they won't be available. In case you use [MongoDB](/using-mongodb/), [Couchbase](/using-couchbase/) or [Neo4j](/using-neo4j) relations have a different semantics, but they are all available to be used. For more information about Couchbase and MongoDB relationships please refer to [Embedded Entities for Couchbase and MongoDB](#embedded-entities-for-couchbase-and-mongodb). A relationship works between two entities, and JHipster will generate the code for: - Managing this relationship with JPA in the generated entities - Creating the correct Liquibase changelog, in order for the relationship to exist in the database - Generating the Angular/React front-end so you can manage this relationship graphically in the user interface ## JHipster UML and JDL Studio This page describes how to create relationships with JHipster using the standard command-line interface. If you want to create many entities and relationships, you might prefer to use a graphical tool. In that case, three options are available: - [JDL Studio](https://start.jhipster.tech/jdl-studio/), our online tool to create entities and relationships using our domain-specific language. - [JHipster IDE](/jhipster-ide/), a plugin that provides textual editing support of JDL files for popular IDEs. - Deprecated: _[JHipster UML](/jhipster-uml/), which allows you to use an UML editor._ You can generate entities with relationships from a JDL file using the `jdl` sub-generator, by running `jhipster jdl your-jdl-file.jh`. ## Available relationships As we use JPA, the usual one-to-many, many-to-one, many-to-many and one-to-one relationships are available. :::tip The `User` entity ::: Information about it is located [here](/user-entity). :::warning **A small warning about entity & relationship generation**: in the following examples, you'll notice that compilation _may_ fail in some cases because destination entities aren't generated and that's normal (this warning can be ignored). ::: There are two ways to avoid that: - Generate the entities first, then the relationships - Use the JDL ## A bidirectional one-to-many relationship Let's start with two entities, a `Owner` and a `Car`. A owner can have many cars, and a car can have only one owner. So this is a one-to-many relationship (one owner has many cars) on one side, and a many-to-one relationship (many cars have one owner) on the other side: ``` Owner (1) <-----> (*) Car ``` Note that after generating the entity, the generator will inform you that some errors occurred while generating the files. That's normal as the destination entity has not yet been generated, so you can safely ignore this warning. We will create the `Owner` first. Here are the relevant JHipster questions for the `Owner`: ``` jhipster entity Owner ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Car ? What is the name of the relationship? car ? What is the type of the relationship? one-to-many ? What is the name of this relationship in the other entity? owner ``` Please note that we selected the default options concerning the names of the relationships. Now we can generate the `Car`: ``` jhipster entity Car ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Owner ? What is the name of the relationship? owner ? What is the type of the relationship? many-to-one ? When you display this relationship with Angular, which field from 'Owner' do you want to use? id ``` The same can be achieved using the below JDL as well ``` entity Owner entity Car relationship OneToMany { Owner{car} to Car{owner} } ``` That's it, you now have a one-to-many relationship between those two entities! On the generated Angular/React client UI you will have a dropdown in `Car` to select a `Owner`. ## A bidirectional many-to-one relationship This is equivalent to the bidirectional one-to-many relationship after inversing the sides in the JDL file: ``` entity Owner entity Car relationship ManyToOne { Car{owner} to Owner{car} } ``` ## A unidirectional many-to-one relationship In the previous example we had a bidirectional relationship: from a `Car` instance you could find its owner, and from a `Owner` instance you could get all of its cars. A many-to-one unidirectional relationship means that the cars know their owner, but not the opposite. ``` Owner (1) <----- (*) Car ``` You would do that relationship for two reasons: - From a business point of view, you only use your entities in this way. So you don't want to have an API that allows developers to do something which doesn't make sense. - You have a small performance gain when using the `Owner` entity (as it won't have to manage the collection of cars). In that case, you would still create the `Owner` first, this time with no relationship: ``` jhipster entity Owner ... Generating relationships to other entities ? Do you want to add a relationship to another entity? No ``` And then the `Car` entity, as in the previous example: ``` jhipster entity Car ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Owner ? What is the name of the relationship? owner ? What is the type of the relationship? many-to-one ? When you display this relationship with Angular, which field from 'Owner' do you want to use? id ``` This will work as in the previous example, but you won't be able to add or remove cars from the `Owner` entity. On the generated Angular/React client UI you will have a dropdown in `Car` to select a `Owner`. This is the corresponding JDL: ``` entity Owner entity Car relationship ManyToOne { Car{owner} to Owner } ``` ## A unidirectional one-to-many relationship A one-to-many unidirectional relationship means that the `Owner` instance can get its collection of cars, but not the opposite. It is the opposite from the previous example. ``` Owner (1) -----> (*) Car ``` This type of relationship is not provided by default in JHipster at the moment, see [#1569](https://github.com/jhipster/generator-jhipster/issues/1569) for more information. You have two solutions for this: - Do a bidirectional mapping, and use it without modification: this is our recommended approach, as it is much simpler - Do a bidirectional mapping, and then modify it to transform it into a unidirectional mapping: - Remove the "mappedBy" attribute on your `@OneToMany` annotation - Generate the required join table: you can do a `mvn liquibase:diff` to generate that table, see the [documentation about using Liquibase diff](/development/) This is not supported with JDL as it isn't in JHipster. ## Two one-to-many relationships on the same two entities For this example, a `Person` can be the owner of many cars and can also be the driver of many cars: ``` Person (1) <---owns-----> (*) Car Person (1) <---drives---> (*) Car ``` For this we need to use the relationship names, which we have left with their default values in the previous examples. Generate the `Person` entity, which has two one-to-many relationships to the `Car` entity: ``` jhipster entity Person ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Car ? What is the name of the relationship? ownedCar ? What is the type of the relationship? one-to-many ? What is the name of this relationship in the other entity? owner ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Car ? What is the name of the relationship? drivenCar ? What is the type of the relationship? one-to-many ? What is the name of this relationship in the other entity? driver ``` Generate the `Car` entity, which use the same relationship name has was configured in the `Person` entity: ``` jhipster entity Car ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Person ? What is the name of the relationship? owner ? What is the type of the relationship? many-to-one ? When you display this relationship with Angular, which field from 'Person' do you want to use? id ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Person ? What is the name of the relationship? driver ? What is the type of the relationship? many-to-one ? When you display this relationship with Angular, which field from 'Person' do you want to use? id ``` The same can be achieved using the below JDL as well ``` entity Person entity Car relationship OneToMany { Person{ownedCar} to Car{owner} } relationship OneToMany { Person{drivenCar} to Car{driver} } ``` A `Car` can now have a driver and a owner, which are both `Person` entities. On the generated Angular/React client UI you will dropdowns in `Car` to select a `Person` for `owner` field and `driver` field. ## A many-to-many relationship A `Driver` can drive many cars, but a `Car` can also have many drivers. ``` Driver (*) <-----> (*) Car ``` At the database level, this means we will have a join table between the `Driver` and the `Car` tables. For JPA, one of those two entities will need to manage the relationship: in our case, that would be the `Car` entity, which will be responsible to add or remove drivers. Please note that, after generating the entity, the generator will inform you that some errors occurred while generating the files. That's normal as the destination entity has not yet been generated, so you can safely ignore this warning. Let us generate the non-owning side of the relationship, the `Driver`, with a many-to-many relationship: ``` jhipster entity Driver ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Car ? What is the name of the relationship? car ? What is the type of the relationship? many-to-many ? Is this entity the owner of the relationship? No ? What is the name of this relationship in the other entity? driver ``` Then generate the `Car`, with the owning side of the many-to-many relationship: ``` jhipster entity Car ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Driver ? What is the name of the relationship? driver ? What is the type of the relationship? many-to-many ? Is this entity the owner of the relationship? Yes ? What is the name of this relationship in the other entity? car ? When you display this relationship on client-side, which field from 'Driver' do you want to use? This field will be displayed as a String, so it cannot be a Blob id ``` The same can be achieved using the below JDL as well ``` entity Driver entity Car relationship ManyToMany { Car{driver} to Driver{car} } ``` That's it, you now have a many-to-many relationship between those two entities! On the generated Angular/React client UI you will have a multi-select dropdown in `Car` to select multiple `Driver` since `Car` is the owning side. ## A one-to-one relationship Following our example, a one-to-one relationship would mean that a `Driver` can drive only one `Car`, and a `Car` can only have one `Driver`. ``` Driver (1) <-----> (1) Car ``` Let us create the non-owning side of the relationship, in our case the `Driver`: ``` jhipster entity Driver ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Car ? What is the name of the relationship? car ? What is the type of the relationship? one-to-one ? Is this entity the owner of the relationship? No ? What is the name of this relationship in the other entity? driver ``` Then generate the `Car`, which owns the relationship: ``` jhipster entity Car ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Driver ? What is the name of the relationship? driver ? What is the type of the relationship? one-to-one ? Is this entity the owner of the relationship? Yes ? Do you want to use JPA Derived Identifier - @MapsId? No ? What is the name of this relationship in the other entity? car ? When you display this relationship on client-side, which field from 'Driver' do you want to use? This field will be displayed as a String, so it cannot be a Blob id ``` The same can be achieved using the below JDL as well ``` entity Driver entity Car relationship OneToOne { Car{driver} to Driver{car} } ``` That's it, you now have a one-to-one relationship between those two entities! On the generated Angular/React client UI you will have a dropdown in `Car` to select a `Driver` since `Car` is the owning side. [More information on using one-to-one with JPA Derived Identifiers](#using-jpa-derived-identifiersmapsid-for-one-to-one-relationship) ## A unidirectional one-to-one relationship A unidirectional one-to-one relationship means that the `citizen` instance can get its passport, but the `passport` instance can't get to its owner. ``` Citizen (1) -----> (1) Passport ``` Generate the `Passport` entity first, without any relationship to its owner: ``` jhipster entity Passport ... Generating relationships to other entities ? Do you want to add a relationship to another entity? No ``` Then, generate the `Citizen` entity: ``` jhipster entity Citizen ... Generating relationships to other entities ? Do you want to add a relationship to another entity? Yes ? What is the name of the other entity? Passport ? What is the name of the relationship? passport ? What is the type of the relationship? one-to-one ? Is this entity the owner of the relationship? Yes ? Do you want to use JPA Derived Identifier - @MapsId? No ? What is the name of this relationship in the other entity? citizen ? When you display this relationship with Angular, which field from 'Passport' do you want to use? id ``` After doing this, a `Citizen` possesses a passport, but no `Citizen` instance is defined in `Passport`. On the generated Angular/React client UI you will have a dropdown in `Citizen` to select a `Passport` since `Citizen` is the owning side. This is the corresponding JDL: ``` entity Citizen entity Passport relationship OneToOne { Citizen{passport} to Passport } ``` ### Using JPA Derived Identifiers(@MapsId) for one-to-one relationship [JPA Derived Identifiers](https://javaee.github.io/javaee-spec/javadocs/javax/persistence/MapsId.html) can be used to have [the most efficient mapping](https://vladmihalcea.com/the-best-way-to-map-a-onetoone-relationship-with-jpa-and-hibernate/). This is the corresponding JDL for previous uni-directional one-to-one example: ``` entity Citizen entity Passport relationship OneToOne { Citizen{passport} to @Id Passport } ``` This is the corresponding JDL for previous bi-directional one-to-one example: ``` entity Driver entity Car relationship OneToOne { Car{driver} to @Id Driver{car} } ``` However, based on business requirements, there might be cases where this should be avoided because it has following constraint: **Once the id(primary key) is set at owning side, it is not changeable using JPA/Hibernate. You should not change it anyway.** **Here are a few suggestions regarding usage:** Use `@MapsId` when: * Dependent - if the owning side (child entity) seems tightly dependent on the non-owning (parent entity). * Association value is never meant to be changed - if you are never going to change the id(primary key) of the child entity once it is set. For example: ``` class User{} class Profile{ @OneToOne @MapsId private User user; } // profile is only meant for that user class Preferences{ @OneToOne @MapsId private User user; } // preference is only meant for that user ``` Once a profile or a preference is created for a user, it will never change to refer to another user. Do not use `@MapsId` when: * Not dependent - If the owning side (child entity) seems not dependent on the non-owning (parent entity) * Association value is meant to be changed - if you think that the child entity is going to refer to another parent entity in future. For example: ``` class Car{ @OneToOne @JoinColumn(name="current_driver_id") Driver currentDriver} // car can be drived by another driver in future class Driver{@OneToOne(mappedBy = "currentDriver") Car drivingCar} // driver drives another car in future ``` Both car and driver association value may change in future. :::note There is [a known issue regarding using `@OneToOne` with `@MapsId` and how to avoid it](/tips/026_tip_issue_of_onetoone_with_mapsid_how_to_avoid_it.html). ::: ## Setting fetching data strategy to eager (FetchType.EAGER) All the relationships use the default JPA FetchType: - OneToMany: LAZY - ManyToOne: EAGER - ManyToMany: LAZY - OneToOne: EAGER There is [a known issue of NPE during JSON deserialization](https://github.com/jhipster/generator-jhipster/issues/10981) due to eager fetch type. If you would like to set either `OneToMany` or `ManyToMany` relationship to `FetchType.EAGER`, you can use one of the following solutions: - Use `@JsonInclude(JsonInclude.Include.NON_EMPTY)` on the relationship For example: ``` @OneToMany(mappedBy = "parent", fetch = FetchType.EAGER) @JsonInclude(JsonInclude.Include.NON_EMPTY) private Set child = new HashSet<>(); ``` - Return null if the collection is empty when fetching the resource in the backend - Using DTO and handle the edge case of empty collection ## Embedded Entities for Couchbase and MongoDB Couchbase and MongoDB supports relationships through embedded documents. For more information regarding embedded documents in MongoDB refer to [https://docs.mongodb.com/manual/applications/data-models-relationships/](https://docs.mongodb.com/manual/applications/data-models-relationships/) and for Couchbase refer to [https://docs.couchbase.com/server/5.1/data-modeling/modeling-relationships.html](https://docs.couchbase.com/server/5.1/data-modeling/modeling-relationships.html). You can define embedded documents simply by using `@embedded`. For example to define a one-to-one relationship; ``` entity Country { countryName String } @embedded entity Region { regionName String } relationship OneToOne { Country to Region } ``` Similarly, for a one-to-many relationship, ``` entity Country { countryName String } @embedded entity Region { regionName String } relationship OneToMany { Country to Region } ``` For a many-to-many relationship you can simply use the `@embedded` keyword in both directions; ``` @embedded entity Country { countryName String } @embedded entity Region { regionName String } relationship ManyToMany { Country to Region } ``` --- ## File: docs/core-tasks/upgrading-an-application.mdx --- title: Upgrading an application slug: /upgrading-an-application/ gitgraph: http://jsfiddle.net/lordlothar99/tqp9gyu3 last_update: date: 2024-04-08T00:00:00-00:00 --- # Upgrading an application ## Summary 1. [Option 1 - Automatic Upgrade](#option-1---automatic-upgrade) 2. [Option 2 - Manual Upgrade](#option-2---manual-upgrade) ## Option 1 - Automatic Upgrade This is helpful to: * Have the latest JHipster features in an existing application * Get the changes when there is an important bug fix or security update * Retain your changes in your codebase, and merge them with newly generated code :::warning Please read this page carefully before doing an upgrade, to understand how the upgrade process works ::: ### Requirements For this sub-generator to work you need to have `git` installed from [http://git-scm.com](http://git-scm.com/). ### Running the upgrade sub-generator Go into the application's root directory: `cd myJHipsterProject/` To upgrade your application, type: `npx generator-jhipster@latest upgrade` An alternative is to use global installation: ``` npm install -g generator-jhipster@latest jhipster upgrade ``` Here are the options you can pass: * `--skip-checks` - Disable checks during project regeneration * `--silent` - Hides output of the generation process ### Upgrading from JHipster 7 and previous versions The [migrate blueprint](https://github.com/jhipster/generator-jhipster-migrate) is an advanced version of the upgrade sub-generator. If you need to upgrade a JHipster 7 app, it's recommended you use the migrate blueprint. For example, let's assume you have a 7.9.3 app. Run `jhipster-migrate` to upgrade to the latest version. Resolve conflicts, commit, and celebrate! For a working example, see the following pull requests from the 21-Points Health project. - [Upgrade to JHipster 7.9.4](https://github.com/mraible/21-points/pull/248) - [Upgrade to JHipster 8.2.1](https://github.com/mraible/21-points/pull/249) ### Graphical view of the upgrade process Here is how the upgrade process works graphically (read the sections below to have a textual explanation): [Raw .mermaid file](/upgrading-an-application/jhipster_upgrade.mermaid) Please note that the `jhipster_upgrade` branch will be created orphan on your project, although it doesn't display correctly on the above graph. ### Step-by-step explanation of the upgrade process Below are the steps processed by the JHipster upgrade sub-generator: 1. Check if there is a new version of JHipster available (not applicable if you are using `--force`). 2. Check if the application is already initialized as a `git` repository, or else JHipster will initialize one for you and commit the current codebase to the master branch. 3. Check to ensure that there are no un-committed local changes in the repository. The process will exit if there are un-committed changes found. 4. Check if a `jhipster_upgrade` branch exists. If not, a branch is created: details about this step is provided in the "Specific steps on first upgrade" section. 5. Checkout the `jhipster_upgrade` branch. 6. Upgrade JHipster to the latest available version globally. 7. Clean the current project directory. 8. Re-generate the application using the `jhipster --force` command. 9. Commit the generated code to the `jhipster_upgrade` branch. 10. Merge the `jhipster_upgrade` branch back to the original branch from where the `npx jhipster upgrade` command was launched. 11. Now you need to proceed with resolving merge conflicts if there are any. Congratulations, your application is now upgraded with the latest version of JHipster! ### Specific steps on first upgrade On the first run of the JHipster upgrade sub-generator, in order to avoid erasing all your changes, some additional steps are run: 1. A `jhipster_upgrade` branch is created orphan (it has no parent). 2. The whole application is generated (using your current JHipster version). 3. A block-merge commit is made on the `master` branch: no alteration is made on your codebase on the `master` branch; this is a practical way to record in Git that the HEAD of `master` is up-to-date with the current JHipster version. #### Advice * Don't commit anything on the `jhipster_upgrade` branch. This branch is dedicated to the JHipster upgrade sub-generator: each time the sub-generator is run, a new commit will be created. * If you are updating from a very old version (example from 5.0.0 to latest) we suggest updating gradually between each minor/patch version and performing tests to make sure the application works as expected. * There are some helpful approaches from the JHipster community around designing the application in such a way that makes the update process easier, and reduces the amount of merge conflicts. We recommend using [JHipster Side-by-Side approach](https://www.youtube.com/watch?v=Gg5CYoBdpVo). ## Option 2 - Manual Upgrade For a manual upgrade, first upgrade your version of JHipster with: ```shell npm install -g generator-jhipster ``` Delete your project `node_modules` folder and then run `jhipster`: ```shell rm -rf node_modules jhipster ``` You can also update your project and all its entities by running ```shell jhipster --force ``` You can also update your entities individually by running the `entity` sub-generator, i.e., if your entity is named _Foo_: ```shell jhipster entity Foo ``` ### Hints about renamed files Sometimes files may be renamed in the generator. If you want to see Git rename detection result then you can run `git add` (`git add .` stages all) and view changes after that with your favorite Git client. If many files are renamed then you may want to increase `diff.renameLimit` in Git config to make Git rename detection work as expected. For example `git config --replace-all diff.renameLimit 10000`. By default Git rename detection uses similarity threshold 50%. To see less similar files as renamed, you can use option `--find-renames=` in Git commands. For example `git diff --staged --find-renames=30`. ### See your own changes If you would like to see changes you have done after generating project you can follow the steps described below. Clone your project into the new folder with `git clone`. Delete all files and folders from cloned project except `.git`, `.jhipster` and `.yo-rc.json`. Find out what JHipster version you used last time to generate your project: look at the `.yo-rc.json` in the project root folder, find out the value of the `jhipsterVersion`. Install JHipster version you used last time you generated your project: ```shell npm install -g generator-jhipster@jhipsterVersionYouUsedLastTime ``` Regenerate your project: ```shell jhipster --force --skip-install ``` With `git diff` you can now see all your changes as reverted. If you would like to see all your changes as added then you can commit all to Git and then revert the last commit. ### See JHipster changes If you would like to see changes done by JHipster you can follow the steps described below. Generate project with JHipster version you used last time to generate your project: * create a new folder * copy your project `.yo-rc.json` file and `.jhipster` folder into this new folder * find out what JHipster version you used last time to generate your project: look at the `.yo-rc.json`, find out the value of the `jhipsterVersion` * install JHipster version you used last time to generate your project: `npm install generator-jhipster@jhipsterVersionYouUsedLastTime` * in the created folder run: `jhipster --skip-install` Generate project with the latest JHipster: * create a new folder * copy your project `.yo-rc.json` file and `.jhipster` folder into this new folder * install the latest JHipster version: `npm install generator-jhipster` * in the created folder run: `jhipster --skip-install` Compare those 2 folders with your favorite file and folder compare tool to see changes done by JHipster. --- ## File: docs/core-tasks/using-dtos.mdx --- title: Using DTOs slug: /using-dtos/ last_update: date: 2015-05-28T23:41:00-00:00 --- ## Introduction By default, JHipster uses its domain objects (typically JPA entities) directly in its REST endpoints. This has a lot of benefits, the main one being that the code is easier to understand as it contains fewer layers. For complex use cases, however, you might want to use Data Transfer Objects (or DTOs) that will be exposed by the REST endpoints. Those objects add an extra layer on top of the domain objects, and are specifically tuned for the REST layer: their main benefit is that they can aggregate several domain objects. ## How DTOs work in JHipster When generating a JHipster entity, you have the option to add a service layer: the DTO option will only be available if you choose to have a service layer, as it needs that layer to handle the mapping (if you are using JPA, this is because the service layer is transactional, so lazy-loading will work). Once you have selected to have a service layer, you will have the option to generate a DTO for the entity. If you select that option: - A DTO will be generated, and it will be mapped on the underlying entity. - It will aggregate many-to-one relationships, only using the ID and the field used to display it in your client-side framework (Angular, for example). As a result, a many-to-one relationship to the `User` entity will add a `userId` field and a `userLogin` field to the DTO. - It will ignore one-to-many relationships and many-to-many relationships on the non-owner side: this matches the way entities work (they have a `@JsonIgnore` annotation on those fields). - For a many-to-many relationship on the owner side: it will use DTOs from the other entity and use them in a `Set`. Thus, this can only work if the other entity also uses DTOs. ## Using MapStruct to map DTOs and entities As DTOs look a lot like entities, it's a frequent requirement to have a solution to map them automatically with each other. The selected solution in JHipster is to use [MapStruct](http://mapstruct.org/). It is an annotation processor, plugged into the Java compiler, that will generate the required mapping automatically. We have found it very clean and efficient, and liked that it does not use reflection (which is bad for performance when used as heavily as in a mapper). ## Configuring your IDE for MapStruct MapStruct is an annotation processor, and as such it should also be set up to be run automatically when your IDE compiles the project. If you are using Maven, you need to activate the `IDE` maven profile in your IDE. Gradle users don't need to apply anything IDE-specific. Instructions for activating the profile are included in [Configuring your IDE](/configuring-ide/). ## Advanced MapStruct usage MapStruct mappers are configured as Spring Beans, and support dependency injection. One nice tip is that you can inject a `Repository` into a mapper, so you can fetch a managed JPA entity from the mapper, using its ID. Here is an example code, fetching a `User` entity: ```java @Mapper public abstract class CarMapper { @Inject private UserRepository userRepository; @Mapping(source = "user.id", target = "userId") @Mapping(source = "user.login", target = "userLogin") public abstract CarDTO carToCarDTO(Car car); @Mapping(source = "userId", target = "user") public abstract Car carDTOToCar(CarDTO carDTO); public User userFromId(Long id) { if (id == null) { return null; } return userRepository.findOne(id); } } ``` --- ## File: docs/development/common-application-properties.mdx --- title: Common application properties slug: /common-application-properties/ last_update: date: 2018-03-18T18:20:00-00:00 --- JHipster generates a Spring Boot application, and can be configured using the standard Spring Boot properties mechanism. Those properties are configured at generation-time by JHipster, and often have different values in development and production modes: learn more about this in our [Profiles documentation](/profiles). ## Spring Boot standard application properties Like any Spring Boot application, JHipster allows you to configure any standard [Spring Boot application property](http://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html). ## JHipster application properties JHipster provides specific application properties, which come from the [JHipster server-side library](https://github.com/jhipster/jhipster). Those properties are standard for all JHipster projects, but some of them only work depending on what you selected when you built your application: for example the `jhipster.cache.hazelcast` key only works if you selected Hazelcast as your 2nd-level Hibernate cache. Those properties are configured using the `io.github.jhipster.config.JHipsterProperties` class. Here is a documentation for those properties: ```yaml jhipster: # Thread pool that will be used for asynchronous method calls in JHipster async: core-pool-size: 2 # Initial pool size max-pool-size: 50 # Maximum pool size queue-capacity: 10000 # Queue capacity of the pool # Specific configuration for JHipster gateways # See https://www.jhipster.tech/api-gateway/ for more information on JHipster gateways gateway: rate-limiting: enabled: false # Rate limiting is disabled by default limit: 100_000L # By default we allow 100,000 API calls duration-in-seconds: 3_600 # By default the rate limiting is reinitialized every hour authorized-microservices-endpoints: # Access Control Policy, if left empty for a route, all endpoints will be accessible app1: /api # recommended prod configuration, it allows the access to all API calls from the "app1" microservice # HTTP configuration http: cache: # Used by io.github.jhipster.web.filter.CachingHttpHeadersFilter timeToLiveInDays: 1461 # Static assets are cached for 4 years by default # Hibernate 2nd level cache, used by CacheConfiguration cache: hazelcast: # Hazelcast configuration time-to-live-seconds: 3600 # By default objects stay 1 hour in the cache backup-count: 1 # Number of objects backups # Configure the Hazelcast management center # Full reference is available at: http://docs.hazelcast.org/docs/management-center/3.9/manual/html/Deploying_and_Starting.html management-center: enabled: false # Hazelcast management center is disabled by default update-interval: 3 # Updates are sent to the Hazelcast management center every 3 seconds by default # Default URL for Hazelcast management center when using JHipster's Docker Compose configuration # See src/main/docker/hazelcast-management-center.yml # Warning, the default port is 8180 as port 8080 is already used by JHipster url: http://localhost:8180/mancenter ehcache: # Ehcache configuration time-to-live-seconds: 3600 # By default objects stay 1 hour in the cache max-entries: 100 # Number of objects in each cache entry caffeine: # Caffeine configuration time-to-live-seconds: 3600 # By default objects stay 1 hour in the cache max-entries: 100 # Number of objects in each cache entry infinispan: #Infinispan configuration config-file: default-configs/default-jgroups-tcp.xml # local app cache local: time-to-live-seconds: 60 # By default objects stay 1 hour (in minutes) in the cache max-entries: 100 # Number of objects in each cache entry #distributed app cache distributed: time-to-live-seconds: 60 # By default objects stay 1 hour (in minutes) in the cache max-entries: 100 # Number of objects in each cache entry instance-count: 1 #replicated app cache replicated: time-to-live-seconds: 60 # By default objects stay 1 hour (in minutes) in the cache max-entries: 100 # Number of objects in each cache entry # Memcached configuration # Uses the Xmemcached library, see https://github.com/killme2008/xmemcached memcached: # Disabled by default in dev mode, as it does not work with Spring Boot devtools enabled: true servers: localhost:11211 # Comma or whitespace separated list of servers' addresses expiration: 300 # Expiration time (in seconds) for the cache use-binary-protocol: true # Binary protocol is recommended for performance (and security) authentication: # if authentication is required you can set it with these parameters. Disabled by default enabled: false, # username: unset by default # password: unset by default redis: # Redis configuration expiration: 3600 # By default objects stay 1 hour (in seconds) in the cache server: redis://localhost:6379 # Server address cluster: false connectionPoolSize: 64, connectionMinimumIdleSize: 24, subscriptionConnectionPoolSize: 50, subscriptionConnectionMinimumIdleSize: 1 # E-mail properties mail: enabled: false # If e-mail sending is enabled. The standard `spring.mail` keys will need to be configured from: jhipster@localhost # The default "from" address for e-mails base-url: http://127.0.0.1:8080 # URL to the application, used inside e-mails # Spring Security specific configuration security: remember-me: # JHipster secure implementation of the remember-me mechanism, for session-based authentication # security key (this key should be unique for your application, and kept secret) key: 0b32a651e6a65d5731e869dc136fb301b0a8c0e4 authentication: jwt: # JHipster specific JWT implementation # The secret token should be encoded using Base64 (you can type `echo 'secret-key'|base64` on your command line). # If both properties are configured, the `secret` property has a higher priority than the `base64-secret` property. secret: # JWT secret key in clear text (not recommended) base64-secret: # JWT secret key encoded in Base64 (recommended) token-validity-in-seconds: 86400 # Token is valid 24 hours token-validity-in-seconds-for-remember-me: 2592000 # Remember me token is valid 30 days # Swagger configuration swagger: default-include-pattern: /api/.* title: JHipster API description: JHipster API documentation version: 0.0.1 terms-of-service-url: contact-name: contact-url: contact-email: license: license-url: host: protocols: # DropWizard Metrics configuration, used by MetricsConfiguration metrics: jmx: # Export metrics as JMX beans enabled: true # JMX is enabled by default # Send metrics to a Graphite server # Use the "graphite" Maven profile to have the Graphite dependencies graphite: enabled: false # Graphite is disabled by default host: localhost port: 2003 prefix: jhipster # Send metrics to a Prometheus server prometheus: enabled: false # Prometheus is disabled by default endpoint: /prometheusMetrics logs: # Reports Dropwizard metrics in the logs enabled: false reportFrequency: 60 # frequency of reports in seconds # Logging configuration, used by LoggingConfiguration logging: logstash: # Forward logs to Logstash over a socket enabled: false # Logstash is disabled by default host: localhost # Logstash server URL port: 5000 # Logstash server port queue-size: 512 # Queue for buffering logs spectator-metrics: # Reports Netflix Spectator metrics in the logs enabled: false # Spectator is disabled by default # By default cross-origin resource sharing (CORS) is enabled in "dev" mode for # monoliths and gateways. # It is disabled by default in "prod" mode for security reasons, and for microservices # (as you are supposed to use a gateway to access them). # This configures a standard org.springframework.web.cors.CorsConfiguration # Note that "exposed-headers" is mandatory for JWT-based security, which uses # the "Authorization" header, and which is not a default exposed header. cors: allowed-origins: "*" allowed-methods: "*" allowed-headers: "*" exposed-headers: "Authorization" allow-credentials: true max-age: 1800 # Ribbon displayed on the top left-hand side of JHipster applications ribbon: # Comma-separated list of profiles that display a ribbon display-on-active-profiles: dev ``` ## Application-specific properties Your generated application can also have its own Spring Boot properties. This is highly recommended, as it allows type-safe configuration of the application, as well as auto-completion and documentation within an IDE. JHipster has generated a `ApplicationProperties` class in the `config` package, which is already preconfigured, and it is already documented at the bottom the `application.yml`, `application-dev.yml` and `application-prod.yml` files. All you need to do is code your own specific properties. --- ## File: docs/development/common-ports.mdx --- title: Common ports slug: /common-ports/ last_update: date: 2021-03-08T12:00:00-00:00 --- JHipster configures many tools and services, and each of them will likely use one or several ports. Here is a documentation to help understand what each port does, and help in case of a port conflict. Please note that as per the JHipster [Policy 1](/policies), the standard port for each technology is used, unless that causes a problem (that should be explained here). The ports here are listed in order, but the most common questions are for ports `8080`, `9000` and `9060`. |Port |Description | |-----|----------------------------------------------------------------------------------------------------------------------------------------------------------------------| |2181 |Zookeeper (used with Kafka) | |3000 |Grafana | |3306 |MySQL and MariaDB | |5000 |Logstash | |5432 |PostgreSQL | |5701 |Hazelcast | |6650 |Pulsar - Service port | |7742 |Swagger Editor | |8080 |JHipster application back-end development port (Spring Boot server) | |8081 |JHipster microservice default port | |8091 |Couchbase - Web administration port | |8092 |Couchbase - API port | |8093 |Couchbase - used by query services for REST/HTTP traffic | |8180 |Hazelcast management center | |8300 |Consul - server | |8301 |Consul - serflan-tcp and serflan-udp | |8302 |Consul - serfwan-tcp and serfwan-udp | |8400 |Consul - RPC | |8500 |Consul - HTTP port with the Web UI | |8600 |Consul - DNS | |8761 |JHipster Registry (Netflix Eureka) | |9000 |JHipster front-end development port with BrowserSync | |9001 |SonarQube | |9042 |Cassandra - CQL | |9060 |JHipster front-end development port with Webpack hot-reload | |9090 |Prometheus | |9092 |Kafka | |9093 |Prometheus alert manager | |9160 |Cassandra - Thrift | |9200 |Elasticsearch - HTTP connections (REST API) | |9300 |Elasticsearch - transport connections (native API) | |9411 |Zipkin | |11210|Couchbase - Internal/external bucket port | |18080|H2 (embedded database) running inside a monolith. Default port is normally 9092 but this would cause a conflict with Kafka, so it is fixed as "1" + "Spring Boot port"| |18081|H2 (embedded database) running inside a microservice. See line above for more information | |27017|MongoDB | --- ## File: docs/development/customizing-bootstrap.mdx --- title: Customizing Bootstrap slug: /customizing-bootstrap/ last_update: date: 2026-09-27T00:00:00-00:00 --- ## Basic customization :::tip Don't forget to run `npm start` to get immediate feedback of your changes! ::: The simplest way to customize how your JHipster application looks like is by overriding styles in the global Sass file: `src/main/webapp/content/scss/global.scss` for Angular and Vue, or `src/main/webapp/app/app.scss` for React. Bootstrap is written in Sass; see Bootstrap's [official documentation about theming](https://getbootstrap.com/docs/5.3/customize/sass/). If you want to use Bootstrap [partials](https://sass-lang.com/guide/#partials) in your own `scss` files then import it like below at the beginning of your `scss` file. For example to use the border-radius mixin: ```css @import "node_modules/bootstrap/scss/variables"; @import "node_modules/bootstrap/scss/mixins/border-radius"; ``` Make sure you import only partials and not main Sass files, otherwise you will end up generating duplicate CSS which might cause issues. To change the default Bootstrap settings like colors, border-radius, etc., add or change the value of the property in the partial file `src/main/webapp/content/scss/_bootstrap-variables.scss` (Angular and Vue) or `src/main/webapp/app/_bootstrap-variables.scss` (React) All values defined in Bootstrap [_variables.scss](https://github.com/twbs/bootstrap/blob/main/scss/_variables.scss) can be overwritten here. --- ## File: docs/development/development.mdx --- title: Using JHipster in development slug: /development/ last_update: date: 2023-01-05T00:00:00-00:00 --- _**Please check our [video tutorial](/video-tutorial) on creating a new JHipster application!**_ ## General configuration ### IDE configuration If you haven't configured your IDE yet, please go to the [Configuring your IDE](/configuring-ide) page. ### Application configuration By default, JHipster uses the "development" profile, so you don't have to configure anything. If you want more information on the available profiles, please go the section titled "[Profiles](/profiles)". If you want to configure some specific JHipster properties, have a look at the [common application properties](/common-application-properties) page. ## Running the Java server ### As a "main" Java class From your IDE, right-click on the "Application" class at the root of your Java package hierarchy, and run it directly. You should also be able to debug it from your IDE. The application will be available on [http://localhost:8080](http://localhost:8080). This application will have "hot reload" enabled by default, so if you compile a class, the Spring application context should refresh itself automatically, without the need to restart the server. ### As a Maven project You can launch the Java server with Maven. JHipster provides a Maven wrapper, so you don't need to install Maven, and you have the guarantee that all project users have the same Maven version: on Mac OS X/Linux: ```shell ./mvnw ``` on Windows: ```shell mvnw ``` (this will run our default Maven task, `spring-boot:run`) The application will be available on [http://localhost:8080](http://localhost:8080). If you will use live reload with `npm start` then you can speed up server start up by excluding webpack tasks by: ```shell ./mvnw -P-webapp ``` Alternatively, if you have installed Maven, you can launch the Java server with Maven: ```shell mvn ``` If you want more information on using Maven, please go to [http://maven.apache.org](http://maven.apache.org) ### (Optional) As a Gradle project If you selected the Gradle option, JHipster provides a Gradle wrapper, so you don't need to install Gradle, and you have the guarantee that all project users have the same Gradle version: on Mac OS X/Linux: ```shell ./gradlew ``` on Windows: ```shell gradlew ``` (this will run our default Gradle task, `bootRun`) The application will be available on [http://localhost:8080](http://localhost:8080). If you will use live reload with `npm start` then you can speed up server start up by excluding webpack tasks by: ```shell ./gradlew -x webapp ``` Alternatively, if you have installed Gradle, you can launch the Java server with Gradle: ```shell gradle ``` If you want more information on using Gradle, please go to [https://gradle.org](https://gradle.org) ## Working with Angular/React ### Running Webpack _This step is required to see changes in your TypeScript code and have live reloading of your client-side code._ Running Webpack is the default task in the `package.json` file, so it is enough to run: ```shell npm start ``` This provides very impressive features: * As soon as you modify one of your HTML/CSS/TypeScript file, your browser will refresh itself automatically * When you test your application on several different browsers or devices, all your clicks/scrolls/inputs should be automatically synchronized on all screens This will launch: - A Webpack task that will automatically compile TypeScript code into JavaScript - A Webpack "hot module reload" server that will run on [http://localhost:9060/](http://localhost:9060/) (and has a proxy to [http://127.0.0.1:8080/api](http://127.0.0.1:8080/api) to access the Java back-end) - A BrowserSync task that will run on [http://localhost:9000/](http://localhost:9000/), which has a proxy to [http://localhost:9060/](http://localhost:9060/) (the Webpack "hot module reload" server), and which will synchronize the user's clicks/scrolls/inputs - The BrowserSync UI, which will be available on [http://localhost:3001/](http://localhost:3001/) **NOTE:** BrowserSync by default enables [ghostMode](https://browsersync.io/docs/options#option-ghostMode) which can create some confusion especially [when using multiple browser tabs](https://github.com/jhipster/generator-jhipster/issues/11116#issuecomment-589362814). To avoid this you can always turn off ghostMode. Some commented code is provided in `webpack.dev.js` for easy disabling of ghostMode. ### Running NPM Direct project dependencies are configured into `package.json`, but transitive dependencies are defined into the `package-lock.json` file, that get generated when `npm install` is run. It is advised to check [`package-lock.json`](https://docs.npmjs.com/files/package-lock.json) into source control, so that all team members of a project have the same versions of all dependencies. Running `npm install` again will regenerate the `package-lock.json` with the latest versions of transitive dependencies. ### Other NPM tasks Some `npm` commands used as an example. - `npm run lint`: check for code style issues in the TypeScript code - `npm run lint:fix`: try to automatically correct TypeScript lint issues - `npm run tsc`: compile the TypeScript code - `npm run test`: run unit tests with Jest - `npm run test:watch`: keep the Jest unit tests running, for live feedback when code is changed - `npm run e2e`: run "end to end" tests with Protractor (only works if the Protractor option has been selected when the project was generated) ## Using a database ### Running a database If you use a non-embedded database, like MySQL, MariaDB, PostgreSQL, MSSQL, MongoDB, Cassandra or Couchbase, you will need to install and configure that database. The easiest and recommended way with JHipster is to use Docker Compose. [Follow our Docker Compose guide here.](/docker-compose/) If you prefer to install and configure your database manually, you must create the schema and its user because Liquibase only creates the objects (tables, indexes, ...) in an existing schema. Then don't forget to configure your Spring Boot properties accordingly in your `src/main/resources/config/application-*.yml` files (for example your database URL, login and password). ### Using the H2 database in development If you choose the H2 database, you will have an in-memory database running inside your application, and you can access its console at [http://localhost:8080/h2-console](http://localhost:8080/h2-console) by default. To connect to the database, select the pre-configured options: * Driver Class: org.h2.Driver * JDBC URL: jdbc:h2:mem:jhipster * User name: \ * Password: \ ### Using MySQL, MariaDB or PostgreSQL in development This option is bit more complex than using H2, but you have a some important benefits: * Your data is kept across application restarts * Your application starts a little bit faster * You can use the great `./mvnw liquibase:diff` goal (see below) **Note**: for MySQL, you probably need to start your database with these options: * `--lower_case_table_names=1`: see the [MySQL Schema Object Names documentation](https://dev.mysql.com/doc/refman/8.0/en/identifier-case-sensitivity.html) * `--skip-ssl`: see the [MySQL Server Options documentation](https://dev.mysql.com/doc/refman/8.0/en/server-options.html#option_mysqld_ssl) * `--character_set_server=utf8`: see the [MySQL Server System Variables documentation](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_character_set_server) * `--explicit_defaults_for_timestamp` : see the [MySQL Server System Variables documentation](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_explicit_defaults_for_timestamp) The command is: ```shell mysqld --lower_case_table_names=1 --skip-ssl --character_set_server=utf8 --explicit_defaults_for_timestamp ``` ## Database updates If you add or modify a JPA entity, you will need to update your database schema. JHipster uses [Liquibase](http://www.liquibase.org) to manage the database updates, and stores its configuration in the `/src/main/resources/config/liquibase/` directory. There are 3 ways to work with Liquibase: * use the entity sub-generator * use the liquibase plugin * update the configuration files manually ### Database updates with the entity sub-generator If you use the [entity sub-generator](/creating-an-entity/), here is the development workflow: * Run the [entity sub-generator](/creating-an-entity/) * A new "change log" is created in your `src/main/resources/config/liquibase/changelog` directory, and has been automatically added to your `src/main/resources/config/liquibase/master.xml` file * Review this change log, it will be applied the next time you run your application ### Database updates with the liquibase plugin If you have chosen to use H2, MySQL, MariaDB or PostgreSQL in development, you can follow this section to automatically generate a changelog. *Note: If you are running H2 with in-memory persistence, you need to startup your application before running the liquibase commands.* #### Maven [Liquibase Hibernate](https://github.com/liquibase/liquibase-hibernate) is a Maven plugin that is configured in your `pom.xml`, and is independent from your Spring `application.yml` file, so if you have changed the default settings (for example, changed the database password), you need to modify both files. Here is the development workflow: 1. Modify your JPA entity (add a field, a relationship, etc.) 2. Skip changes in the regenerated liquibase file for that entity `config/liquibase/changelog/DATE_added_entity_ENTITY_NAME.xml` to avoid conflict with the soon to be generated changelog file bellow 3. Compile your application (this works on the compiled Java code, so don't forget to compile!) 4. Run `./mvnw liquibase:diff` (or `./mvnw compile liquibase:diff` to compile before) 5. A new "change log" is created in your `src/main/resources/config/liquibase/changelog` directory 6. Review this change log and add it to your `src/main/resources/config/liquibase/master.xml` file, so it is applied the next time you run your application #### Gradle [Liquibase gradle plugin](https://github.com/liquibase/liquibase-gradle-plugin) is a Gradle plugin that is configured in your `build.gradle`, and is independent from your Spring `application.yml` file, so if you have changed the default settings (for example, changed the database password), you need to modify both files. You can use the same workflow as for Maven except for the 4th step where you need to run `./gradlew liquibaseDiffChangelog -PrunList=diffLog`. ### Database updates by manually editing the change log If you prefer (or need) to do a database update manually, here is the development workflow: * Modify your JPA entity (add a field, a relationship, etc.) * Create a new "change log" in your `src/main/resources/config/liquibase/changelog` directory. The files in that directory are prefixed by their creation date (in yyyyMMddHHmmss format), and then have a title describing what they do. For example, `20141006152300_added_price_to_product.xml` is a good name. * Add this "change log" file in your `src/main/resources/config/liquibase/master.xml` file, so it is applied the next time you run your application If you want more information on using Liquibase, please go to [http://www.liquibase.org](http://www.liquibase.org). ## Internationalization Internationalization (or i18n) is a first-class citizen in JHipster, as we believe it should be set up at the beginning of your project (and not as an afterthought). Usage is as follows: - With Angular, thanks to [NG2 translate](https://github.com/ocombe/ng2-translate) and a specific JHipster component, which uses JSON files for translation - With React, thanks to a specific JHipster component, which works the same way as the Angular component, and uses the same files For example, to add a translation to the "First Name" field, add a "translate" attribute with a key: `` This key references a JSON document, which will return the translated string. Angular/React will then replace the "First Name" string with the translated version. If you want more information on using languages, read our [Installing new languages documentation](/installing-new-languages). --- ## File: docs/development/managing-server-errors.mdx --- title: Managing server errors slug: /managing-server-errors/ last_update: date: 2018-03-07T00:00:00-00:00 --- JHipster has first-class support for error handling: it provides error pages and custom mechanisms to handle both business and technical errors on the server-side. ## Error pages JHipster generates a Single-Page Application (SPA), but it still requires custom error pages for people who do not (or cannot) access the application. ### Dynamic error pages JHipster provides a generic error page, which is a [Thymeleaf](https://www.thymeleaf.org/) template, located at `src/main/resources/templates/error.html`. This page will display the server-side error message, for example if the user tried to access a non-existing page, it will display a 404 error, telling the user that the page wasn’t found. ### Static 404 error page JHipster provides a specific, static 404 error page located at `src/main/webapp/404.html`. By default, this page isn’t used by JHipster: it is here for projects using a proxy before JHipster (Apache/NGinx/etc.), so that the proxy can also display a 404 error page, even if the JHipster application isn’t available. It needs to be specifically configured on the front-end proxy. ## API errors To handle Spring MVC REST errors, JHipster uses [Zalando’s Problem Spring Web library](https://github.com/zalando/problem-spring-web), in order to provide rich, JSON-based error messages. In order to help the end-user, for each known problem this library will provide a link to a specific error page, that will give more details. Those links are configured in the `ErrorConstants` class, and point by default to this website. In your application, you should customize those links, and point them to your own API documentation. Here are the available error links: - [Problem with message](/problem/problem-with-message) - [Constraint violation](/problem/constraint-violation) - [Problem with a parameterized message](/problem/parameterized) - [Entity not found](/problem/entity-not-found) - [Invalid password](/problem/invalid-password) - [E-mail already used](/problem/email-already-used) - [Login already used](/problem/login-already-used) - [E-mail not found](/problem/email-not-found) --- ## File: docs/development/profiles.mdx --- title: Profiles slug: /profiles/ last_update: date: 2014-11-26T00:00:00-00:00 --- JHipster comes with two [Spring profiles](http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-profiles.html): * `dev` for development: it focuses on ease of development and productivity * `prod` for production: it focuses on performance and scalability Those profiles come in two different configurations: * The Maven/Gradle profiles are used at build time. For example `./mvnw -Pprod package` or `./gradlew -Pprod bootJar` will package a production application. * The Spring profiles work at run time. Some Spring beans will behave differently, depending on the profile. Spring profiles are set by Maven/Gradle, so we have a consistency between the two methods: you will have a `prod` profile on Maven/Gradle and Spring at the same time. _Note:_ Spring profiles are used to configure the JHipster application properties, so you should be interested in reading our [common application properties documentation](/common-application-properties). ## By default, JHipster will use the `dev` profile If you run the application without Maven/Gradle, launch the "Application" class (you can probably run it directly from your IDE by right-clicking on it). If you run the application with Maven, run `./mvnw` to use our Maven Wrapper, or `mvn` to use your own Maven installation. If you run the application with Gradle, run `./gradlew` to use our Gradle Wrapper, or `gradle` to use your own Gradle installation. When using Angular 2+ and Maven if you need to do a clean run with webpack compilation enabled for `dev` profile you can pass the `webapp` param as below ```shell ./mvnw -Pdev,webapp ``` **Note** Gradle automatically runs webpack compilation in `dev` profile if front end has changed (only at start up, for live reload use `npm start`). ## In production, JHipster has to run with the `prod` profile You can run JHipster in production directly using Maven or Gradle: * With Maven, run `./mvnw -Pprod` (or `mvn -Pprod`) * With Gradle, run `./gradlew -Pprod` (or `gradle -Pprod`) If you want to package your application as an executable WAR file, you should provide Maven or Gradle with a profile. E.g.,: * With Maven, run `./mvnw -Pprod package` (or `mvn -Pprod package`) * With Gradle, run `./gradlew -Pprod bootJar` (or `gradle -Pprod bootJar`) When you run your production application from a WAR file, the default is to use the same profile(s) as used during packaging. If you want to override this, you can explicitly provide an alternative in VM argument: ```shell java -jar jhipster-0.0.1-SNAPSHOT.jar --spring.profiles.active=... ``` ## Spring profiles switches JHipster comes with three additional profiles used as switches: * `api-docs` to enable swagger * `no-liquibase` to disable liquibase * `tls` to enable TLS security and use the HTTP/2 protocol (see [the TLS and HTTP/2 documentation](/tls)) These can be used along with both the `dev` and `prod` profiles. Please note that by default, the `api-docs` profile is not enabled in `prod` and enabled in `dev` by setting the `spring.profiles.group.dev` profile group property in `application.yml`. `api-docs`, `no-liquibase`, `tls` are only used at runtime: * In your IDE, run your main application class with `spring.profiles.active=dev,no-liquibase` (please note you need to include the `dev` or `prod` profile explicitly) * With a packaged application: `./java -jar jhipster-0.0.1-SNAPSHOT.war --spring.profiles.active=prod,no-liquibase` With Maven, you can also use those profiles directly: ```shell ./mvnw -Pprod,api-docs,no-liquibase ``` ```shell ./mvnw -Pdev,no-liquibase ``` With Gradle, you can also use those profiles directly: ```shell ./gradlew -Pprod -Papi-docs -Pno-liquibase ``` ```shell ./gradlew -Pno-liquibase ``` --- ## File: docs/development/separating-front-end-and-api.mdx --- title: Separating the front-end and the API server slug: /separating-front-end-and-api/ last_update: date: 2021-03-08T12:00:00-00:00 --- ## Introduction JHipster is a "full-stack" development tool, and its goal is to make you work efficiently with your front-end code (Angular/React) and your back-end code (Spring Boot). However, it is a common requirement to separate the front-end and the back-end codes, typically because they are developed by different teams and have a different lifecycle. **Please note** that this isn't the default JHipster way of working: this isn't complex to do, and works well, but this is an advanced topic. If you are getting started with JHipster, we recommend that you begin by using our standard way of working. ## Generating only a front-end or a back-end application You can choose to generate only a JHipster back-end or JHipster front-end application. At generation time, this is only a matter of choosing flags which are described in our [application generation documentation](/creating-an-app): - `jhipster --skip-client` will only generate a back-end application (this is typically what JHipster microservices are) - `jhipster --skip-server [options]` will only generate a front-end application (e.g. `jhipster --skip-server --db=sql --auth=jwt`) This should only work well for monoliths, as this doesn't make much sense for microservices (which have no front-end anyway) and gateways (which are monoliths with the Spring Cloud Gateway service enabled). ## Directory layout JHipster uses the standard Maven directory layout. When working on the back-end, you can read the [Maven standard directory layout documentation](https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html). When working on the front-end, there are 2 directories you need to know: - `src/main/webapp` is where the client application will be developed - `target/classes/static` is where your client application will be packaged If you have separate teams working on the front-end and back-end, you have two solutions: - Both teams can work on the same project. As the directories are separated, there won't have much conflicts between teams. To make things even cleaner, both teams could work on separate branches. - The front-end code can be stored in a specific Git project, and then imported into the main back-end project as a Git sub-module. This would require to move the client-side build scripts. ## HTTP requests routing and caching Once the front-end and back-end have been separated, the issue will be how to handle HTTP requests: - All API calls will use a `/api` prefix. If you are using Angular, there is also a specific `SERVER_API_URL` constant, defined in the `webpack.common.js` configuration, that can enrich this prefix. For example, you can use `"http://api.jhipster.tech:8081/"` as a back-end API server (If you do this, please read our documentation on CORS below). - `/index.html` should not be cached by the browser or server. - Calls to `/` that serve static assets (from the front-end) `/app` (which contains the client-side application) and `/content` (which contains the static content, like images and CSS) should be cached in production, as those assets are hashed. - Calls to `/i18n` can be cached but files itsefs not are hashed, url query string are used - Calls to a non-existent route should forward the request to `index.html`. This is normally handled in the backend through `ClientForwardController`. When deploying the client separately, this needs to be configured. See the [Angular](https://angular.io/guide/deployment#server-configuration) or [React](https://facebook.github.io/create-react-app/docs/deployment) documentation for several examples. ## Using BrowserSync In `dev` mode, JHipster uses BrowserSync for hot-reload of the front-end application. BrowserSync has a proxy ([here is its documentation](https://www.browsersync.io/docs/options#option-proxy)) that will route requests from `/api` to a back-end server (by default, `http://127.0.0.1:8080`). This only works in `dev` mode, but this is a very powerful way of accessing different API servers from the front-end. ## Using CORS CORS ([Cross-origin request sharing](https://wikipedia.org/wiki/Cross-origin_resource_sharing)) allow to access different back-end servers with the same front-end, without configuring a proxy. This is an easy-to-use solution, but it can be less secure in production. JHipster provides out-of-the-box a CORS configuration: - CORS can be configured using the `jhipster.cors` property, as defined in [the JHipster common application properties](/common-application-properties/) - It is enabled by default in `dev` mode for monoliths and gateways. It is turned off by default for microservices as you are supposed to access them through a gateway. - It is turned off by default in `prod` mode, for security reasons. ## Using NGinx Another solution to separate the front-end and back-end codes is to use a proxy server. This is very common in production, and some teams also use this technique in development. This configuration will change depending on your specific use-case, so this cannot be automated by the generator, here is below a working configuration. Create a `src/main/docker/nginx.yml` Docker Compose file: ```yaml version: '2' services: nginx: image: nginx:1.15-alpine volumes: - ./../../../target/static:/usr/share/nginx/html - ./nginx/site.conf:/etc/nginx/conf.d/default.conf ports: - "8000:80" ``` This Docker image will configure an NGinx server, that reads the static assets from `target/static`: this is where the JHipster front-end application is generated by default. In production, you will probably have a specific folder for this. It also reads a `./nginx/site.conf` file: this is a NGinx-specific configuration file. ### Configuration lambda Here is a sample `site.conf`: ``` server { listen 80; index index.html; server_name localhost; error_log /var/log/nginx/error.log; root /usr/share/nginx/html; location /api { proxy_pass http://api.jhipster.tech:8081/api; } location /management { proxy_pass http://api.jhipster.tech:8081/management; } location /swagger-resources { proxy_pass http://api.jhipster.tech:8081/swagger-resources; } location /v2 { proxy_pass http://api.jhipster.tech:8081/v2; } location /auth { proxy_pass http://api.jhipster.tech:8081/auth; } location / { try_files $uri $uri/ /index.html; } } ``` This configuration means that: - NGinx will run on port `80` - It will read the static assets in folder `/usr/share/nginx/html`, and - It will act as a proxy from `/api` to `http://api.jhipster.tech:8081/api` - Any unhandled requests will forward to `index.html` This configuration will require some tuning depending on your specific needs, but should be a good enough starting point for most applications. --- ## File: docs/development/tls.mdx --- title: Using TLS and HTTP/2 in development slug: /tls/ last_update: date: 2018-10-04T00:00:00-00:00 --- ## Introduction This page is for using TLS and HTTP/2 in development (mainly for testing purposes). For production configuration, please read the [security section in the production documentation](/production/#security). TLS is the protocol used when having an `https://` URL, and it is required in order to use HTTP/2 on modern browsers. It is useful to use those protocols when testing an application, mainly for performance reasons. ## Using TLS and HTTP/2 with Spring Boot JHipster has a specific configuration for configuring both TLS and HTTP/2 (see the [common application properties documentation](/common-application-properties)), and in order to make things even simpler: - JHipster generates a self-signed certificate at application generation - A specific `tls` profile is provided (see the [profiles documentation](/profiles)) In order to run JHipster with the provided self-signed certificate, with TLS and HTTP/2 enabled, you need to use the `tls` profile: * with Maven: `./mvnw -Pdev,tls` * with Gradle: `./gradlew -Ptls` The application will be available on `https://localhost:8080/`. As the certificate is self-signed, your browser will issue a warning, and you will need to ignore it (or import it) in order to access the application. ## Using TLS and HTTP/2 with Angular or React or Vue.js Instead of using `npm start` in order to run the front-end (with Webpack and BrowserSync), run `npm run start-tls`, and it will connect to the back-end running on `https://localhost:8080/`. Everything should then work the same as without TLS and HTTP/2. --- ## File: docs/development/using-angular.mdx --- title: Using Angular slug: /using-angular/ last_update: date: 2015-01-29T23:41:00-00:00 --- ## Tooling Angular is using TypeScript instead of JavaScript, and as a result some specific tooling is necessary to work efficiently with it. Our [development](/development) workflow for an Angular 2+ application is as below. 1. When you generate an application the files are created and at the end of generation `npm install` task is triggered. 2. Once `npm install` is complete it calls the `postInstall` script in `package.json`, this step triggers the `webapp:build` task. 3. Now you should have all files generated and compiled into the `www` folder inside the `target` or `build` folder based on the build tool (Maven or Gradle) selected. 4. Now run `./mvnw` or `./gradlew` to launch the application server and it should be available at [localhost:8080](localhost:8080) this also serves the client side code compiled from the above steps. 5. Now run `npm start` in a new terminal to launch Webpack dev-server with BrowserSync. This will take care of compiling your TypeScript code, and automatically reloading your browser. If you start making changes to the client side code without having `npm start` running, nothing will be reflected as the changes are not compiled so you need to either run `npm run webapp:build` manually after changes or have `npm start` running. You can also force Maven to run the `webapp:dev` task while starting by passing the `webapp` profile like `./mvnw -Pdev,webapp`. **Note** Gradle automatically runs webpack compilation in `dev` profile if front end has changed (only at start up, for live reload use `npm start`). Other available npm commands can be found in the `scripts` section of your project's `package.json` file. - To work on your code in your browser, we recommend using [Angular DevTools](https://angular.io/guide/devtools). Angular DevTools is a browser extension that provides debugging and profiling capabilities for Angular applications (**Note** Angular DevTools supports Angular v12 and later). ## Project Structure The JHipster client code can be found under `src/main/webapp`, and follows closely the [Angular style guide](https://angular.io/guide/styleguide). Please read this guide first if you have any question on our application structure, file names, TypeScript conventions... This style guide is endorsed by the Angular team, and provides best practices that every Angular project should follow. For Angular routes we follow a dash cased naming convention so that the URLs are clean and consistent. When you generate an entity the route names, route URLs and REST API endpoint URLs are generated according to this convention, also entity names are automatically pluralized where required. Here is the main project structure: ``` webapp β”œβ”€β”€ app - Your application β”‚ β”œβ”€β”€ account - User account management UI β”‚ β”œβ”€β”€ admin - Administration UI β”‚ β”œβ”€β”€ config - Some utilities files β”‚ β”œβ”€β”€ core - Common building blocks like configuration and interceptors β”‚ β”œβ”€β”€ entities - Generated entities (more information below) β”‚ β”œβ”€β”€ home - Home page β”‚ β”œβ”€β”€ layouts - Common page layouts like navigation bar and error pages β”‚ β”œβ”€β”€ main - Main page β”‚ β”œβ”€β”€ main.component.ts - Main application class β”‚ β”œβ”€β”€ login - Login page β”‚ β”œβ”€β”€ shared - Common services like authentication and internationalization β”‚ β”œβ”€β”€ app.module.ts - Application modules configuration β”‚ β”œβ”€β”€ app-routing.module.ts - Main application router β”œβ”€β”€ content - Static content β”‚ β”œβ”€β”€ css - CSS stylesheets β”‚ β”œβ”€β”€ images - Images β”‚ β”œβ”€β”€ scss - Sass style sheet files will be here if you choose the option β”œβ”€β”€ i18n - Translation files β”œβ”€β”€ swagger-ui - Swagger UI front-end β”œβ”€β”€ 404.html - 404 page β”œβ”€β”€ favicon.ico - Fav icon β”œβ”€β”€ index.html - Index page β”œβ”€β”€ robots.txt - Configuration for bots and Web crawlers ``` Using the [entity sub-generator](/creating-an-entity/) to create a new entity called `Foo` generates the following front-end files under `src/main/webapp`: ``` webapp β”œβ”€β”€ app β”‚ β”œβ”€β”€ entities β”‚ β”œβ”€β”€ foo - CRUD front-end for the Foo entity β”‚ β”œβ”€β”€ foo.component.html - HTML view for the list page β”‚ β”œβ”€β”€ foo.component.ts - Controller for the list page β”‚ β”œβ”€β”€ foo.model.ts - Model representing the Foo entity β”‚ β”œβ”€β”€ foo.module.ts - Angular module for the Foo entity β”‚ β”œβ”€β”€ foo.route.ts - Angular Router configuration β”‚ β”œβ”€β”€ foo.service.ts - Service which access the Foo REST resource β”‚ β”œβ”€β”€ foo-delete-dialog.component.html - HTML view for deleting a Foo β”‚ β”œβ”€β”€ foo-delete-dialog.component.ts - Controller for deleting a Foo β”‚ β”œβ”€β”€ foo-detail.component.html - HTML view for displaying a Foo β”‚ β”œβ”€β”€ foo-detail.component.ts - Controller or displaying a Foo β”‚ β”œβ”€β”€ foo-dialog.component.html - HTML view for editing a Foo β”‚ β”œβ”€β”€ foo-dialog.component.ts - Controller for editing a Foo β”‚ β”œβ”€β”€ foo-popup.service.ts - Service for handling the create/update dialog pop-up β”‚ β”œβ”€β”€ index.ts - Barrel for exporting everything β”œβ”€β”€ i18n - Translation files β”‚ β”œβ”€β”€ en - English translations β”‚ β”‚ β”œβ”€β”€ foo.json - English translation of Foo name, fields, ... β”‚ β”œβ”€β”€ fr - French translations β”‚ β”‚ β”œβ”€β”€ foo.json - French translation of Foo name, fields, ... ``` Please note that the default language translations would be based on what you have chosen during app generation. 'en' and 'fr' are shown here only for demonstration. ## Authorizations JHipster uses [the Angular router](https://angular.io/docs/ts/latest/guide/router.html) to organize the different parts of your client application. For each state, the required authorities are listed in the state's data, and when the authority list is empty it means that the state can be accessed anonymously. The authorities are also defined on the server-side in the class `AuthoritiesConstants.java`, and logically the client and server-side authorities should be the same. In the example below, the 'settings' state is designed to be accessed only by authenticated users who have `ROLE_ADMIN` authority: ```ts export const settingsRoute: Route = { path: 'sessions', component: SettingsComponent, title: 'global.menu.account.settings', data: { authorities: ['ROLE_ADMIN'], }, canActivate: [UserRouteAccessService] }; ``` Once those authorities are defined in the router, they can be used through `jhiHasAnyAuthority` directive within its 2 variants based on type of argument: - for a single string, the directive only displays the HTML component if the user has the required authority - for an array of strings, the directive displays the HTML component if the user has one of the listed authorities For example, the following text will only be displayed to users having the `ROLE_ADMIN` authority: ```html

Hello, admin user

``` For example, the following text will only be displayed to users having one of the `ROLE_ADMIN` or `ROLE_USER` authorities: ```html

Hello, dear user

``` *Please note* that those directives only show or hide HTML components on the client-side, and that you also need to secure your code on the server-side! ## The ng-jhipster library The ng-jhipster library is free and OSS, and available on [https://github.com/jhipster/ng-jhipster](https://github.com/jhipster/ng-jhipster). The ng-jhipster library contains utility functions and common components that are used by Angular 2+ applications. They include: - Validation directives - Internationalization components - Commonly-used pipes like capitalization, ordering and word truncation - Base64, date and pagination handling services - A notification system (see below) ### Notification System JHipster uses a custom notification system to send events from the server-side to the client-side, and has i18n-capable `JhiAlertComponent` and `JhiAlertErrorComponent` components which can be used throughout the generated applications. By default JHipster will show error notifications when there is an error caught from an HTTP response. To show a custom notification or alert, use the below methods after injecting the `AlertService` to your controller, directive or service. The shorthand methods `success`, `info`, `warning` and `error` will have a default timeout of 5 seconds, which can be configured: ```ts this.alerts.push( this.alertService.addAlert( { type: 'danger', msg: 'you should not have pressed this button!', timeout: 5000, toast: false, scoped: true }, this.alerts ) ); ``` ## Using Angular CLI Angular CLI is used to build and test JHipster applications. However, we added a custom webpack configuration file in order to improve the developer experience by adding BrowserSync, ESLint (Angular CLI is still on TSLint for now), merging JSON translation files and add notifications when build has completed or failed. ### Overview [Angular CLI](https://cli.angular.io/) is a tool to develop, scaffold and maintain Angular applications. JHipster generates the Angular CLI configuration file, so the Angular CLI workflows work with JHipster. This integration is done by generating a `angular.json` file in the application root folder and adding its dependencies in the `package.json` file. ### Usage ```shell ng help ``` ### Building You can use `ng build` to build your front-end, but we still recommend to use the provided NPM scripts such as `npm start`, `npm run build`, etc. Check our ["using in development" documentation](/development/) and our ["using in production" documentation](/production/). ### Generating Components, Directives, Pipes and Services You can use the `ng generate` (or `ng g`) command to generate Angular components: ```shell ng generate component my-new-component ng g component my-new-component # using the alias # Components support relative path generation # Go to src/app/feature/ and run ng g component new-cmp # your component will be generated in src/app/feature/new-cmp # but if you were to run ng g component ../newer-cmp # your component will be generated in src/app/newer-cmp ``` You can find all possible blueprints in the table below: Scaffold | Usage --- | --- [Component](https://github.com/angular/angular-cli/wiki/generate-component) | `ng g component my-new-component` [Directive](https://github.com/angular/angular-cli/wiki/generate-directive) | `ng g directive my-new-directive` [Pipe](https://github.com/angular/angular-cli/wiki/generate-pipe) | `ng g pipe my-new-pipe` [Service](https://github.com/angular/angular-cli/wiki/generate-service) | `ng g service my-new-service` [Class](https://github.com/angular/angular-cli/wiki/generate-class) | `ng g class my-new-class` [Guard](https://github.com/angular/angular-cli/wiki/generate-guard) | `ng g guard my-new-guard` [Interface](https://github.com/angular/angular-cli/wiki/generate-interface) | `ng g interface my-new-interface` [Enum](https://github.com/angular/angular-cli/wiki/generate-enum) | `ng g enum my-new-enum` [Module](https://github.com/angular/angular-cli/wiki/generate-module) | `ng g module my-module` ### Test For consistency purpose on JHipster application, tests are available through the `npm` command: ```shell npm test ``` ### i18n JHipster is using the `ngx-translate` dependency for translation purpose. Angular CLI i18n is based on the default Angular i18n support, which is incompatible with JHipster. ### Running the server If you prefer to use Angular CLI to develop you application, you can run your server directly by using its dedicated command. ```shell ng serve ``` ### Conclusion For more information about the Angular CLI, please visit the official website [https://cli.angular.io/](https://cli.angular.io/) --- ## File: docs/development/using-react.mdx --- title: Using React (with Redux) slug: /using-react/ last_update: date: 2018-04-02T23:41:00-00:00 --- This section refers to the JavaScript library **React** used with **Redux**. ## Project Structure The JHipster client code can be found under `src/main/webapp`, and follows closely the [Piotr Witek React style guide](https://github.com/piotrwitek/react-redux-typescript-guide/blob/master/README.md). Please read this guide first if you have any question on our application structure, file names, TypeScript conventions... For React routes we follow a dash cased naming convention so that the URLs are clean and consistent. When you generate an entity the route names, route URLs and REST API endpoint URLs are generated according to this convention, also entity names are automatically pluralized where required. Here is the main project structure: ``` webapp β”œβ”€β”€ app - Your application β”‚ β”œβ”€β”€ config - General configuration (redux store, middleware, etc.) β”‚ β”œβ”€β”€ entities - Generated entities β”‚ β”œβ”€β”€ modules - Main components directory β”‚ β”‚ β”œβ”€β”€ account - Account related components β”‚ β”‚ β”œβ”€β”€ administration - Administration related components β”‚ β”‚ β”œβ”€β”€ home - Application homepage β”‚ β”‚ └── login - Login related components β”‚ β”œβ”€β”€ shared - Shared elements such as your header, footer, reducers, models and util classes β”‚ β”œβ”€β”€ app.scss - Your global application stylesheet if you choose the Sass option β”‚ β”œβ”€β”€ app.css - Your global application stylesheet β”‚ β”œβ”€β”€ app.tsx - The application main class β”‚ β”œβ”€β”€ index.tsx - Index script β”‚ β”œβ”€β”€ routes.tsx - Application main routes β”‚ └── typings.d.ts - β”œβ”€β”€ i18n - Translation files β”œβ”€β”€ static - Contains your static files such as images and fonts β”œβ”€β”€ swagger-ui - Swagger UI front-end β”œβ”€β”€ 404.html - 404 page β”œβ”€β”€ favicon.ico - Fav icon β”œβ”€β”€ index.html - Index page β”œβ”€β”€ manifest.webapp - Application manifest └── robots.txt - Configuration for bots and Web crawlers ``` Using the [entity sub-generator](/creating-an-entity) to create a new entity called `Foo` generates the following front-end files under `src/main/webapp`: ``` webapp β”œβ”€β”€ app β”‚ └── entities β”‚ β”œβ”€β”€ foo - CRUD front-end for the Foo entity β”‚ β”‚ β”œβ”€β”€ foo-delete-dialog.tsx - Delete dialog component β”‚ β”‚ β”œβ”€β”€ foo-detail.tsx - Detail page component β”‚ β”‚ β”œβ”€β”€ foo-dialog.tsx - Creation dialog component β”‚ β”‚ β”œβ”€β”€ foo.reducer.ts - Foo entity reducer β”‚ β”‚ β”œβ”€β”€ foo.tsx - Entity main component β”‚ β”‚ └── index.tsx - Entity main routes β”‚ └── index.tsx - Entities routes └── i18n - Translation files β”œβ”€β”€ en - English translations β”‚ β”œβ”€β”€ foo.json - English translation of Foo name, fields, ... └── fr - French translations └── foo.json - French translation of Foo name, fields, ... ``` Please note that the default language translations would be based on what you have chosen during app generation. 'en' and 'fr' are shown here only for demonstration. ## Redux [Redux](https://redux.js.org/) is a predictable state container for JavaScript. It is used together with React to manage the state of your React components. Redux provides an object **store** used to store the whole state of your application. To access this store and therefore update your state components, the only way is to dispatch **actions** which describe the fact that an update is requested, then the **reducers** will define how the state is updated in response to these actions. Here is an example of a reducer: ```ts export const ACTION_TYPES = { FETCH_FOOS: 'foo/FETCH_FOOS', }; const initialState = { loading: false, foos: [], updateSuccess: false, updateFailure: false }; // Reducer export default (state = initialState, action) => { switch (action.type) { case REQUEST(ACTION_TYPES.FETCH_FOOS): return { ...state, updateSuccess: false, updateFailure: false, loading: true }; case FAILURE(ACTION_TYPES.FETCH_FOOS): return { ...state, loading: false, updateSuccess: false, updateFailure: true }; case SUCCESS(ACTION_TYPES.FETCH_FOOS): return { ...state, loading: false, updateSuccess: true, updateFailure: false, foos: action.payload.data }; default: return state; } }; ``` In order to access your store and update the current application state, you need to dispatch actions to the store as mentioned previously. Actions are JavaScript objects and must have a **type**, which describe what the action is going to perform and a usually they have also a **payload** which corresponds to data you want to pass to the store. Here is an action to access the store: ```ts const apiUrl = SERVER_API_URL + '/api/foos'; // Action export const getFoos = () => ({ type: ACTION_TYPES.FETCH_FOOS, payload: axios.get(apiUrl) }); ``` The action described above indicates that we want to retrieve all the Foo objects by sending a GET request. The action type will match Notice that the **export** keyword is used to able the connected component to use that action when necessary (for instance, everytime the component is updated). ## Authorizations Jhipster uses the [React router](https://github.com/ReactTraining/react-router) to organize the differents parts of your application. When it comes to routes that require authentication, the `PrivateRoute` component generated is used. This component will prevent any unauthenticated user from accessing a route. Here is an example of PrivateRoute usage: ```ts const Routes = () => (
); ``` As you can see, unauthenticated user can access `/` and `/login` but accessing `/account` requires to be logged in. Please note that PrivateRoute uses the `authentication.isAuthenticated` store value to know if the user is authenticated. ## Notification System JHipster uses [react-toastify](https://github.com/fkhadra/react-toastify) alerts for the notification system. By default JHipster will show success notifications whenever an entity is created/updated/deleted and error notifications when there is an error caught from the response. ## React JHipster library The [react-jhipster](https://github.com/jhipster/react-jhipster) lib provides utilities and generic services for a generated application. It handles i18n as well. --- ## File: docs/development/using-vue.mdx --- title: Using Vue slug: /using-vue/ last_update: date: 2019-03-27T23:41:00-00:00 --- This section refers to the JavaScript library **Vue.js**. ## Project Structure The JHipster client code can be found under `src/main/webapp`. Please read this guide first if you have any question on our application structure, file names, TypeScript conventions... Note that we use TypeScript in our generated Vue application following [vue-class-component](https://github.com/vuejs/vue-class-component) style and guidelines. For Vue routes we follow a dash cased naming convention so that the URLs are clean and consistent. When you generate an entity the route names, route URLs and REST API endpoint URLs are generated according to this convention, also entity names are automatically pluralized where required. Here is the main project structure: ``` webapp β”œβ”€β”€ app - Your application β”‚ β”œβ”€β”€ account - Account related components β”‚ β”œβ”€β”€ admin - Administration related components β”‚ β”œβ”€β”€ core - Main components such as Home, navbar, ... β”‚ β”œβ”€β”€ entities - Generated entities β”‚ β”œβ”€β”€ locale - I18n / translation related components β”‚ β”œβ”€β”€ router - Routing configuration β”‚ β”œβ”€β”€ shared - Shared elements such as your config, models and util classes β”‚ β”œβ”€β”€ app.component.ts - The application main class β”‚ β”œβ”€β”€ app.vue - The application main SFC component β”‚ β”œβ”€β”€ constants.ts - Global application constants β”‚ β”œβ”€β”€ main.ts - Index script, application entrypoint β”‚ └── shims-vue.d.ts β”œβ”€β”€ content - Contains your static files such as images and fonts β”œβ”€β”€ i18n - Translation files β”œβ”€β”€ swagger-ui - Swagger UI front-end β”œβ”€β”€ 404.html - 404 page β”œβ”€β”€ favicon.ico - Fav icon β”œβ”€β”€ index.html - Index page β”œβ”€β”€ manifest.webapp - Application manifest └── robots.txt - Configuration for bots and Web crawlers ``` Using the [entity sub-generator](/creating-an-entity) to create a new entity called `Foo` generates the following front-end files under `src/main/webapp`: ``` webapp β”œβ”€β”€ app β”‚ β”œβ”€β”€ entities β”‚ β”‚ └── foo - CRUD front-end for the Foo entity β”‚ β”‚ β”œβ”€β”€ foo-details.vue - Details SFC component β”‚ β”‚ β”œβ”€β”€ foo-detail.component.ts - Details page component β”‚ β”‚ β”œβ”€β”€ foo-update.vue - Creation / Update SFC component β”‚ β”‚ β”œβ”€β”€ foo-update.component.ts - Creation / Update component class β”‚ β”‚ β”œβ”€β”€ foo.vue - Entity main SFC component β”‚ β”‚ β”œβ”€β”€ foo.component.ts - Entity main component class β”‚ β”‚ └── foo.service.ts - Foo entity service β”‚ β”œβ”€β”€ router β”‚ β”‚ └── index.ts - Entity main routes configuration β”‚ └── shared β”‚ └── model β”‚ └── foo.model.ts - Entity model class └── i18n - Translation files β”œβ”€β”€ en - English translations β”‚ β”œβ”€β”€ foo.json - English translation of Foo name, fields, ... └── fr - French translations └── foo.json - French translation of Foo name, fields, ... ``` Please note that the default language translations would be based on what you have chosen during app generation. 'en' and 'fr' are shown here only for demonstration. ## Store using VuexStore Application will use a store [VuexStore](https://vuex.vuejs.org/guide/state.html) to maintain state within the application. This store is configured at startup in `app/config/config.ts:initVueXStore`. Please refer to Vuex documentation to add new states or mutations. The application will use the store to maintain: * User authentication information * Language and translation * Notification and alert information * Active profiles data ## Authorizations JHipster uses the [Vue router](https://router.vuejs.org/) to organize the differents parts of your application. When it comes to routes that require authentication, the meta `authorities` is used on desired route. This component will prevent any unauthenticated or unauthorized user from accessing a route. Here is an example of PrivateRoute usage: ```ts const Routes = () => [{ path: '/public', name: 'public', component: Public }, { path: '/private', name: 'Private', component: Private, meta: { authorities: ['ROLE_USER'] } }]; ``` As you can see, unauthenticated user can access `/public` but accessing `/private` requires at least to be logged in. Please note that the interceptor uses the `$store.getters.authenticated` store value to know if the user is authenticated. ## Validation system In order to perform form validation, we use [Vuelidate](https://vuelidate.netlify.com/) library. Besides adding validation constraints, several filters are already furnished and enable a full validation on form. Custom validation can be added as such: ```ts import { required } from 'vuelidate/lib/validators'; const mustBeCool = (value) => value.indexOf('cool') >= 0; const validations = { foo: { required, mustBeCool } }; @Component({ validations }) export default class FooComponent extends Vue { foo: string = null; } ``` ## Bootswatch theme Theming Bootstrap can be done directly using [Bootswatch](https://bootswatch.com) themes. We now provide questions during generation to pick one of the many themes served by Bootswatch. --- ## File: docs/development/problem/constraint-violation.mdx --- title: Error - constraint violation slug: /problem/constraint-violation/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: constraint violation ### Error description This is a generic JHipster error, that is displayed when there is a validation error, typically using [Bean Validation](http://beanvalidation.org/). The error message should tell you which constraint has been violated, and for which reason. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/email-already-used.mdx --- title: Error - e-mail already used slug: /problem/email-already-used/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is a an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: e-mail already used ### Error description This is a JHipster error that is used when the end-user tries to use an e-mail address that is already being used. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/email-not-found.mdx --- title: Error - e-mail not found slug: /problem/email-not-found/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is a an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: e-mail not found ### Error description This is a JHipster error that is used when the end-user tries to use an e-mail address that does not exist in the system. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/entity-not-found.mdx --- title: Error - entity not found slug: /problem/entity-not-found/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is a an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: e-mail not found ### Error description This is a generic JHipster error that is used when the end-user tries to use an entity that does not exist in the system. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/invalid-password.mdx --- title: Error - invalid password slug: /problem/invalid-password/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is a an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: invalid password ### Error description This is a JHipster error that is used when an invalid password is entered by the end-user. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/login-already-used.mdx --- title: Error - login already used slug: /problem/login-already-used/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is a an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: login already used ### Error description This is a JHipster error that is used when the end-user tries to use a login name that is already being used. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/parameterized.mdx --- title: Error - parameterized slug: /problem/parameterized/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is a an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: parameterized ### Error description This is a generic JHipster error, that comes with a message and one or several parameters. The message and its parameter(s) should tell you what the problem is. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/development/problem/problem-with-message.mdx --- title: Error - problem with a message slug: /problem/problem-with-message/ last_update: date: 2017-09-10T00:00:00-00:00 --- ## Welcome to the JHipster website! You probably found this page by clicking on an error message in an application that was developed with JHipster. JHipster is an application generator, which was used to develop the application you are using. You can find more information about JHipster by going to our [home page](/). Please find below some information on the error that happened. ## Error: problem with a message ### Error description This is a generic JHipster error, which comes with a message. The message should tell you what the problem is. ### How can this page be customized? Error pages are configured in each application's `ErrorConstants` class. If you want to provide your own error pages in your application, please modify this class accordingly. --- ## File: docs/environment/configuring-a-corporate-proxy.mdx --- title: Configuring a corporate proxy slug: /configuring-a-corporate-proxy/ last_update: date: 2016-08-18T08:00:00-00:00 --- When JHipster is used in a company, you probably will need to configure all tools to bypass the corporate proxy. You can try to configure the `HTTP_PROXY` and `HTTPS_PROXY` environment variables or use a tool like [Cntlm](http://cntlm.sourceforge.net/). But this probably won't be enough, so you will need to configure separately all the tools that are used with JHipster. ## Introduction Supposing your proxy is defined with: - username - password - host - port The resulting configuration is: `http://username:password@host:port` If you use [Cntlm](http://cntlm.sourceforge.net/), then your configuration would be: `127.0.0.1:3128`. Otherwise, follow the next steps to configure each tool individually. ## NPM configuration Use these commands: ```shell npm config set proxy http://username:password@host:port npm config set https-proxy http://username:password@host:port ``` Or you can edit directly your `~/.npmrc` file: ``` proxy=http://username:password@host:port https-proxy=http://username:password@host:port https_proxy=http://username:password@host:port ``` ## Git configuration Use these commands: ```shell git config --global http.proxy http://username:password@host:port git config --global https.proxy http://username:password@host:port ``` Or you can edit directly your `~/.gitconfig` file: ``` [http] proxy = http://username:password@host:port [https] proxy = http://username:password@host:port ``` ## Maven configuration Edit the `proxies` session in your `~/.m2/settings.xml` file: ```xml id true http username password host port local.net|some.host.com ``` ### Maven Wrapper Create a new file `.mvn/jvm.config` inside the project folder and set the properties accordingly: ``` -Dhttp.proxyHost=host -Dhttp.proxyPort=port -Dhttps.proxyHost=host -Dhttps.proxyPort=port -Dhttp.proxyUser=username -Dhttp.proxyPassword=password ``` ## Gradle configuration Add the below in your `gradle.properties` file and in your `gradle/wrapper/gradle-wrapper.properties` file if you are downloading the wrapper over a proxy If you want to set these properties globally then add it in `USER_HOME/.gradle/gradle.properties` file ```properties ## Proxy setup systemProp.proxySet="true" systemProp.http.keepAlive="true" systemProp.http.proxyHost=host systemProp.http.proxyPort=port systemProp.http.proxyUser=username systemProp.http.proxyPassword=password systemProp.http.nonProxyHosts=local.net|some.host.com systemProp.https.keepAlive="true" systemProp.https.proxyHost=host systemProp.https.proxyPort=port systemProp.https.proxyUser=username systemProp.https.proxyPassword=password systemProp.https.nonProxyHosts=local.net|some.host.com ## end of proxy setup ``` ## Docker ### Native Docker Depending on your OS, you have to edit a specific file (`/etc/sysconfig/docker` or `/etc/default/docker`). Then, you have to restart the docker service with: `sudo service docker restart`. It will not apply to systemd. See this [page from docker](https://docs.docker.com/engine/admin/systemd/#http-proxy) to configure the proxy. ### Docker with docker-machine You can create your docker-machine with: ```shell docker-machine create -d virtualbox \ --engine-env HTTP_PROXY=http://username:password@host:port \ --engine-env HTTPS_PROXY=http://username:password@host:port \ default ``` Or you can edit the file `~/.docker/machine/machines/default/config.json`. --- ## File: docs/environment/docker-compose.mdx --- title: Docker and Docker Compose slug: /docker-compose/ last_update: date: 2016-12-01T00:00:00-00:00 --- Using Docker and Docker Compose is highly recommended in development, and is also a good solution in production. Docker Compose is used by default in development, tests and CI scripts, which can be [disabled](#disabling). ## Description :::note This Docker configuration is used to run your generated application(s) inside a container image. It's completely different from the [Docker setup](/installation/) that JHipster also provides, which is for running the JHipster generator inside a container ::: JHipster provides a complete Docker support, in order to: - Facilitate development, as you can start a full infrastructure with a single command, even when using a complex microservices architecture - For people using Docker Swarm, deploying to production directly, as it uses the same Docker Compose configuration One great feature of using Docker Compose is that you can scale your containers, using the `docker-compose scale` command. This is very interesting if you use JHipster with [a microservices architecture](#building-and-running-a-docker-image-of-your-application). When generating your application, JHipster generates for you several Docker Compose configurations to help you run your application with third-party services, for example a database. Those files are located inside folder `src/main/docker/`. ## Prerequisites You have to install Docker and Docker Compose: - [Docker](https://docs.docker.com/installation/#installation) - [Docker Compose](https://docs.docker.com/compose/install) Docker now requires creating an account to the docker store to download Docker for Mac and Docker for Windows. To bypass this :::tip On Windows and Mac OS X, Kitematic is an easy-to-use graphical interface provided with the Docker Toolbox, which will makes using Docker a lot easier. ::: :::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 this directory to avoid any issues. ::: If you encounter the error `npm ERR! Error: EACCES: permission denied` when installing JHipster UML (or any unbundled package), your container may not have `sudo` installed (for instance, sudo isn't bundled with Ubuntu Xenial). __Solution 1__ The NPM documentation recommends not installing any NPM package as root. Follow the [official documentation](https://docs.npmjs.com/getting-started/fixing-npm-permissions) to fix this. __Solution 2__ - `docker container exec -u root -it jhipster bash`, - `npm install YOUR_PACKAGE`, - then exit and log into the container normally: `docker container exec -it jhipster bash` ## Building and running a Docker image of your application To build a Docker image of your application using [Jib](https://github.com/GoogleContainerTools/jib) connecting to the local Docker daemon: - NPM: `npm run java:docker`, on Apple Silicon: `npm run java:docker:arm64` - Maven: `./mvnw package -Pprod verify jib:dockerBuild` - Gradle: `./gradlew -Pprod bootJar jibDockerBuild` To build a Docker image of your application without Docker and push it directly into your Docker registry, run: - Maven: `./mvnw package -Pprod verify jib:build -Djib.to.image=/` - Gradle: `./gradlew -Pprod bootJar jib -Djib.to.image=/` If this doesn't work out of the box for you, refer to the Jib documentation for configurations details, specifically regarding how to set up authentication to a Docker registry: - [Jib maven plugin documentation](https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin#configuration) - [Jib gradle plugin documentation](https://github.com/GoogleContainerTools/jib/tree/master/jib-gradle-plugin#configuration) :::warning Due to the way Jib works, it will first try to pull the latest version of the base Docker image from the configured Docker registry. This is on purpose as in a CI environment you must ensure that you always build on top of the latest patched base image. However in a local environment, this might fail your build if jib cannot access the Docker registry. A workaround for this is to use the `--offline` flag and will fix the issue as long as jib has already pulled the base Docker image in its cache. With Maven, type: `./mvnw -Pprod package verify jib:dockerBuild --offline` With Gradle, type: `./gradlew -Pprod bootJar jibDockerBuild --offline` If jib has not already pulled the base Docker image in its cache, to do it, you need to modify the pom.xml (in case of Maven) or the docker.gradle (in case of Gradle) by adding `docker://` as prefix of your base image (at the "image" tag, nested in the "from" tag). Example: `docker://imagename:latest` In this way jib puts the image present in your local docker daemon in its cache. ::: To run this image, use the Docker Compose configuration located in the `src/main/docker` folder of your application: - `docker-compose -f src/main/docker/app.yml up` This command will start up your application and the services it relies on (database, search engine, Consul, JHipster Registry...). If you chose OAuth 2.0 for authentication, be sure to read our [Keycloak section on this documentation](#keycloak). ## Generating a custom Docker-Compose configuration for multiple applications If your architecture is composed of several JHipster applications, you can use the specific `docker-compose` sub-generator, which will generate a global Docker Compose configuration for all selected applications. This will allow you to deploy and scale your complete architecture with one command. To use the `docker-compose` subgenerator: - You need to have all your monolith(s), gateway(s) and microservices in the same directory. - Create another directory, for example `mkdir docker-compose`. - Go into that directory: `cd docker-compose`. - Run the sub-generator: `jhipster docker-compose`. - The sub-generator will ask you which application you want to have in your architecture, and if you want to setup monitoring with ELK or Prometheus. This will generate a global Docker Compose configuration, type `docker-compose up` to run it, and have all your services running at once. In the case of a microservice architecture, this configuration will also pre-configure Consul or JHipster Registry, that will configure your services automatically: - Those services will wait until the Consul (or JHipster Registry) is running to start. This can be configured in your `bootstrap-prod.yml` file using the `spring.cloud[.consul].config.fail-fast` and `spring.cloud[.consul].config.retry` keys. - The registry will configure your applications, for example it will share the JWT secret token between all services. - Scaling each service is done using Docker Compose, for example type `docker-compose scale test-app=4` to have 4 instances of application "test" running. Those instances will be automatically load-balanced by the gateway(s), and will automatically join the same Hazelcast cluster (if Hazelcast is your Hibernate 2nd-level cache). ## Working with databases ### MySQL, MariaDB, PostgreSQL, Oracle, MongoDB, Couchbase, Neo4j or Cassandra Running `docker-compose -f src/main/docker/app.yml up` already starts up your database automatically. If you only want to start your database, and not the other services, use the Docker Compose configuration of your database: - With MySQL: `docker-compose -f src/main/docker/mysql.yml up` - With MariaDB: `docker-compose -f src/main/docker/mariadb.yml up` - With PostgreSQL: `docker-compose -f src/main/docker/postgresql.yml up` - With Oracle: `docker-compose -f src/main/docker/oracle.yml up` - With MongoDB: `docker-compose -f src/main/docker/mongodb.yml up` - With Cassandra: `docker-compose -f src/main/docker/cassandra.yml up` - With Couchbase: `docker-compose -f src/main/docker/couchbase.yml up` - With Neo4j: `docker-compose -f src/main/docker/neo4j.yml up` ### MongoDB Cluster Mode If you want to use MongoDB with a replica set or shards and a shared configuration between them, you need to build and set up manually MongoDB images. Follow these steps to do so: - Build the image: `docker-compose -f src/main/docker/mongodb-cluster.yml build` - Run the database: `docker-compose -f src/main/docker/mongodb-cluster.yml up -d` - Scale the MongoDB node service (you have to choose an odd number of nodes): `docker-compose -f src/main/docker/mongodb-cluster.yml scale -mongodb-node=` - Init the replica for mongo config server: `docker exec -it -mongodb-config mongoΒ  --port 27019 --eval 'rs.initiate();'` - Init the replica set (parameter X is the number of nodes you input in the previous step, folder is the folder where the YML file is located, it's `docker` by default): `docker container exec -it _-mongodb-node_1 mongo --port 27018 --eval 'var param=, folder=""' init_replicaset.js` - Init the shard: `docker container exec -it _-mongodb_1 mongo --eval 'sh.addShard("rs1/_-mongodb-node_1:27018")'` - Build a Docker image of your application: `./mvnw -Pprod clean verify jib:dockerBuild` or `./gradlew -Pprod clean bootJar jibDockerBuild` - Start your application: `docker-compose -f src/main/docker/app.yml up -d -app` If you want to add or remove some MongoDB nodes, repeat step 3 and 4. ### Couchbase Cluster Mode If you want to use Couchbase with multiple nodes, you need to build and set up manually Couchbase images. Follow these steps to do so: - Build the image: `docker-compose -f src/main/docker/couchbase-cluster.yml build` - Run the database: `docker-compose -f src/main/docker/couchbase-cluster.yml up -d` - Scale the Couchbase node service (you have to choose an odd number of nodes): `docker-compose -f src/main/docker/couchbase-cluster.yml scale -couchbase-node=` - Build a Docker image of your application: `./mvnw -Pprod clean verify jib:dockerBuild` or `./gradlew -Pprod clean bootJar jibDockerBuild` - Start your application: `docker-compose -f src/main/docker/app.yml up -d -app` ### Cassandra Unlike the other databases, where the schema migrations are applied by the application itself, Cassandra schema migrations are applied by a dedicated Docker container. #### Cassandra in development To start a Cassandra cluster to run your application locally, you can use the docker_compose file for development use: `docker-compose -f src/main/docker/cassandra.yml up -d` Docker-compose will start 2 services: - `-cassandra`: a container with the Cassandra node contact point - `-cassandra-migration`: a container to automatically apply all CQLΒ migrations scripts (create the Keyspace, create the tables, all data migrations, ...) See the [Cassandra page](/using-cassandra/) for more information on how to add new CQL scripts without restarting the local cluster. #### Cassandra in production: The `app.yml` docker-compose file uses `cassandra-cluster.yml` to configure the cluster. The application starts after few seconds (see _JHIPSTER_SLEEP_ variable) to gives the time to the cluster to start and the migrations to be applied. One big difference between Cassandra and the other databases, is that you can scale your cluster with Docker Compose. To have X+1 nodes in your cluster, run: - `docker-compose -f src/main/docker/cassandra-cluster.yml scale -cassandra-node=X` ### Microsoft SQL Server If you want to use the MSSQL Docker image with JHipster, there are a few steps to follow: - Increase the RAM available to Docker to at least 3.25GB - Run the database: `docker-compose -f src/main/docker/mssql.yml up -d` - Create the database with a MSSQL client of your choice - Start your application: `docker-compose -f src/main/docker/app.yml up -d -app` ## Elasticsearch Running `docker-compose -f src/main/docker/app.yml up` already starts up your search engine automatically. If you only want to start your Elasticsearch node, and not the other services, use its specific Docker Compose configuration: - `docker-compose -f src/main/docker/elasticsearch.yml up` ## Sonar A Docker Compose configuration is generated for running Sonar: - `docker-compose -f src/main/docker/sonar.yml up` To analyze your code, run Sonar on your project: - With Maven: `./mvnw initialize sonar:sonar` - With Gradle: `./gradlew sonar` The Sonar reports will be available at: [http://localhost:9000](http://localhost:9000) ## Keycloak If you chose OAuth 2.0 as your authentication, Keycloak is used as the default identity provider. Running `docker-compose -f src/main/docker/app.yml up` starts up Keycloak automatically. To make Keycloak work, you need to add the following line to your hosts file (`/etc/hosts` on Mac/Linux, `c:\Windows\System32\Drivers\etc\hosts` on Windows). ``` 127.0.0.1 keycloak ``` This is because you will access your application with a browser on your machine (which name is localhost, or `127.0.0.1`), but inside Docker it will run in its own container, which name is `keycloak`. If you only want to start Keycloak, and not the other services, use its specific Docker Compose configuration: - `docker-compose -f src/main/docker/keycloak.yml up` ## Common commands ### List the containers You can use `docker container ps -a` to list all the containers ```shell $ docker container 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 ``` ### Docker stats for containers `docker container stats` or `docker container stats $(docker container ps --format={{.Names}})` to list all running containers with CPU, Memory, Networking I/O and Block I/O stats. ```shell $ docker container stats $(docker container ps --format={{.Names}}) CONTAINER CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS jhips-mysql 0.04% 221 MB / 7.966 GB 2.77% 66.69 kB / 36.78 kB 8.802 MB / 302.5 MB 37 00compose_msmongo-app_1 0.09% 965.6 MB / 7.966 GB 12.12% 121.3 kB / 54.64 kB 89.84 MB / 14.88 MB 35 00compose_gateway-app_1 0.39% 1.106 GB / 7.966 GB 13.89% 227.5 kB / 484 kB 117 MB / 28.84 MB 92 jhipster-registry 0.74% 1.018 GB / 7.966 GB 12.78% 120.2 kB / 126.4 kB 91.12 MB / 139.3 kB 63 gateway-elasticsearch 0.27% 249.1 MB / 7.966 GB 3.13% 42.57 kB / 21.33 kB 48.16 MB / 4.096 kB 58 00compose_jhips-app_1 0.29% 1.042 GB / 7.966 GB 13.08% 101.8 kB / 78.84 kB 70.08 MB / 13.5 MB 68 msmongo-mongodb 0.34% 44.8 MB / 7.966 GB 0.56% 49.72 kB / 48.08 kB 33.97 MB / 811 kB 18 gateway-mysql 0.03% 202.7 MB / 7.966 GB 2.54% 60.84 kB / 31.22 kB 27.03 MB / 297 MB 37 ``` ### Scale a container Run `docker-compose scale test-app=4` to have 4 instances of application "test" running. ### Stop containers `docker-compose -f src/main/docker/app.yml stop` You can also use directly Docker: `docker container stop ` When you stop a container, the data is not deleted, unless you delete the container. ### Delete a container Be careful! All data will be deleted: `docker container rm `

Memory Tweaking

In order to optimize memory usage for applications running in the container, you can setup Java memory parameters on `Dockerfile` or `docker-compose.yml` ### Adding memory parameters to Dockerfile Set the environment variable. ENV JAVA_OPTS=-Xmx512m -Xms256m ### Adding memory parameters to docker-compose.yml This solution is desired over Dockerfile. In this way, you have a single control point for your memory configuration on all containers that compose your application. Add the `JAVA_OPTS` into `environment` section. ```yaml environment: - (...) - JAVA_OPTS=-Xmx512m -Xms256m ``` Depending on the Docker base image, `JAVA_OPTS` won't work. In this case, try to use `_JAVA_OPTIONS` instead: ```yaml environment: - (...) - _JAVA_OPTIONS=-Xmx512m -Xms256m ``` ## Disabling Add to src/main/resources/application.yml or application-dev.yml depending on your application configuration. ```yaml spring: docker: compose: enabled: false ``` ## Alternatives - [Colima](https://github.com/abiosoft/colima#getting-started) --- ## File: docs/environment/installation.mdx --- title: Installing JHipster slug: /installation/ last_update: date: 2018-08-30T08:20:00-00:00 --- ## Installation types We provide 3 ways of working with JHipster. If in doubt, choose our 2nd option, "Local installation with NPM": - [JHipster Online](https://start.jhipster.tech/) is a way to generate an application without installing JHipster in the first place. - "Local installation with NPM" 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. - The "[Docker](https://www.docker.io/)" container, which brings you a lightweight container with JHipster installed. ## JHipster Online (for users wanting a simplified way to run JHipster) [JHipster Online](https://start.jhipster.tech/) allows you to generate JHipster applications, without having to install JHipster. This is intended for people trying JHipster for the first time, or who 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 NPM"), as you will still need Java (to run your application) and NPM (to manage your front-end code). In the future, we expect JHipster Online to provide more features. ## Local installation with NPM (recommended for normal users) ### Quick setup 1. Install Java 21 LTS or greater. We recommend you use [Eclipse Temurin builds](https://adoptium.net/temurin/releases/?version=21), as they are open source and free. 2. Install Node.js from [the Node.js website](http://nodejs.org/) (please use an LTS 64-bit version, non-LTS versions are not supported) 3. Install JHipster: `npm install generator-jhipster` 4. (optional) If you want to use a module or a blueprint (for instance from the [JHipster Marketplace](/modules/marketplace/)), install [Yeoman](https://yeoman.io/): `npm install yo` Now that JHipster is installed, your next step is to [create an application](/creating-an-app/) ### Optional installations 1. Install a Java build tool. * Whether you choose to use [Maven](http://maven.apache.org/) or [Gradle](http://www.gradle.org/), you normally don't have to install anything, as JHipster will automatically install the [Maven Wrapper](https://github.com/takari/maven-wrapper) or the [Gradle Wrapper](http://gradle.org/docs/current/userguide/gradle_wrapper.html) for you. * If you don't want to use those wrappers, go to the official [Maven website](http://maven.apache.org/) or [Gradle website](http://www.gradle.org/) to do your own installation. 2. Install Git from [git-scm.com](http://git-scm.com/). We recommend you also use a tool like [SourceTree](http://www.sourcetreeapp.com/) if you are starting with Git. * JHipster will try to commit your project to Git, if it is installed. * The [JHipster upgrade sub-generator](/upgrading-an-application/) requires to have Git installed. ### Additional information JHipster uses [Yeoman](http://yeoman.io/) for code generation. To find more information, tips and help, please have a look at [the Yeoman "getting starting" guide](http://yeoman.io/learning/index.html) before [submitting a bug](https://github.com/jhipster/generator-jhipster/issues?state=open). The configuration will be stored in a generated `.yo-rc.json` file, so it is **strongly** recommended not to generate a JHipster project in your HOME directory. If you did it, you won't be able to generate another project in a sub directory. To solve it, delete the `.yo-rc.json` file. ## Docker installation (for advanced users only) :::note This Docker image is for running the JHipster generator inside a container. It's completely different from the [Docker and Docker Compose configurations](/docker-compose/) that JHipster will generate, which goal is to run your generated application inside a container ::: ### Information JHipster has a specific [Dockerfile](https://github.com/jhipster/generator-jhipster/blob/main/Dockerfile), which provides a [Docker](https://www.docker.io/) image. It makes a Docker "Automated build" that is available on: [https://hub.docker.com/r/jhipster/jhipster/](https://hub.docker.com/r/jhipster/jhipster/) This image will allow you to run JHipster inside Docker. ### Prerequisites 1. **(Recommended) Docker Desktop:** the easiest way to build, run and test the dockerized apps. [Docker Desktop](https://docs.docker.com/desktop/) comes with graphical interface for managing containers/images/volumes, Docker developer tools, Kubernetes support and much more. 2. **Docker Engine:** client-server application with command line interface (CLI). Follow the [Docker Engine](https://docs.docker.com/engine/install/) installation instructions 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 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](http://askubuntu.com/a/477554) to do so. ### Usage on Linux/Mac Windows (with Docker) #### Pull the image Pull the latest JHipster Docker image: ```shell docker image pull jhipster/jhipster ``` Pull the development JHipster Docker image: ```shell docker image pull jhipster/jhipster:master ``` You can see all tags [here](https://hub.docker.com/r/jhipster/jhipster/tags/) #### 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: ```shell 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) ```shell 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 ``` :::tip If you have already started the container once before, you do not need to run the above command, you can start/stop the existing container. ::: #### Check if the container is running To check that your container is running, use the command: ```shell 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 run: `docker container stop jhipster` * And to start again, run: `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: 1. `docker container stop jhipster` 2. `docker container rm jhipster` 3. `docker image pull jhipster/jhipster` 4. `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 :::warning On Windows, you need to run the Docker Quick Terminal as Administrator to be able to create symlinks during the `npm install` step. ::: The easiest way to log into the running container is by executing following command: ```shell docker container exec -it bash ``` If you copy-pasted the above command to run the container, notice that you have to specify `jhipster` as the container name: ```shell 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: ```shell 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: ```shell cd /home/jhipster/app jhipster ``` Once your application is created, you can run all the normal gulp/bower/maven commands, for example: ```shell ./mvnw ``` **Congratulations! You've launched your JHipster app inside Docker!** On your machine, you should be able to: * Access the running application at `http://DOCKER_HOST:8080` * Get all the generated files inside your shared folder :::warning By default, Docker is not installed inside the `jhipster/jhipster` image. So you won't be able to: - use the docker-compose files - build a Docker image with the docker daemon (Maven goal: `jib:dockerBuild` or Gradle task: `jibDockerBuild`) However, you will be able to use [jib](https://github.com/GoogleContainerTools/jib)'s daemonless mode which can build a docker image and push it to a registry without access to a docker daemon (Maven goal: `jib:build` or Gradle task: `jibBuild`). But you will need to setup credentials to the docker registry as a pre-requisite of building the app. See the [Jib plugin configuration documentations](https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin#configuration) for more details. ::: --- ## File: docs/environment/configuring-ide/configuring-ide-eclipse-gradle.mdx --- title: Configuring Eclipse with Gradle slug: /configuring-ide-eclipse-gradle/ last_update: date: 2015-05-22T18:40:00-00:00 --- To get full Gradle support in eclipse you should install the [buildship plugin](https://gradle.org/eclipse/). For configuring the [JavaScript](/configuring-ide-eclipse) side you can follow the instructions for Maven. ## 1. Import your project as a Gradle project - Select ``File -> Import`` - Choose ``Gradle Project`` - Select your projects root directory - Click on ``Next`` and finish the wizard ## 2. Add apt generated source folder to build path When using buildship gradles default outputfolder is filtered and not visible in your workspace. Therefore you need to remove it from eclipse's resource filter setting. - Right click on your project and select ``Properties`` - Select ``Resources`` - Remove the entry ``build`` - Select ``Java Build Path`` - Click ``Add Folder...`` - Check the path ``build/generated/source/apt/main`` Make sure the new source folder contains the correctly generated mapper implementations when running JHipster via eclipse. --- ## File: docs/environment/configuring-ide/configuring-ide-eclipse.mdx --- title: Configuring Eclipse with Maven slug: /configuring-ide-eclipse/ last_update: date: 2015-05-22T18:40:00-00:00 --- Importing your JHipster application in Eclipse will require a few manual steps. You will need to do some configuration: - on the Maven side (for Maven users) - on the JavaScript side (so Eclipse can ignore a couple of folders for static files) ## 1. Import your project as a Maven project - Select File -> Import - Choose "Existing Maven Projects" - Select your project - Click on "Finish" At the end of the import phase, you can expect to see the below dialog. "Maven plugin connectors" are an extension for m2eclipse. That one should be installed and Eclipse will need to restart after completion. If you have installed it already, you will be good to go and do not need to do anything. __Note__: if you already have an existing JHipster project and have not installed the corresponding connector, you should see the below error: `Plugin execution not covered by lifecycle configuration: org.bsc.maven:maven-processor-plugin:2.2.4:process (execution: process, phase: generate-sources)` Select Quick Fix/Ctrl+1 (Cmd+1 on Mac) on the error marker and select "Discover new m2e connectors" ## 2. Excluding generated static folders At this stage you should not have any Java error but should still see some JavaScript errors. This is because you have some JavaScript files that Eclipse cannot parse properly. Those files are used at execution time only and do not need to be visible in your workspace. They should be excluded. ### Exclude the β€˜node_modules’ folder - Right-click on Project -> Properties -> Resource -> Resource Filters - Select: Exclude all, Applies to folders, Name matches node_modules - Press "Ok" ### Exclude 'app' from src/main/webapp - Right click on Project -> Properties -> Javascript -> Include path - Click on the β€œsource” tab and select your_project/src/main/webapp - Select β€œExcluded: (None) -> Edit -> Add multiple - Select `app` and click β€œOk” - The following folders should have been automatically excluded (if not, exclude them manually): - `bower_components` - `node_modules/` ### Maven IDE profile If you are using Maven, you need to activate the `IDE` profile in Eclipse. This is used for applying IDE-specific tweaks, which currently only includes applying the MapStruct annotation processor. - Right click on Project -> Properties -> Maven - In "Active Maven Profiles", type `dev,IDE` With this configuration, you will be using both the JHipster `dev` and `IDE` profiles. ### Configuring MapStruct plugins In case for the IDE correctly recognize the mapstruct code generator some more things needs to be done. You should use the plugin m2e-apt (https://marketplace.eclipse.org/content/m2e-apt). Installing the m2e-apt plugin, enable Eclipse to work along with mapstruct. Also you can install the plugin MapStruct Eclipse Plugin (https://marketplace.eclipse.org/content/mapstruct-eclipse-plugin) for help and tips from the IDE. --- ## File: docs/environment/configuring-ide/configuring-ide-idea.mdx --- title: Configuring Intellij IDEA slug: /configuring-ide-idea/ last_update: date: 2015-11-28T17:13:00-00:00 --- ## Open your project - Open your project normally - Maven should be detected, and your project will build automatically If you want more control on your setup, you can also choose "Import project". ## Exclude directories If you use Git, initialize your project (`git init && git add . && git commit -m 'Initial commit'`), Intellij IDEA will automatically exclude directories which are ignored by Git (so you don't have anything to do). To exclude directories manually: - Right-click on the `node_modules/` folder - Select "Mark Directory As" and select "Excluded" **Note:** If you are using Intellij IDEA Ultimate and would like to use IDEA to code the frontend you should **not** exclude `node_modules` folder. Otherwise you will not have any code assistance for the frontend code! ## Spring Support (not available in Community Edition) To add Spring support to many of the JHipster modules from a new project first go to `File β†’ Project Structure`. Then go to the Modules tab, click on the `+` button, and then click on "Spring" to add Spring code assistance to your project. It will tell you there are unmapped Spring configuration files, click on the `+` sign on the bottom right (not the original one) and select all the Spring files that belong to your project, clicking the folder is enough to select everything. After that click `OK`, and Spring should be configured with proper code assistance. Now click on the original `+` button which you used to add Spring in the first place, and add Hibernate. You do not need to add any files on this one, adding it there will give you Hibernate based code assistance. Remember to click `OK` on the Project structure dialog. You should now have Spring support for most of the codebase. You have to repeat this step every time you start a new project, as these settings are project-specific. ## Application "hot restart" with Spring Boot devtools [Spring Boot devtools](https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html) is configured by JHipster, and will "hot restart" your application when classes from your project are compiled. This is a must-have feature, as it makes your application updated on the fly. By default IntelliJ IDEA does not automatically compile files when the application is running. To enable the "Compile on save" feature: * Go to `File -> Settings -> Build, Execution, Deployment -> Compiler` and enable "Make project automatically" * Open the Action window : * Linux : `CTRL+SHIFT+A` * Mac OSX : `SHIFT+COMMAND+A` * Windows : `CTRL+ALT+SHIFT+/` * Enter `Registry...` and enable `compiler.automake.allow.when.app.running` Note: For IntelliJ IDEA version 2021.2 * Go to `File -> Settings -> Build, Execution, Deployment -> Compiler` and enable "Build project automatically" * Go to `File -> Advanced Settings -> Compiler` and enable "Allow auto-make to start even if developed application is currently running" ## Maven IDE profile If you are using Maven, you need to activate the `IDE` profile in IntelliJ. This is used for applying IDE-specific tweaks which currently only includes applying the MapStruct annotation processor. Open the "Maven Projects" tool window (View -> Tool Windows), check the `IDE` maven profile to activate it. ## Gradle In order to get the best out-of-the-box experience with Gradle you should delegate all [IDE build/run actions to Gradle](https://www.jetbrains.com/idea/whatsnew/#v2017-3-gradle) directly. With this setting annotation processing is automatically configured and you won't have duplicated classes when mixing IDE and cli builds. If you are using an older version ( < 2016.3) you have to enable annotation processing manually. --- ## File: docs/environment/configuring-ide/configuring-ide-netbeans.mdx --- title: Configuring Netbeans slug: /configuring-ide-netbeans/ last_update: date: 2016-08-20T18:40:00-00:00 --- Importing your JHipster application in NetBeans is straightforward. ## 1. Open your project - Select File -> Open Project - Browse and select your project's folder **That's All** : To run your project, do a right-click on the Application class (at the root of the package hierarchy) and select "Run File". --- ## File: docs/environment/configuring-ide/configuring-ide-visual-studio-code.mdx --- title: Configuring Visual Studio Code slug: /configuring-ide-visual-studio-code/ last_update: date: 2016-09-15T17:13:00-00:00 --- Visual Studio Code is an Open Source text editor made by Microsoft. It has excellent support for TypeScript, so many people want to use it for developing Angular 2 applications. ## Yeoman Support **Warning! At the time of this writing, this extension is broken** Visual Studio Code has a Yeoman extension, which should help you run JHipster commands. You can install it by using the Visual Studio Code marketplace: ## Java Code Support Visual Studio Code has a Java extension developed by Red Hat. It has a good Java support, using Maven or Gradle. You can install it by using the Visual Studio Code marketplace: ## Common tasks: compiling, running and packaging the code The Visual Studio Code Java extension can't be used to run commands: it can't compile, run the code, or package the application. For all those tasks, there are 2 solutions: - Use the terminal, for instance the internal terminal provided by Visual Studio Code, to run those commands manually - Use the [JHipster App](/jhipster-app), which offers a graphical interface for all those commands. **Note:** JHipster App is deprecated. ## Application "hot restart" with Spring Boot devtools [Spring Boot devtools](https://docs.spring.io/spring-boot/docs/current/reference/html/using-boot-devtools.html) is configured by JHipster, and will "hot restart" your application when classes from your project are compiled. This is a must-have feature, as it makes your application updated on the fly. To use it within Visual Studio Code, you need to: - Run your application in a terminal, typically by typing `./mvnw` - In another terminal, compile your application: `./mvnw compile` In the first terminal, your JHipster application should automatically redeploy, and use your new code. If you use the JHipster App, this is only a matter of clicking on 2 buttons (one for running the application, the other for compiling it), and your application will automatically redeploy in the same way. ## Custom settings For best performance, it's recommended to exclude some folders, in your project's `.vscode` folder create a `settings.json` file as below: ``` { // Configure glob patterns for excluding files and folders. "files.exclude": { "**/.git": true, "**/.gradle": true, "**/.idea": true, "**/.mvn": true, "**/.svn": true, "**/.hg": true, "**/.DS_Store": true }, // Configure glob patterns for excluding files and folders in searches. Inherits all glob patterns from the files.exclude setting. "search.exclude": { "**/node": true, "**/node_modules": true, "**/bower_components": true, "**/build": true, "**/target": true } } ``` --- ## File: docs/environment/configuring-ide/index.mdx --- title: Configuring your IDE slug: /configuring-ide/ last_update: date: 2015-05-22T18:40:00-00:00 --- JHipster projects can be developed without any IDE, all you need are a text editor and the command line. In order to be productive, people either use full-fledged IDEs or advanced text editors. Here is how you can configure them: - [Configuring Eclipse with Maven](/configuring-ide-eclipse) - [Configuring Eclipse with Gradle](/configuring-ide-eclipse-gradle) - [Configuring Intellij IDEA](/configuring-ide-idea) - [Configuring Visual Studio Code](/configuring-ide-visual-studio-code) - [Configuring Netbeans](/configuring-ide-netbeans) --- ## File: docs/environment/shell-plugins/fisher.mdx --- title: Using Fisher slug: /fisher/ last_update: date: 2018-10-20T18:40:00-00:00 --- If you are using Linux or Mac OS X, [fisher](https://github.com/jorgebucaran/fisher) is a great tool to manage your [fish shell](http://fishshell.com/) configuration. Some of the JHipster development team use fish shell with Fisher, and if you see people using shortcuts in their terminal, the magic comes from here! ## Fisher JHipster plugin The JHipster Fisher plugin is available on GitHub at [https://github.com/jhipster/jhipster-fisher-plugin](https://github.com/jhipster/jhipster-fisher-plugin). Currently it only adds shortcuts (full list [here](https://github.com/jhipster/jhipster-fisher-plugin/blob/main/conf.d/jhipster.aliases.fish)), but we welcome contributions to have better auto-completion! 1. Install it via ``fisher`` command: `fisher install jhipster/jhipster-fisher-plugin` For more details about [Fisher](https://github.com/jorgebucaran/fisher) have a look at their [usage](https://github.com/jorgebucaran/fisher#usage) section. --- ## File: docs/environment/shell-plugins/index.mdx --- title: JHipster Shell Plugins slug: /shell-plugins/ last_update: date: 2016-08-14T18:40:00-00:00 --- Shell plugins bring additional shortcuts for using JHipster, which makes it faster and easier to use. If you've seen people having a beautiful shell, with nice auto-completion and ultra-fast shortcuts, the magic comes from here! Currently there are two shell plugins: - [Oh-My-Zsh JHipster plugin](/oh-my-zsh) for [Oh-My-Zsh](https://ohmyz.sh/) - [Fisher JHipster plugin](/fisher) for [Fisher](https://github.com/jorgebucaran/fisher)