Update installation documentation #1965

New Issue

OVERLORD · 2026-02-05T02:20:32+03:00

OVERLORD commented

2026-02-05 02:20:32 +03:00

Originally created by @Baptistou on GitHub (Dec 9, 2020).

Describe the feature you'd like
I encountered 2 different issues during a fresh install of BookStack on an Apache server that could be added to the documentation.

Error 404 at first login

This was really stupid but I have spent hours to understand what was happening, verifying every config files and having no error logs nor help on internet. I finally discovered that I forgot to enable mod_rewrite for Apache, please add this into the requirements.

Error 500 at first login

I also spent hours to find a solution, having no error logs again. I had to add RewriteBase / into the file bookstack/public/.htaccess in order to fix the problem.
According to Apache documentation :

This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless any of the following conditions are true [...]

In my case, the conditions were not met and this directive was effectively required. It would be nice to either add this rule to the repository if there is no regression or to add a Common Errors/FAQ section into the documentation.

Describe the benefits this feature would bring to BookStack users
Save a lot of time ! 😄

Originally created by @Baptistou on GitHub (Dec 9, 2020). **Describe the feature you'd like** I encountered 2 different issues during a fresh install of BookStack on an Apache server that could be added to the [documentation](https://www.bookstackapp.com/docs/admin/installation/). 1. Error 404 at first login This was really stupid but I have spent hours to understand what was happening, verifying every config files and having no error logs nor help on internet. I finally discovered that I forgot to enable mod_rewrite for Apache, please add this into the [requirements](https://www.bookstackapp.com/docs/admin/installation/#requirements). 2. Error 500 at first login I also spent hours to find a solution, having no error logs again. I had to add ```RewriteBase /``` into the file ```bookstack/public/.htaccess``` in order to fix the problem. According to [Apache documentation](https://httpd.apache.org/docs/2.4/en/mod/mod_rewrite.html#rewritebase) : > This directive is **required** when you use a relative path in a substitution in per-directory (htaccess) context unless any of the following conditions are true [...] In my case, the conditions were not met and this directive was effectively required. It would be nice to either add this rule to the [repository](https://github.com/BookStackApp/BookStack/blob/master/public/.htaccess) if there is no regression or to add a *Common Errors/FAQ* section into the [documentation](https://www.bookstackapp.com/docs/admin/installation/). **Describe the benefits this feature would bring to BookStack users** Save a lot of time ! :smile:

OVERLORD closed this issue

2026-02-05 02:20:34 +03:00

OVERLORD commented

2026-02-05 02:20:38 +03:00

@ssddanbrown commented on GitHub (Dec 10, 2020):

Thanks for the feedback @Baptistou.

In the docs I've added a hint to ensure mod_rewrite is enabled, by the Apache URL re-write rules to hopefully provide a hint.
I wouldn't want to add something so specific within the numbered manual install steps themselves as to avoid them becoming littered with platform/software specific edge-cases.

In regards to RewriteBase, I'm not going to add this as it should be rarely required, From the Apache documentation it states:

 This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless any of the following conditions are true:

 -   The original request, and the substitution, are underneath the DocumentRoot (as opposed to reachable by other means, such as Alias).
 -   The filesystem path to the directory containing the RewriteRule, suffixed by the relative substitution is also valid as a URL path on the server (this is rare).
 -   In Apache HTTP Server 2.4.16 and later, this directive may be omitted when the request is mapped via Alias or mod_userdir.

I think the first of those will be true in the vast majority of cases. For the cases where that is not true, I would hope that the cases will be advanced enough that configuration will be done via server config rather than .htaccess files. Supporting non-document root installs via .htaccess may encourage use where people just copy/download the bookstack files into a subdirectory within another server root folder location which is not something I'd want to be encouraging since it would put a lot of files at risk.

@ssddanbrown commented on GitHub (Dec 10, 2020): Thanks for the feedback @Baptistou. In the docs I've added a hint to ensure mod_rewrite is enabled, by the Apache URL re-write rules to hopefully provide a hint. I wouldn't want to add something so specific within the numbered manual install steps themselves as to avoid them becoming littered with platform/software specific edge-cases. In regards to `RewriteBase`, I'm not going to add this as it should be rarely required, From the Apache documentation it states: ``` This directive is required when you use a relative path in a substitution in per-directory (htaccess) context unless any of the following conditions are true: - The original request, and the substitution, are underneath the DocumentRoot (as opposed to reachable by other means, such as Alias). - The filesystem path to the directory containing the RewriteRule, suffixed by the relative substitution is also valid as a URL path on the server (this is rare). - In Apache HTTP Server 2.4.16 and later, this directive may be omitted when the request is mapped via Alias or mod_userdir. ``` I think the first of those will be true in the vast majority of cases. For the cases where that is not true, I would hope that the cases will be advanced enough that configuration will be done via server config rather than `.htaccess` files. Supporting non-document root installs via `.htaccess` may encourage use where people just copy/download the bookstack files into a subdirectory within another server root folder location which is not something I'd want to be encouraging since it would put a lot of files at risk.

OVERLORD commented

2026-02-05 02:20:43 +03:00

@Baptistou commented on GitHub (Dec 10, 2020):

In the docs I've added a hint to ensure mod_rewrite is enabled, by the Apache URL re-write rules to hopefully provide a hint.

Nice 👍 Thanks

In regards to RewriteBase, I'm not going to add this as it should be rarely required, From the Apache documentation it states:

I understand. And what about to add a Common Errors/FAQ in the doc ? This would be very helpful.

@Baptistou commented on GitHub (Dec 10, 2020): > In the docs I've added a hint to ensure mod_rewrite is enabled, by the Apache URL re-write rules to hopefully provide a hint. Nice :+1: Thanks > In regards to RewriteBase, I'm not going to add this as it should be rarely required, From the Apache documentation it states: I understand. And what about to add a Common Errors/FAQ in the doc ? This would be very helpful.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#1965