From 02baa9e2847ac635ee97495ccd021da6865d16af Mon Sep 17 00:00:00 2001 From: nicolas63 Date: Sun, 27 Sep 2020 11:37:33 +0200 Subject: [PATCH 1/2] Added Introduction section on read the docs --- README.md | 1 + docs/Introduction/big-picture.md | 10 + docs/Introduction/getting-started.md | 53 ++++ docs/autobuild.bat | 1 + docs/getting-started.md | 398 --------------------------- docs/index.rst | 10 +- 6 files changed, 72 insertions(+), 401 deletions(-) create mode 100644 docs/Introduction/big-picture.md create mode 100644 docs/Introduction/getting-started.md create mode 100644 docs/autobuild.bat delete mode 100644 docs/getting-started.md diff --git a/README.md b/README.md index fe4f43d29..c44c17ca1 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ # generator-jhipster-dotnetcore [![NPM version][npm-image]][npm-url] +[![Documentation Status](https://readthedocs.org/projects/jhipsternet/badge/?version=latest)](https://jhipsternet.readthedocs.io/en/latest/?badge=latest) [![Generator Build Status][github-actions-generator-image]][github-actions-url] [![Integration JWT Build Status][github-actions-integ-jwt-image]][github-actions-url] [![Integration OAUTH Build Status][github-actions-integ-oauth-image]][github-actions-url] diff --git a/docs/Introduction/big-picture.md b/docs/Introduction/big-picture.md new file mode 100644 index 000000000..7656398a1 --- /dev/null +++ b/docs/Introduction/big-picture.md @@ -0,0 +1,10 @@ +## Big Picture + +JHipster is a well-known platform for generating modern application in java world. +JHipster provides a blueprints system that allows to override the default behavior of the generator + +JHipster.NET is a blueprint that overrides the back-end part, originally generated in spring boot, by back-end in asp.net core. For the front-end all the common language can be used (angular, react). + +In alpha version we have also the possibility to choose Blazor for the front. [Blazor as front issue](https://github.com/jhipster/jhipster-dotnetcore/issues/165) + +This blueprint it's an official blueprint of jhipster [official-blueprints](https://www.jhipster.tech/modules/official-blueprints/) \ No newline at end of file diff --git a/docs/Introduction/getting-started.md b/docs/Introduction/getting-started.md new file mode 100644 index 000000000..e317068d4 --- /dev/null +++ b/docs/Introduction/getting-started.md @@ -0,0 +1,53 @@ +## Getting Started + +### Prerequisites + +As this is a [JHipster](https://www.jhipster.tech/) blueprint, we expect you have JHipster and its related tools already installed: + +- [Installing JHipster](https://www.jhipster.tech/installation/) + +### Generate your first application + +Installation of the blueprint + +```bash +npm install -g generator-jhipster-dotnetcore +``` + +Call the generator + +```bash +jhipster --blueprints dotnetcore +``` + +After running this command you have few questions to answer, as Application name, authentication mode, client framework etc +Once it's done, you can build and run your application. + +```bash +dotnet run --verbosity normal --project ./src/YourAppName/YourAppName.csproj +``` + +Your first application is ready and you can now use it with default user like JHipster (admin admin or user user) + +Ok now you have an application but without entity. +JHipster allow you to add entity with cli or with jdl file (add link) +JHipster.NET have the same behavior. + +```bash +jhipster entity +``` + +Or with jdl + +```bash +jhipster import-jdl my_file.jdl +``` +You can edit jdl with https://start.jhipster.tech/jdl-studio/ + +You have now an application with CRUD operations on each new entities with potentially link between entities (one-to-one, many-to-one or many-to-many) + +Default configurations are availables in the generated project. As an example, a docker compose file is generated with monitoring solutions (influxdb telegraf and chronograf or grafana) + +The repository : [https://github.com/jhipster/jhipster-dotnetcore](https://github.com/jhipster/jhipster-dotnetcore) + +Sample project : [https://github.com/jhipster/jhipster-sample-app-dotnetcore](https://github.com/jhipster/jhipster-sample-app-dotnetcore) \ No newline at end of file diff --git a/docs/autobuild.bat b/docs/autobuild.bat new file mode 100644 index 000000000..6bcafb67c --- /dev/null +++ b/docs/autobuild.bat @@ -0,0 +1 @@ +sphinx-autobuild.exe . .\_build\html\ \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index fe4f43d29..000000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,398 +0,0 @@ -# generator-jhipster-dotnetcore -[![NPM version][npm-image]][npm-url] -[![Generator Build Status][github-actions-generator-image]][github-actions-url] -[![Integration JWT Build Status][github-actions-integ-jwt-image]][github-actions-url] -[![Integration OAUTH Build Status][github-actions-integ-oauth-image]][github-actions-url] -[![Dependency Status][daviddm-image]][daviddm-url] -[![Sonar Cloud Quality Gate][sonar-gate-image]][sonar-url] -[![Sonar Cloud Reliability Rate][sonar-reliability-image]][sonar-url] -[![Sonar Cloud Security Rate][sonar-security-image]][sonar-url] -[![Sonar Cloud Maintainability Rate][sonar-maintainability-image]][sonar-url] -[![Sonar Cloud Duplicated Code][sonar-duplication-image]][sonar-url] - -> JHipster blueprint, - -# Analysis of the sample project -https://github.com/jhipster/jhipster-sample-app-dotnetcore - -[![Sonar Cloud Quality Gate][sonar-sample-gate-image]][sonar-sample-url] -[![Sonar Cloud Coverage Rate][sonar-sample-coverage-image]][sonar-sample-coverage-url] -[![Sonar Cloud Reliability Rate][sonar-sample-reliability-image]][sonar-sample-url] -[![Sonar Cloud Security Rate][sonar-sample-security-image]][sonar-sample-url] -[![Sonar Cloud Maintainability Rate][sonar-sample-maintainability-image]][sonar-sample-url] -[![Sonar Cloud Duplicated Code][sonar-sample-duplication-image]][sonar-sample-url] - -# Introduction - -This is a [JHipster](https://www.jhipster.tech/) blueprint, that is meant to be used in a JHipster application. - -# Gitter - -https://gitter.im/JHipster-NET/jhipster-dotnetcore - -# Prerequisites - -As this is a [JHipster](https://www.jhipster.tech/) blueprint, we expect you have JHipster and its related tools already installed: - -- [Installing JHipster](https://www.jhipster.tech/installation/) - -# Installation - -## With NPM - -To install this blueprint: - -```bash -npm install -g generator-jhipster-dotnetcore -``` - -To update this blueprint: - -```bash -npm update -g generator-jhipster-dotnetcore -``` - -## With Yarn - -To install this blueprint: - -```bash -yarn global add generator-jhipster-dotnetcore -``` - -To update this blueprint: - -```bash -yarn global upgrade generator-jhipster-dotnetcore -``` - -# Usage - -To use this blueprint, run the below command - -```bash -jhipster --blueprints dotnetcore -``` - -## 🚦 What we have now - -✅ General App generation - -- `jhipster --blueprints dotnetcore` - - JWT : ✅ - - Oauth2 : ✅ - -✅ Entity generation - -- `jhipster entity ` - -✅ JDL Entity model support generation - -- `jhipster import-jdl my_file.jdl` - - - -## Running local Blueprint version for development - -During development of blueprint, please note the below steps. They are very important. - -1. Link your blueprint globally - -Note: If you do not want to link the blueprint(step 3) to each project being created, use NPM instead of Yarn as yeoman doesn't seem to fetch globally linked Yarn modules. On the other hand, this means you have to use NPM in all the below steps as well. - -```bash -cd dotnetcore -npm link -``` - -2. Link a development version of JHipster to your blueprint (optional: required only if you want to use a non-released JHipster version, like the master branch or your own custom fork) - -You could also use Yarn for this if you prefer - -```bash -cd generator-jhipster -npm link - -cd dotnetcore -npm link generator-jhipster -``` - -3. Create a new folder for the app to be generated and link JHipster and your blueprint there - -```bash -mkdir my-app && cd my-app - -npm link generator-jhipster-dotnetcore -npm link generator-jhipster (Optional: Needed only if you are using a non-released JHipster version) - -jhipster -d --blueprint dotnetcore - -``` - -## Running the generated app in a Docker container - -1. Build the Docker image of the app - -```bash -docker build -f "[Dockerfile path]" -t [An image name]:[A tag] "[Application root path]" -``` - -2. Run your image in a Docker container - -```bash -docker run -d -p [A host port]:80 [Image name]:[Image tag] -``` - -3. Open your favorite browser at ```localhost:[Chosen host port]``` and enjoy ! :whale: - -Docker compose file can be used to start the application with database as a service. To build images, run - -```bash -docker-compose -f docker/app.yml build -``` - -To start services, use - -```bash -docker-compose -f docker/app.yml up -``` - -In case of Oracle database, see [official documentation](https://github.com/oracle/docker-images/blob/master/OracleDatabase/SingleInstance/README.md) - - -## Generating Services - -You can use services to move business logic away from controllers. It also allows you to use DTOs. - -You can generate services using the entity generator: - -`jhipster entity newentity` - -Or by using JDL: - - `service all with serviceImpl except Employee, Job` - -Notice that only the service with interface option (serviceImpl) is enabled on this generator. - -### Extending and Customizing Services - -One common use case is to customize service classes to suit different business needs. When using the jhipster generator to edit an existing entity or upgrading the generator's version, changes to the generated service classes might be overwritten. Altough it is possible to make changes directly to generated service classes, It might get tricky keeping track of changes. - -Optionally, you can extend and customize service classes to avoid service class code overwriting. - -Example: -Add an Author entity with service generation enabled by using the generator's cli. -Then create the following class named `AuthorExtendedService.cs`: - -```csharp -namespace MyCompany.Domain.Services { - public class AuthorExtendedService : AuthorService, IAuthorService - { - public CountryExtendedService(ApplicationDatabaseContext applicationDatabaseContext) : base(applicationDatabaseContext) - { - } - - public override async Task Delete(long id) - { - // add custom business logic before delete - await base.Delete(id); - } - } -} -``` - -AuthorExtendedService class will override one specific method of its base class (or more if you wish) adding custom business logic and AuthorExtendedService class will be automatically be registered with the dotnet container. Any code using the IAuthorService dependency will use this class for its implementation. - -Currently the automatic registration strategy for class/interface is used only for service classes/interfaces and more details are explained below. - -### Automatic Service Registration In DI Container - -Under the hood this project uses reflection for assembly scanning to automatically register service classes/interfaces with dotnet's dependency injection container. Implementation details can be found at `ServiceStartup.cs` file located at `src/ProjectName/Configuration/` folder. - -The following steps are used to automatically register service classes and interfaces: -- Scan `ProjectName.Domain.Services.Interfaces` namespace (at `ProjectName.Domain` assembly) for service interfaces and `ProjectName.Domain.Services` namespace (at `ProjectName.Domain.Services` assembly) for service classes. -- Find matching classes and its interfaces using the "I" prefix convention for interface name. This step registers the generated service classes/interfaces since they use "I" interface prefix convention, but user-defined services and interfaces can also be automatically registered using this convention. -For example: JobService class matches IJobService interface, EmployeeService class matches IEmployeeService interface, MyNewService class matches IMyNewService interface, etc... -- Service class names ending with 'ExtendedService' have higher priority for registration on the DI container. This is useful to make sure that the class will be registered and will replace any existing DI registrations. -For example: if JobExtendedService class is present and implements IJobService, then replace existing registrations. - - -## Using DTOs - -Notice that this blueprint uses [AutoMapper](https://automapper.org/) to handle dto conversion instead of Java's mapstruct. - -Example using JDL: - - ```dto * with mapstruct``` - - See [JHispter's documentation](https://www.jhipster.tech/using-dtos/) for more details about using DTOs. - - -## Using database migrations - -If you had already run the application before creating your first migration, some database tables might be already -created automatically on application startup. -So you have the options of removing conflicting tables or editing the migration you just created. -If you wish to automatically apply database migrations when the application is started replace method -EnsureCreated() by Migrate() at DatabaseStartup.cs file. Be aware of the implications of doing so. -Currently it is up to the user to create migrations. - -1. Add EF Core cli tools - -With .net core 3.0 the cli tool for entity framework was removed from the core sdk so you need to install it globally. -You only need to do this once. See [Breaking changes included in EF Core 3.0](https://docs.microsoft.com/pt-br/ef/core/what-is-new/ef-core-3.0/breaking-changes#dotnet-ef) for reference. - -```bash -dotnet tool install --global dotnet-ef -``` - -If using Visual Studio follow the documentation on [Entity Framework Core tools reference - Package Manager Console in Visual Studio](https://docs.microsoft.com/pt-br/ef/core/miscellaneous/cli/powershell) - -2. Create the initial database migration - -```bash -dotnet ef migrations add InitialCreate --project YourProject.csproj -``` - -3. Update the database - -```bash -dotnet ef database update --project YourProject.csproj -``` - -Tips: -- Remember to change the connection string to point to your database at appsettings.json. -- It is a good practice to check your migration files and backup your database before running migrations. - - -# Running SonarQube - -## By Script : - -1. Run Sonar in container : ```docker-compose -f ./docker/sonar.yml up -d``` - -2. Wait container was up Run ```SonarAnalysis.ps1``` and go to http://localhost:9001 - -## Manually : - -1. Run Sonar in container : ```docker-compose -f ./docker/sonar.yml up -d``` - -2. Install sonar scanner for .net : - - ```dotnet tool install --global dotnet-sonarscanner``` - -3. Run ```dotnet sonarscanner begin /d:sonar.login=admin /d:sonar.password=admin /k:"YourProject" /d:sonar.host.url="http://localhost:9001" /s:"`pwd`/SonarQube.Analysis.xml"``` - -4. Build your application : ```dotnet build``` - -5. Publish sonar results : ```dotnet sonarscanner end /d:sonar.login=admin /d:sonar.password=admin``` - -6. Go to http://localhost:9001 - -# Monitoring your app - -1. Run container (uncomment chronograf and kapacitor if you would use it): ```docker-compose -f ./docker/monitoring.yml up -d``` - -2. Go to http://localhost:3000 (or http://localhost:8888 if you use chronograf) - -3. (Only for chronograf) Change influxdb connection string by ```YourApp-influxdb``` - -4. (Only for chronograf) Change kapacitor connection string by ```YourApp-kapacitor``` - -5. (Only for chronograf) You can now add dashboard (like docker), see your app log in Cronograf Log viewer and send alert with kapacitor - -# OAuth2 and OpenID Connect - -OAuth is a stateful security mechanism, like HTTP Session. Spring Security provides excellent OAuth 2.0 and OIDC support, and this is leveraged by JHipster. 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) - -## Keycloak - -[Keycloak](https://keycloak.org) is the default OpenID Connect server configured with JHipster. - -To log into your application, 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 ./docker/keycloak.yml up -``` - -The security settings in `appsettings.json` are configured for this image. - -``` -appsettings.json: - ... -"jhipster": { - "Security": { - "Authentication": { - "OAuth2": { - "Provider": { - "IssuerUri": "http://localhost:9080/auth/realms/jhipster", - "LogOutUri": "http://localhost:9080/auth/realms/jhipster/protocol/openid-connect/logout", - "ClientId": "web_app", - "ClientSecret": "web_app" - } -``` - -Keycloak uses an embedded H2 database by default, so you will lose the created users if you restart your Docker container. To keep your data, please read the [Keycloak Docker documentation](https://hub.docker.com/r/jboss/keycloak/). One solution, with keeping the H2 database, is to do the following: - -- Add a volume that will be persisted: `./keycloak-db:/opt/jboss/keycloak/standalone/data` -- Change the migration strategy from `OVERWRITE_EXISTING`, to `IGNORE_EXISTING` (in the command section) - -In production, it is required by Keycloak that you use HTTPS. There are several ways to achieve this, including using a reverse proxy or load balancer that will manage HTTPS. We recommend that you read the [Keycloak HTTPS documentation](https://www.keycloak.org/docs/latest/server_installation/index.html#setting-up-https-ssl) to learn more about this topic. - -## Okta - -If you'd like to use Okta instead of Keycloak, you'll need to change a few things. First, you'll need to create a free developer account at . After doing so, you'll get your own Okta domain, that has a name like `https://dev-123456.okta.com`. - -Modify `appsettings.json` to use your Okta settings. Hint: replace `{yourOktaDomain}` with your org's name (e.g., `dev-123456.okta.com`). - -``` -appsettings.json: - ... -"jhipster": { - "Security": { - "Authentication": { - "OAuth2": { - "Provider": { - "IssuerUri": "https://{yourOktaDomain}/oauth2/default", - "LogOutUri": "https://{yourOktaDomain}/oauth2/default/v1/logout", - "ClientId": "client_id", - "ClientSecret": "client_secret" - } -``` - -Create an OIDC App in Okta to get a `{client-id}` and `{client-secret}`. 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, and specify `http://localhost:[port]/login/oauth2/code/oidc` as a Login redirect URI. Click **Done**, then edit your app to add `http://localhost:[port]` as a Logout redirect URI. Copy the client ID and secret into your `application.yml` file. - -Create a `ROLE_ADMIN` and `ROLE_USER` group (**Users** > **Groups** > **Add Group**) and add users to them. You can use the account you signed up with, or create a new user (**Users** > **Add Person**). Navigate to **API** > **Authorization Servers**, and click on the `default` server. 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 `.*`. Click **Create**. - -Add Claim - -# License - -Apache-2.0 © [Daniel Petisme]() - - -[npm-image]: https://img.shields.io/npm/v/generator-jhipster-dotnetcore.svg -[npm-url]: https://npmjs.org/package/generator-jhipster-dotnetcore -[daviddm-image]: https://david-dm.org/jhipster/jhipster-dotnetcore.svg?theme=shields.io -[daviddm-url]: https://david-dm.org/jhipster/jhipster-dotnetcore -[github-actions-generator-image]: https://github.com/jhipster/jhipster-dotnetcore/workflows/Generator/badge.svg?branch=master -[github-actions-integ-oauth-image]: https://github.com/jhipster/jhipster-dotnetcore/workflows/Test%20Integration%20OAUTH/badge.svg?branch=master -[github-actions-integ-jwt-image]: https://github.com/jhipster/jhipster-dotnetcore/workflows/Test%20Integration%20JWT/badge.svg?branch=master -[github-actions-url]: https://github.com/jhipster/jhipster-dotnetcore/actions -[sonar-url]: https://sonarcloud.io/dashboard?branch=master&id=jhipster_jhipster-dotnetcore -[sonar-coverage-url]: https://sonarcloud.io/component_measures?branch=master&id=jhipster_jhipster-dotnetcore&metric=coverage&view=list -[sonar-gate-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-dotnetcore&metric=alert_status -[sonar-coverage-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-dotnetcore&metric=coverage -[sonar-reliability-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-dotnetcore&metric=reliability_rating -[sonar-security-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-dotnetcore&metric=security_rating -[sonar-maintainability-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-dotnetcore&metric=sqale_rating -[sonar-duplication-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-dotnetcore&metric=duplicated_lines_density - -[sonar-sample-url]: https://sonarcloud.io/dashboard?branch=master&id=jhipster_jhipster-sample-app-dotnetcore -[sonar-sample-coverage-url]: https://sonarcloud.io/component_measures?branch=master&id=jhipster_jhipster-sample-app-dotnetcore&metric=coverage&view=list -[sonar-sample-gate-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-sample-app-dotnetcore&metric=alert_status -[sonar-sample-coverage-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-sample-app-dotnetcore&metric=coverage -[sonar-sample-reliability-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-sample-app-dotnetcore&metric=reliability_rating -[sonar-sample-security-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-sample-app-dotnetcore&metric=security_rating -[sonar-sample-maintainability-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-sample-app-dotnetcore&metric=sqale_rating -[sonar-sample-duplication-image]: https://sonarcloud.io/api/project_badges/measure?branch=master&project=jhipster_jhipster-sample-app-dotnetcore&metric=duplicated_lines_density diff --git a/docs/index.rst b/docs/index.rst index 91f04e4ee..04b97f3ba 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,11 +3,15 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to JHipster.NET's documentation! +Welcome to JHipster.NET documentation! ======================================== +Thanks for taking a look at the JHipster.NET documentation. Please use the left hand nav to get around. I would suggest taking a look at introduction first. + .. toctree:: :maxdepth: 1 - :caption: Getting Started + :hidden: + :caption: Introduction - getting-started + Introduction/big-picture + Introduction/getting-started From fbb57a117cac3330934a3c1c4a2e6dc3d9422e58 Mon Sep 17 00:00:00 2001 From: nicolas63 Date: Sun, 27 Sep 2020 15:22:05 +0200 Subject: [PATCH 2/2] Added link to the docs --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c44c17ca1..586c30843 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,11 @@ [![Sonar Cloud Maintainability Rate][sonar-maintainability-image]][sonar-url] [![Sonar Cloud Duplicated Code][sonar-duplication-image]][sonar-url] -> JHipster blueprint, +> JHipster blueprint + +Documentation and information about `JHipster.NET ` is available [here](https://jhipsternet.readthedocs.io/en/latest/) + +Full documentation and information about JHipster is available [here](https://www.jhipster.tech/) # Analysis of the sample project https://github.com/jhipster/jhipster-sample-app-dotnetcore