From 6a3ac5ab38729157768301e6d0075be21ca6e27a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?O=C4=9Fuzhan=20A=C4=9F=C4=B1r?= <90545225+oguzhanagir@users.noreply.github.com> Date: Tue, 14 Jul 2026 11:33:07 +0300 Subject: [PATCH] Enhance setup page documentation to clarify database startup wait behavior --- docs/en/Features-Angular-Setup-Page.md | 2 ++ docs/en/Features-Mvc-Core-Setup-Page.md | 8 +++++ docs/en/Features-Rate-Limiting.md | 2 ++ docs/en/Features-React-Setup-Page.md | 2 ++ .../Infrastructure-Core-Mvc-Configuration.md | 36 ++++++++++++++++++- 5 files changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/en/Features-Angular-Setup-Page.md b/docs/en/Features-Angular-Setup-Page.md index cdd05fa0..dcf5da63 100644 --- a/docs/en/Features-Angular-Setup-Page.md +++ b/docs/en/Features-Angular-Setup-Page.md @@ -4,6 +4,8 @@ ASP.NET Zero application can be set-up using install page. This page is develope Just note that, this page is only visible when the database is not created. If the database is created, you will be redirected to login page. +Since the server application and the database server often start together (for example after a machine reboot), the server application waits for the database server for a short while before it starts, so that a database that is simply slow to start is not mistaken for a missing one. See [Waiting for the Database on Startup](Infrastructure-Core-Mvc-Configuration#waiting-for-the-database-on-startup) if you need to change how long it waits. + install page ## Next diff --git a/docs/en/Features-Mvc-Core-Setup-Page.md b/docs/en/Features-Mvc-Core-Setup-Page.md index d271acd0..e700d699 100644 --- a/docs/en/Features-Mvc-Core-Setup-Page.md +++ b/docs/en/Features-Mvc-Core-Setup-Page.md @@ -4,6 +4,14 @@ ASP.NET Zero application can be set-up using install page. This page is develope install page +## When the Setup Page Is Shown + +The setup page is only meant for applications that do not have a database yet. As long as the database is missing, the application redirects you to the setup page instead of the normal pages. + +If your database already exists but your database server was simply not ready when the application started, you do not need to reinstall anything. The application keeps checking, and as soon as the database becomes available it stops redirecting to the setup page. Refresh the page and you will be taken to the login page as usual. + +Since your application and your database server often start together (for example after a machine reboot), the application also waits for the database server for a short while before it starts, so that it does not end up in setup mode for no reason. See [Waiting for the Database on Startup](Infrastructure-Core-Mvc-Configuration#waiting-for-the-database-on-startup) if you need to change how long it waits. + ## Next - [Web Host Project](Features-Mvc-Core-Web-Host-Project) \ No newline at end of file diff --git a/docs/en/Features-Rate-Limiting.md b/docs/en/Features-Rate-Limiting.md index dde33c5f..8f9c122c 100644 --- a/docs/en/Features-Rate-Limiting.md +++ b/docs/en/Features-Rate-Limiting.md @@ -128,6 +128,8 @@ Endpoint patterns support wildcard matching with `*`. For example: Rate limiting policies are cached in memory for optimal performance. The cache is automatically invalidated whenever a policy is created, updated, deleted, or toggled, and when the global rate limiting setting is changed. This means policy changes take effect immediately without requiring an application restart. +If the policies cannot be read because the database is temporarily unreachable, rate limiting is skipped for that request and a warning is written to the log, instead of failing the request. Requests keep being served, and rate limiting starts working again by itself as soon as the database is available. + ## Permissions Rate limiting management is controlled by the following permissions under **Administration > Rate Limiting**: diff --git a/docs/en/Features-React-Setup-Page.md b/docs/en/Features-React-Setup-Page.md index 1952f9e9..ef7175b2 100644 --- a/docs/en/Features-React-Setup-Page.md +++ b/docs/en/Features-React-Setup-Page.md @@ -4,6 +4,8 @@ ASP.NET Zero application can be set-up using install page. This page is develope Just note that, this page is only visible when the database is not created. If the database is created, you will be redirected to login page. +Since the server application and the database server often start together (for example after a machine reboot), the server application waits for the database server for a short while before it starts, so that a database that is simply slow to start is not mistaken for a missing one. See [Waiting for the Database on Startup](Infrastructure-Core-Mvc-Configuration#waiting-for-the-database-on-startup) if you need to change how long it waits. + install page ## Next diff --git a/docs/en/Infrastructure-Core-Mvc-Configuration.md b/docs/en/Infrastructure-Core-Mvc-Configuration.md index a905516a..3c87e854 100644 --- a/docs/en/Infrastructure-Core-Mvc-Configuration.md +++ b/docs/en/Infrastructure-Core-Mvc-Configuration.md @@ -8,6 +8,7 @@ Every application in the solution has it's own **appsettings.json** that should - "**ConnectionStrings:Default**": Database connection string. - "**Abp.RedisCache**": Redis cache settings if you are enabled [Redis cache provider](https://aspnetboilerplate.com/Pages/Documents/Caching#redis-cache-integration). +- "**App:Database:StartupWait**": Waits for the database server to become available while the application is starting. See [Waiting for the Database on Startup](#waiting-for-the-database-on-startup). - "**App:WebSiteRootAddress**": Root URL of this application. - "**App:RedirectAllowedExternalWebSites**": A comma separated list of root URLs those are allowed to be redirected once user logins. For security reasons, ASP.NET Zero only redirects to local URLs except this list. If you will use the public web site, you should add it's root URL to this list. - "**Authentication**": Authentication settings especially for external login providers. @@ -29,9 +30,42 @@ Every application in the solution has it's own **appsettings.json** that should - "**ConnectionStrings:Default**": Database connection string. - "**Abp.RedisCache**": Redis cache settings if you are enabled [Redis cache provider](https://aspnetboilerplate.com/Pages/Documents/Caching#redis-cache-integration). +- "**App:Database:StartupWait**": Waits for the database server to become available while the application is starting. See [Waiting for the Database on Startup](#waiting-for-the-database-on-startup). - "**App:ServerRootAddress**": Root URL of this application. - "**App:ClientRootAddress**": Root URL of the Angular application (if you are using Angular as UI). - "**App:CorsOrigins**": Allowed origins for cross origin requests (splitted by comma). - "**Authentication**": Authentication settings especially for external login providers. - "**IdentityServer**": IdentityServer settings. It's important to disable it if you are not using IdentityServer. If you are using, ensure that you configured proper settings. -- "**Payment**": Payment provider settings if you are developing a paid SaaS product. \ No newline at end of file +- "**Payment**": Payment provider settings if you are developing a paid SaaS product. + +## Waiting for the Database on Startup + +Your application and your database server usually start at the same time, for example when the machine reboots. If the database server is still starting up, the application can start before it and find no database to connect to. This is a common situation with SQL Server, since its service is often set to *Automatic (Delayed Start)* and can take a couple of minutes to become available. + +When this happens, the application would otherwise start in a degraded state: background jobs would not be registered, host data would not be seeded, and users would be sent to the setup page even though the database is perfectly fine. + +To avoid this, the application waits for the database server for a short while before it starts. If the database becomes available within that time, the application starts normally. If it does not, the application still starts (it never hangs forever) and logs a warning telling you to make the database available and restart the application. + +This is configured under **App:Database:StartupWait** in `appsettings.json`: + +```json +"App": { + "Database": { + "StartupWait": { + "Enabled": true, + "TimeoutSeconds": 40, + "RetryIntervalSeconds": 3, + "ConnectTimeoutSeconds": 5 + } + } +} +``` + +- "**Enabled**": Set it to `false` to start immediately without waiting for the database. +- "**TimeoutSeconds**": How long the application waits for the database server at most. +- "**RetryIntervalSeconds**": How long it waits between two attempts. +- "**ConnectTimeoutSeconds**": How long a single connection attempt is allowed to take. + +The application only waits when the database **server** cannot be reached. If the server is reachable but the database has not been created yet, it does not wait at all and takes you straight to the [setup page](Features-Mvc-Core-Setup-Page). + +If your database server takes longer than the configured timeout to start, increase **TimeoutSeconds**. Note that the application does not accept requests while it is waiting, so if you host on IIS, make sure the value stays below the IIS startup time limit (`startupTimeLimit`), and increase that limit as well if you need a longer wait. \ No newline at end of file