BookStack High Availability Setup #581

New Issue

OVERLORD · 2026-02-04T21:18:13+03:00

OVERLORD commented

2026-02-04 21:18:13 +03:00

Originally created by @jacac on GitHub (Feb 28, 2018).

Hello BookStack developer, thank you for creating an easy tool to create nice looking books/wikis.

Intro

During a high availability setup of BookStack I could not find any documentation around this topic. I've setup already a few PHP applications in HA mode, so I knew the basics I needed. Hopefully I covered all the areas which needed special attention.

Here a list I came up with during the setup and please correct me if I missed anything:

Sessions needs to be stored in DB, Memcache or Redis
storage/uploads needs to live on a shared directory (SAN/NAS) with access from all nodes.
public/uploads needs to live on a shared directory (SAN/NAS) with access from all nodes.
No sure about the workflow for S3

It would be nice if a topic could be create in the documentation about this.

Missing feature: Customize the location of upload folder.

Feature missing is to customize the location of those upload folders. In the .env to have for STORAGE_TYPE=local another parameter STORAGE_LOCAL_ROOT=/full/path/to/something which could point to a shared folder and hold all files which need to be accessible by all nodes.

The workaround i did was to create links from those folders to SAN location. Now, every time I update BookStack those folders need to be removed and a link created instead.

Originally created by @jacac on GitHub (Feb 28, 2018). Hello BookStack developer, thank you for creating an easy tool to create nice looking books/wikis. #### Intro During a high availability setup of BookStack I could not find any documentation around this topic. I've setup already a few PHP applications in HA mode, so I knew the basics I needed. Hopefully I covered all the areas which needed special attention. Here a list I came up with during the setup and please correct me if I missed anything: - Sessions needs to be stored in DB, Memcache or Redis - storage/uploads needs to live on a shared directory (SAN/NAS) with access from all nodes. - public/uploads needs to live on a shared directory (SAN/NAS) with access from all nodes. - No sure about the workflow for S3 It would be nice if a topic could be create in the documentation about this. #### Missing feature: Customize the location of upload folder. Feature missing is to customize the location of those upload folders. In the `.env` to have for `STORAGE_TYPE=local` another parameter `STORAGE_LOCAL_ROOT=/full/path/to/something` which could point to a shared folder and hold all files which need to be accessible by all nodes. The workaround i did was to create links from those folders to SAN location. Now, every time I update BookStack those folders need to be removed and a link created instead.

OVERLORD added the 📖 Docs Update label 2026-02-04 21:18:13 +03:00

OVERLORD closed this issue

2026-02-04 21:18:16 +03:00

OVERLORD commented

2026-02-04 21:18:18 +03:00

@comnam90 commented on GitHub (May 29, 2018):

@jacac Hey I'm looking to setup HA bookstack as well, care you share your notes?

I setup a MySQL Group Replication cluster initially but it seems Bookstack's DB schema isn't compatible.

Next I tried a MariaDB Galera cluster, but I'm not as familiar with that and for some reason the bookstack DB doesn't seem to have replicated from one node to the other.

@comnam90 commented on GitHub (May 29, 2018): @jacac Hey I'm looking to setup HA bookstack as well, care you share your notes? I setup a MySQL Group Replication cluster initially but it seems Bookstack's DB schema isn't compatible. Next I tried a MariaDB Galera cluster, but I'm not as familiar with that and for some reason the bookstack DB doesn't seem to have replicated from one node to the other.

OVERLORD commented

2026-02-04 21:18:21 +03:00

@jacac commented on GitHub (May 29, 2018):

@comnam90 We are running Bookstack on MariaDB Galera Cluster, the only think I had to add was the engine in the database driver inside config\database.php see https://github.com/BookStackApp/BookStack/issues/727.

'mysql' => [
            'driver'    => 'mysql',
            'host'      => $mysql_host,
            'database'  => env('DB_DATABASE', 'forge'),
            'username'  => env('DB_USERNAME', 'forge'),
            'password'  => env('DB_PASSWORD', ''),
            'port'      => $mysql_port,
            'charset'   => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix'    => '',
            'strict'    => false,
	    'engine'	=> 'INNODB ROW_FORMAT=COMPRESSED'
        ],

