From 217cecb2e3ffbca775fd7ebc96132c18425b93f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 24 Oct 2024 09:27:34 +0300 Subject: [PATCH 1/5] Grammar fix --- docs/en/deployment/ssl.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/en/deployment/ssl.md b/docs/en/deployment/ssl.md index 3b95e96a66..8ad1bc177a 100644 --- a/docs/en/deployment/ssl.md +++ b/docs/en/deployment/ssl.md @@ -1,10 +1,10 @@ # Configuring SSL certificate(HTTPS) -A website needs an SSL certificate in order to keep user data secure, verify ownership of the website, prevent attackers from creating a fake version of the site, and gain user trust. +A website needs an SSL certificate to keep user data secure, verify ownership, prevent attackers from creating a fake version of the site, and gain user trust. -This document introduces how to get and use SSL certificate(HTTPS) for your application. +This document introduces how to get and use an SSL certificate (HTTPS) for your application. -## Get a SSL Certificate from a Certificate Authority +## Get an SSL Certificate from a Certificate Authority You can get a SSL certificate from a certificate authority (CA) such as [Let's Encrypt](https://letsencrypt.org/) or [Cloudflare](https://www.cloudflare.com/learning/ssl/what-is-an-ssl-certificate/) and so on. @@ -18,7 +18,7 @@ Once you have a certificate, you need to configure your web server to use it. Th You can create a self-signed certificate for testing purposes or internal use. -There is an article about [how to create a self-signed certificate](https://learn.microsoft.com/en-us/dotnet/core/additional-tools/self-signed-certificates-guide), If you are using IIS, you can use the following this document to [obtain a Certificate](https://learn.microsoft.com/en-us/iis/manage/configuring-security/how-to-set-up-ssl-on-iis#obtain-a-certificate) +There is an article about [how to create a self-signed certificate](https://learn.microsoft.com/en-us/dotnet/core/additional-tools/self-signed-certificates-guide); if you are using IIS, you can use the following document to [obtain a Certificate](https://learn.microsoft.com/en-us/iis/manage/configuring-security/how-to-set-up-ssl-on-iis#obtain-a-certificate) ## Common Problems @@ -31,4 +31,4 @@ This error may occur when using IIS. You need to trust your certificate by `Mana * [ABP IIS Deployment](./index.md) * [HTTPS in ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/security/enforcing-ssl) * [Let's Encrypt](https://letsencrypt.org/getting-started) -* [Cloudflare's Free SSL / TLS](https://www.cloudflare.com/application-services/products/ssl/) \ No newline at end of file +* [Cloudflare's Free SSL / TLS](https://www.cloudflare.com/application-services/products/ssl/) From b87776b14567c793dba90322c212013130ca2dc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 24 Oct 2024 09:28:05 +0300 Subject: [PATCH 2/5] Grammar fix --- docs/en/deployment/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/deployment/index.md b/docs/en/deployment/index.md index 50b6fd0938..3537e4593e 100644 --- a/docs/en/deployment/index.md +++ b/docs/en/deployment/index.md @@ -1,6 +1,6 @@ # Deployment -Deploying an ABP application is not different than deploying any .NET or ASP.NET Core application. You can deploy it to a cloud provider (e.g. Azure, AWS, Google Could) or on-premise server, IIS or any other web server. ABP's documentation doesn't contain much information on deployment. You can refer to your provider's documentation. +Deploying an ABP application is not different than deploying any .NET or ASP.NET Core application. You can deploy it to a cloud provider (e.g., Azure, AWS, Google Could) or an on-premise server, IIS or any other web server. ABP's documentation doesn't contain much information on deployment. You can refer to your provider's documentation. However, there are some topics that you should care about when you are deploying your applications. Most of them are general software deployment considerations, but you should understand how to handle them within your ABP based applications. We've prepared guides for this purpose and we suggest you to read these guides carefully before designing your deployment configuration. @@ -9,6 +9,6 @@ However, there are some topics that you should care about when you are deploying * [Configuring SSL certificate(HTTPS)](./ssl.md): Explains how to configure SSL certificate(HTTPS) for your application. * [Configuring OpenIddict](./configuring-openIddict.md): Notes for some essential configurations for OpenIddict. * [Configuring for Production](./configuring-production.md): Notes for some essential configurations for production environments. -* [Optimization for Production](./optimizing-production.md): Tips and suggestions for optimizing your application on production environments. +* [Optimization for Production](./optimizing-production.md): Tips and suggestions for optimizing your application in production environments. * [Deploying to a Clustered Environment](./clustered-environment.md): Explains how to configure your application when you want to run multiple instances of your application concurrently. * [Deploying Distributed / Microservice Solutions](./distributed-microservice.md): Deployment notes for solutions consisting of multiple applications and/or services. From ae6b6acb012b78a1dacc87a4d492d4d0b7470580 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 24 Oct 2024 09:32:55 +0300 Subject: [PATCH 3/5] Update configuring-openIddict.md --- docs/en/deployment/configuring-openIddict.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/deployment/configuring-openIddict.md b/docs/en/deployment/configuring-openIddict.md index b044bcb275..80fa74d898 100644 --- a/docs/en/deployment/configuring-openIddict.md +++ b/docs/en/deployment/configuring-openIddict.md @@ -26,7 +26,7 @@ public override void PreConfigureServices(ServiceConfigurationContext context) ## Development Environment -We've enabled `AddDevelopmentEncryptionAndSigningCertificate` by default on the development environment. It registers (and generates if necessary) a user-specific development encryption/development signing certificate. This is a certificate used for signing and encrypting the tokens and for **development environment only**. +`AddDevelopmentEncryptionAndSigningCertificate` is enabled by default on the development environment. It registers (and also generates, if necessary, a user-specific development encryption/development signing certificate. This is a certificate used for signing and encrypting the tokens and for **development environment only**. `AddDevelopmentEncryptionAndSigningCertificate` cannot be used in applications deployed on IIS or Azure App Service: trying to use them on IIS or Azure App Service will result in an exception being thrown at runtime (unless the application pool is configured to [load a user profile](https://learn.microsoft.com/en-us/iis/manage/configuring-security/application-pool-identities#user-profile)). @@ -34,7 +34,7 @@ To avoid that, consider creating self-signed certificates and storing them in th ## Production Environment -We've disabled `AddDevelopmentEncryptionAndSigningCertificate` in the production environment and tried to setup signing and encrypting certificates using `openiddict.pfx` file. +`AddDevelopmentEncryptionAndSigningCertificate` is disabled in production environment. Signing and encryption of certificates is done using `openiddict.pfx` file in production environment. You can use the `dotnet dev-certs https -v -ep openiddict.pfx -p 00000000-0000-0000-0000-000000000000` command to generate the `authserver.pfx` certificate. From 89c48ffdf3ab11493dfaeefdde3a4bb314118155 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 24 Oct 2024 11:50:10 +0300 Subject: [PATCH 4/5] grammar fixes --- docs/en/deployment/optimizing-production.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/en/deployment/optimizing-production.md b/docs/en/deployment/optimizing-production.md index 3803493be7..d6689b77fe 100644 --- a/docs/en/deployment/optimizing-production.md +++ b/docs/en/deployment/optimizing-production.md @@ -1,22 +1,26 @@ # Optimizing Your Application for Production Environments -ABP and the startup solution templates are configured well to get the maximum performance on production environments. However, there are still some points you need to pay attention to in order to optimize your system in production. In this document, we will mention some of these topics. +ABP and the startup solution templates are configured well to get the maximum performance on production environments. +However, you still need to pay attention to some points to optimize your system in production. +This document will explain optimization points for the production environment. ## Caching Static Contents -The following items are contents that can be cached in the client side (typically in the Browser) or in a CDN server: +The following items are contents that can be cached on the client side (typically in the Browser) or in a CDN server: -* **Static images** can always be cached. Here, you should be careful that if you change an image, use a different file name, or use a versioning query-string parameter, so the browser (or CDN) understands it's been changed. -* **CSS and JavaScript files**. ABP's [bundling & minification](../framework/ui/mvc-razor-pages/bundling-minification.md) system always uses a query-string versioning parameter and a hash value in the files names of the CSS & JavaScript files for the [MVC (Razor Pages)](../framework/ui/mvc-razor-pages/overall.md) UI. So, you can safely cache these files in the client side or in a CDN server. +* **Static images** can always be cached. Here, you should be careful that if you change an image, use a different file name, or use a versioning query-string parameter so the browser (or CDN) understands it's been changed. +* **CSS and JavaScript files**. ABP's [bundling & minification](../framework/ui/mvc-razor-pages/bundling-minification.md) system always uses a query-string versioning parameter and a hash value in the files names of the CSS & JavaScript files for the [MVC (Razor Pages)](../framework/ui/mvc-razor-pages/overall.md) UI. So you can safely cache these files on the client side or on a CDN server. * **Application bundle files** of an [Angular UI](../framework/ui/angular/quick-start.md) application. -* **[Application Localization Endpoint](../framework/api-development/standard-apis/localization.md)** can be cached per culture (it already has a `cultureName` query string parameter) if you don't use dynamic localization on the server-side. ABP's [Language Management](https://abp.io/modules/Volo.LanguageManagement) module provides dynamic localization. If you're using it, you can't cache that endpoint forever. However, you can still cache it for a while. Applying dynamic localization text changes to the application can delay for a few minutes, even for a few hours in a real life scenario. +* **[Application Localization Endpoint](../framework/api-development/standard-apis/localization.md)** can be cached per culture (it already has a `cultureName` query string parameter) if you don't use dynamic localization on the server-side. ABP's [Language Management](https://abp.io/modules/Volo.LanguageManagement) module provides dynamic localization. If you're using it, you can't cache that endpoint forever. However, you can still cache it for a while. Applying dynamic localization text changes to the application can delay a few minutes, even a few hours, in a real-life scenario. -There may be more ways based on your solution structure and deployment environment, but these are the essential points you should consider to client-side cache in a production environment. +There may be more ways based on your solution structure and deployment environment, but these are the essential points you should consider for client-side cache in a production environment. ## Bundling & Minification for MVC (Razor Pages) UI -ABP's [bundling & minification](../framework/ui/mvc-razor-pages/bundling-minification.md) system automatically bundles, minifies and versions your CSS and JavaScript files in production environment. Normally, you don't need to do anything, if you haven't disabled it yourself in your application code. It is important to follow the [bundling & minification](../framework/ui/mvc-razor-pages/bundling-minification.md) document and truly use the system to get the maximum optimization. +ABP's [bundling & minification](../framework/ui/mvc-razor-pages/bundling-minification.md) system automatically bundles, minifies and versions your CSS and JavaScript files in the production environment. +Normally, you don't need to do anything if you have not disabled it yourself in your application code. +It is important to follow the [bundling & minification](../framework/ui/mvc-razor-pages/bundling-minification.md) document and truly use the system to get the maximum optimization. ## Background Jobs -ABP's [Background Jobs](../framework/infrastructure/background-jobs) system provides an abstraction with a basic implementation to enqueue jobs and execute them in a background thread. ABP's Default Background Job Manager may not be enough if you are adding too many jobs to the queue and want them to be executed in parallel by multiple servers with a high performance. If you need these, you should consider to configure a dedicated background job software, like [Hangfire](https://www.hangfire.io/). ABP has a pre-built [Hangfire integration](../framework/infrastructure/background-jobs/hangfire.md), so you can switch to Hangfire without changing your application code. +ABP's [Background Jobs](../framework/infrastructure/background-jobs) system provides an abstraction with a basic implementation to enqueue jobs and execute them in a background thread. ABP's Default Background Job Manager may not be enough if you are adding too many jobs to the queue and want them to be executed in parallel by multiple servers with a high performance. If you need these, you should consider configuring a dedicated background job software, like [Hangfire](https://www.hangfire.io/). ABP has a pre-built [Hangfire integration](../framework/infrastructure/background-jobs/hangfire.md), so you can switch to Hangfire without changing your application code. From b32a0c407088ad498d40a727300a0cd564428965 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alper=20Ebi=C3=A7o=C4=9Flu?= <9526587+ebicoglu@users.noreply.github.com> Date: Thu, 24 Oct 2024 12:13:56 +0300 Subject: [PATCH 5/5] grammar fixes --- docs/en/deployment/configuring-production.md | 37 ++++++++++++-------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/docs/en/deployment/configuring-production.md b/docs/en/deployment/configuring-production.md index 0eb9b0ba81..1480f933fe 100644 --- a/docs/en/deployment/configuring-production.md +++ b/docs/en/deployment/configuring-production.md @@ -1,10 +1,13 @@ # Configuring Your Application for Production Environments -ABP has a lot of options to configure and fine-tune its features. They are all explained in their own documents. Default values for these options are pretty well for most of the deployment environments. However, you may need to care about some options based on how you've structured your deployment environment. In this document, we will highlight these kind of options. So, it is highly recommended to read this document in order to not have unexpected behaviors in your system in production. +ABP predefines the configurations for the best performance for common deployment scenarios. +However, depending on how you have structured your deployment environment, you may need to consider some extra options. This document highlights these options. +It is highly recommended that you read it to prevent unexpected behaviors in your production environment. ## Distributed Cache Prefix -ABP's [distributed cache infrastructure](../framework/fundamentals/caching.md) provides an option to set a key prefix for all of your data that is saved into your distributed cache provider. The default value of this option is not set (it is `null`). If you are using a distributed cache server that is shared by different applications, then you can set a prefix value to isolate an application's cache data from others. +ABP's [distributed cache infrastructure](../framework/fundamentals/caching.md) provides an option to set a key prefix for all your data saved into your distributed cache provider. +The default value of this option is not set (it is `null`). If you are using a distributed cache server that is shared by different applications, then you can set a prefix value to isolate an application's cache data from others. ````csharp Configure(options => @@ -13,19 +16,21 @@ Configure(options => }); ```` -That's all. ABP, then will add this prefix to all of your cache keys in your application as along as you use ABP's `IDistributedCache` or `IDistributedCache` services. See the [Caching documentation](../framework/fundamentals/caching.md) if you are new to distributed caching. +That's all! This prefix will be added to all cache keys in your application, as long as you use ABP's `IDistributedCache` or `IDistributedCache` services. +If you are new to distributed caching, check out the [caching documentation](../framework/fundamentals/caching.md). -> **Warning**: If you use ASP.NET Core's standard `IDistributedCache` service, it's your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it. + +> **Warning**: If you use ASP.NET Core's standard `IDistributedCache` [service](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.caching.distributed.idistributedcache), it is your responsibility to add the key prefix (you can get the value by injecting `IOptions`). ABP can not do it anymore. > **Warning**: Even if you have never used distributed caching in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your caching server is shared among multiple systems. -> **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed cache server. In such systems, all applications (or services) should normally use the same cache prefix, because you want all the applications to use the same cache data to have consistency between them. +> **Warning**: If you are building a microservice architecture, then you will have multiple applications that share the same distributed cache server. All applications (sub-services) in these systems should use the same cache prefix and cache values to have application-wide consistency. -> **Warning**: Some of ABP's startup templates are pre-configured to set a prefix value for the distributed cache. So, please check your application code if it is already configured. +> **Warning**: Some of ABP's startup templates are pre-configured to set a prefix value for the distributed cache. If your application code is already configured, please check it. ## Distributed Lock Prefix -ABP's [distributed locking infrastructure](../framework/infrastructure/distributed-locking.md) provides an option to set a prefix for all the keys you are using in the distributed lock server. The default value of this option is not set (it is `null`). If you are using a distributed lock server that is shared by different applications, then you can set a prefix value to isolate an application's lock from others. +ABP's [distributed locking infrastructure](../framework/infrastructure/distributed-locking.md) provides an option to set a prefix for all the keys you use in the distributed lock server. The default value of this option is not set (it is `null`). If you use a distributed lock server shared by different applications, you can set a prefix value to isolate an application's lock from others. ````csharp Configure(options => @@ -34,29 +39,31 @@ Configure(options => }); ```` -That's all. ABP, then will add this prefix to all of your keys in your application. See the [Distributed Locking documentation](../framework/infrastructure/distributed-locking.md) if you are new to distributed locking. +That's all! ABP will add this prefix to all of your keys in your application. See the [Distributed Locking documentation](../framework/infrastructure/distributed-locking.md) if you are new to distributed locking. > **Warning**: Even if you have never used distributed locking in your own codebase, ABP still uses it for some features. So, you should always configure this prefix if your distributed lock server is shared among multiple systems. > **Warning**: If you are building a microservice system, then you will have multiple applications that share the same distributed locking server. In such systems, all applications (or services) should normally use the same lock prefix, because you want to globally lock your resources in your system. -> **Warning**: Some of ABP's startup templates are pre-configured to set a prefix value for distributed locking. So, please check your application code if it is already configured. +> **Warning**: Some of ABP's startup templates are pre-configured to set a prefix value for distributed locking. Please check your application code to see if it has already been configured. ## Email Sender ABP's [Email Sending](../framework/infrastructure/emailing.md) system abstracts sending emails from your application and module code and allows you to configure the email provider and settings in a single place. -Email service is configured to write email contents to the standard [application log](../framework/fundamentals/logging.md) in development environment. You should configure the email settings to be able to send emails to users in your production environment. +For the development environment, ABP will not send real emails. The email service is configured to write email contents in the development environment's standard [application log](../framework/fundamentals/logging.md). By default, it will write to the `Logs.txt` in your host project's `Logs` folder. You should configure the email settings to be able to send emails to users in your production environment. -Please see the [Email Sending](../framework/infrastructure/emailing.md) document to learn how to configure its settings to really send emails. +See the [Sending Email](../framework/infrastructure/emailing.md) document to learn what settings to configure to send actual email without writing to the logs. > **Warning**: If you don't configure the email settings, you will get errors while trying to send emails. For example, the [Account module](../modules/account.md)'s *Password Reset* feature sends email to the users to reset their passwords if they forget it. ## SMS Sender -ABP's [SMS Sending abstraction](../framework/infrastructure/sms-sending.md) provides a unified interface to send SMS to users. However, its implementation is left to you. Because, typically a paid SMS service is used to send SMS, and ABP doesn't depend on a specific SMS provider. +ABP's [SMS Sending abstraction](../framework/infrastructure/sms-sending.md) provides a unified interface for sending SMS to users. +However, its implementation is left to you. Typically, a paid SMS service is used to send SMS, and ABP doesn't depend on a specific SMS provider. +> PRO users can use the [Twilio SMS module](../modules/twilio-sms.md) to send SMS. -So, if you are using the `ISmsSender` service, you must implement it yourself, as shown in the following code block: +In the following code-block you can see where to implement the `ISmsSender` service: ````csharp public class MySmsSender : ISmsSender, ITransientDependency @@ -89,11 +96,11 @@ Configure(options => }); ```` -Note that ABP CLI automatically sets the password to a random value on a new project creation. However, it is stored in the `appsettings.json` file and is generally added to your source control. It is suggested to use [User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) or [Environment Variables](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration) to set that value. +Note that ABP CLI automatically sets the password to a random value on new project creation. However, it is stored in the `appsettings.json` file and is generally added to your source control. It is suggested to use [User Secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) or [Environment Variables](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration) to set that value. ## Logging -ABP uses .NET's standard [Logging services](../framework/fundamentals/logging.md). So, it is compatible with any logging provider that works with .NET. ABP's startup solution templates come with [Serilog](https://serilog.net/) pre-installed and configured for you. It writes logs to file system and console with the initial configuration. File system is useful for development environment, but it is suggested you to use a different provider for your production environment, like Elasticsearch, database or any other provider that can properly work. +ABP uses .NET's standard [Logging services](../framework/fundamentals/logging.md). So, it is compatible with any logging provider that works with .NET. ABP's startup solution templates come with [Serilog](https://serilog.net/) pre-installed and configured for you. It writes logs to the file system and console with the initial configuration. The file system is useful for the development environment, but it is suggested you use a different provider for your production environment, like Elasticsearch, database or any other provider that can properly work. ## The Swagger UI