<%#
 Copyright 2019-2023 the original author or authors from the JHipster project

 This file is part of the JHipster project, see https://www.jhipster.tech/
 for more information.

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

      https://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-%>
<%#
 This is a fragment file, it will be merged into to root template if available.
 EJS fragments will process % delimiter tags in template and & delimiter tags in the merge process.
-%>
<&_ if (fragment.introSection) { -&>
This application was generated using the [NodeJS blueprint](https://github.com/jhipster/generator-jhipster-nodejs) of JHipster <%= jhipsterVersion %>, you can find documentation and help at [<%= documentationArchiveUrl %>](<%= documentationArchiveUrl %>). For any questions you can refer to the stream lead: [Angelo Manganiello](https://github.com/amanganiello90).
<%_ if (applicationTypeGateway || applicationTypeMicroservice) { _%>

This is a "<%= applicationType %>" application intended to be part of a microservice architecture, please refer to the [Doing microservices with JHipster][] page of the documentation for more information.
This application is configured for Service Discovery and Configuration with <% if (serviceDiscoveryEureka) { %>the JHipster-Registry<% } %><% if (serviceDiscoveryConsul) { %>Consul<% } %>. On launch, it will refuse to start if it is not able to connect to <% if (serviceDiscoveryEureka) { %>the JHipster-Registry at [http://localhost:8761](http://localhost:8761)<% } %><% if (serviceDiscoveryConsul) { %>Consul at [http://localhost:8500](http://localhost:8500)<% } %>.<% if (serviceDiscoveryEureka) { %> For more information, read our documentation on [Service Discovery and Configuration with the JHipster-Registry][].<% } %><% if (serviceDiscoveryConsul) { %> For more information, read our documentation on [Service Discovery and Configuration with Consul][].<% } %>
<%_ } _%>

<&_ } -&>

<&_ if (fragment.structureSection) { -&>
Node is required for generation and recommended for development. `package.json` is always generated for a better development experience with prettier, commit hooks, scripts and so on.

In the project root, JHipster generates configuration files for tools like git, prettier, husky, and others that are well known and you can find references in the web.

- `.yo-rc.json` - Yeoman configuration file
JHipster configuration is stored in this file at `generator-jhipster` key. You may find `generator-jhipster-*` for specific blueprints configuration.
- `.yo-resolve` (optional) - Yeoman conflict resolver
Allows to use a specific action when conflicts are found skipping prompts for files that matches a pattern. Each line should match `[pattern] [action]` with pattern been a [Minimatch](https://github.com/isaacs/minimatch#minimatch) pattern and action been one of skip (default if ommited) or force. Lines starting with `#` are considered comments and are ignored.
- `.jhipster/*.json` - JHipster entity configuration files
- `/<%- dockerServicesDir %>` - Docker configurations for the application and services that the application depends on
- `/<%- clientRootDir %>` - Web application.
- `/server/` - NodeJS server application.

<&_ } -&>

<&_ if (fragment.developmentSection) { -&>

<%_ if (authenticationTypeOauth2) { _%>
### OAuth 2.0 / OpenID Connect

Congratulations! You've selected an excellent way to secure your NHipster application. If you're not sure what OAuth and OpenID Connect (OIDC) are, please see [What the Heck is OAuth?](https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth)

To log in to your app, you'll need to have [Keycloak](https://keycloak.org) up and running. The JHipster Team has created a Docker container for you that has the default users and roles. Start Keycloak using the following command.

```
docker compose -f src/main/docker/keycloak.yml up
```

### Okta

If you'd like to use Okta instead of Keycloak, it's pretty quick using the [Okta CLI](https://cli.okta.com/). After you've installed it, run:

```shell
okta register
```

Then, in your JHipster app's directory, run `okta apps create` and select **JHipster**. This will set up an Okta app for you, create `ROLE_ADMIN` and `ROLE_USER` groups, create a `.okta.env` file with your Okta settings, and configure a `groups` claim in your ID token.

Run `source .okta.env` and start your app with Maven or Gradle. You should be able to sign in with the credentials you registered with.

If you're on Windows, you should install [WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10) so the `source` command will work.

If you'd like to configure things manually through the Okta developer console, see the instructions below.

First, you'll need to create a free developer account at <https://developer.okta.com/signup/>. After doing so, you'll get your own Okta domain, that has a name like `https://dev-123456.okta.com`.

Modify `<%= nodeServerRootDir %>/src/config/application.yml` to use your Okta settings.

```yaml
  ...
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://{yourOktaDomain}/oauth2/default
        registration:
          oidc:
            client-id: {clientId}
            client-secret: {clientSecret}
```

Create an OIDC App in Okta to get a `{clientId}` and `{clientSecret}`. To do this, log in to your Okta Developer account and navigate to **Applications** > **Add Application**. Click **Web** and click the **Next** button. Give the app a name you’ll remember, specify `http://localhost:<%- serverPort %>` as a Base URI, and `http://localhost:<%- serverPort %>/login/oauth2/code/oidc` as a Login Redirect URI. Click **Done**, then Edit and add `http://localhost:<%- serverPort %>` as a Logout redirect URI. Copy and paste the client ID and secret into your `application.yml` file.

Create a `ROLE_ADMIN` and `ROLE_USER` group and add users into them. Modify e2e tests to use this account when running integration tests. You'll need to change credentials in `<%= clientTestDir %>e2e/account/account.spec.ts` and `<%= clientTestDir %>e2e/admin/administration.spec.ts`.

Navigate to **API** > **Authorization Servers**, click the **Authorization Servers** tab and edit the default one. Click the **Claims** tab and **Add Claim**. Name it "groups", and include it in the ID Token. Set the value type to "Groups" and set the filter to be a Regex of `.*`.

After making these changes, you should be good to go! If you have any issues, please post them to [Stack Overflow](https://stackoverflow.com/questions/tagged/jhipster). Make sure to tag your question with "jhipster" and "okta".

<%_ } else if (authenticationTypeJwt) { _%>

### JWT authentication and authorization

Congratulations! You've selected an excellent way to secure your NHipster application. If you're not sure what JSON Web Token (JWT) is, please see [What the Heck is JWT?](https://jwt.io/introduction/)

Your app uses, to get and use the token, the `<%= nodeServerRootDir %>/src/config/application.yml` settings:

```yaml
  ...
  security:
    authentication:
        jwt:
            # This token must be encoded using Base64 and be at least 256 bits long (you can type `openssl rand -base64 64` on your command line to generate a 512 bits one)
            base64-secret: {yourSecret}
            # Token is valid 24 hours
            token-validity-in-seconds: 86400
            token-validity-in-seconds-for-remember-me: 2592000
```

You can use the default secret created from the app, or change it.
So to get a token, you have to pass a POST request on the _api/authenticate_ url with **UserLoginDTO** as body.
For this you can use **swagger ui** on **/api/v2/api-docs** path, or the client login page (if you have generated it).
<%_ } _%>

### Using NestJS CLI

You can also use [NestJS CLI][] to generate some custom server code.

For example, the following command:

    nest generate module my-module

will generate the file:

    create <%= nodeServerRootDir %>/src/my-component/my-component.module.ts


### Building and running

#### Running

```bash
<%= nodePackageManager %> run start:app
```

#### Building

```bash
<%= nodePackageManager %> run build:app
```

The build folder with all compiled sources will be **<%= nodeServerRootDir %>/dist**.

> For more explanation about full stack server/client build refer to [<%= nodeServerRootDir %>/README.md](<%= nodeServerRootDir %>/README.md)

<&_ } -&>

<&_ if (fragment.othersSection) { -&>

### Code quality using Sonar

Sonar is used to analyse code quality. You can start a local Sonar server (accessible on http://localhost:9001) with:

```
docker compose -f src/main/docker/sonar.yml up -d
```

Note: we have turned off forced authentication redirect for UI in [src/main/docker/sonar.yml](src/main/docker/sonar.yml) for out of the box experience while trying out SonarQube, for real use cases turn it back on.

You can run a Sonar analysis with using the [sonar-scanner](https://docs.sonarqube.org/display/SCAN/Analyzing+with+SonarQube+Scanner).
Then, run a Sonar analysis in the <%= nodeServerRootDir %> folder:

```sh
npm run sonar:scanner
```

For more information, refer to the [Code quality page][].

<&_ } -&>

<&_ if (fragment.referenceSection) { -&>
[Node.js]: https://nodejs.org/
[Webpack]: https://webpack.github.io/
[Jest]: https://facebook.github.io/jest/
[NestJS]: https://nestjs.com/
[NestJS CLI]: https://docs.nestjs.com/cli/usages
<&_ } -&>