but if your database is not getting replicated to other DB servers inside the cluster you have a problem with your DB cluster.

@jacac commented on GitHub (May 29, 2018): @comnam90 We are running Bookstack on MariaDB Galera Cluster, the only think I had to add was the engine in the database driver inside `config\database.php` see https://github.com/BookStackApp/BookStack/issues/727. ```php 'mysql' => [ 'driver' => 'mysql', 'host' => $mysql_host, 'database' => env('DB_DATABASE', 'forge'), 'username' => env('DB_USERNAME', 'forge'), 'password' => env('DB_PASSWORD', ''), 'port' => $mysql_port, 'charset' => 'utf8mb4', 'collation' => 'utf8mb4_unicode_ci', 'prefix' => '', 'strict' => false, 'engine' => 'INNODB ROW_FORMAT=COMPRESSED' ], ``` but if your database is not getting replicated to other DB servers inside the cluster you have a problem with your DB cluster.

OVERLORD commented

2026-02-04 21:18:25 +03:00

@comnam90 commented on GitHub (May 30, 2018):

Ah! that was the missing piece
tables were replicating but without data. Specifying innodb specifically sorted that out

@comnam90 commented on GitHub (May 30, 2018): Ah! that was the missing piece tables were replicating but without data. Specifying innodb specifically sorted that out

OVERLORD commented

2026-02-04 21:18:28 +03:00

@jacac commented on GitHub (May 30, 2018):

Your Galera cluster should have INNODB as the default table engine. Other
table types are not replicated see
https://mariadb.com/kb/en/library/mariadb-galera-cluster-known-limitations/.

On Tue, May 29, 2018 at 11:33 PM, Ben Thomas notifications@github.com
wrote:

Ah! that was the missing piece
tables were replicating but without data. Specifying innodb specifically
sorted that out

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/BookStackApp/BookStack/issues/722#issuecomment-393046108,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAZxlbz-Zwswo4iWGIkHWNSmiIOzITYvks5t3j0xgaJpZM4SXMbK
.

@jacac commented on GitHub (May 30, 2018): Your Galera cluster should have INNODB as the default table engine. Other table types are not replicated see https://mariadb.com/kb/en/library/mariadb-galera-cluster-known-limitations/. On Tue, May 29, 2018 at 11:33 PM, Ben Thomas <notifications@github.com> wrote: > Ah! that was the missing piece > tables were replicating but without data. Specifying innodb specifically > sorted that out > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <https://github.com/BookStackApp/BookStack/issues/722#issuecomment-393046108>, > or mute the thread > <https://github.com/notifications/unsubscribe-auth/AAZxlbz-Zwswo4iWGIkHWNSmiIOzITYvks5t3j0xgaJpZM4SXMbK> > . >

OVERLORD commented

2026-02-04 21:18:32 +03:00

@ssddanbrown commented on GitHub (Jan 30, 2022):

Just coming back to this (4 years later 🐢)

I've now appended a "High Availability" section to our install page:
https://www.bookstackapp.com/docs/admin/installation/#ha

In regards to a STORAGE_LOCAL_ROOT option, I'd only introduce such an option if there was a significant case and demand for it. Having predictable paths makes support easier while having less complications to consider when testing/changing things. I'd have thought many in a highly available setup may choose the s3/s3-like path anyway.

@ssddanbrown commented on GitHub (Jan 30, 2022): Just coming back to this (4 years later :turtle:) I've now appended a "High Availability" section to our install page: https://www.bookstackapp.com/docs/admin/installation/#ha In regards to a `STORAGE_LOCAL_ROOT` option, I'd only introduce such an option if there was a significant case and demand for it. Having predictable paths makes support easier while having less complications to consider when testing/changing things. I'd have thought many in a highly available setup may choose the s3/s3-like path anyway.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#581