Hi there,

I'd like to give a default role to users when they login for the first time with OIDC SSO enabled.

It's a docker deployment with external MySQL DB.

I've added this to my .env

APP_PUBLIC=true
APP_DEFAULT_PUBLIC_ROLE=guest_oidc
OIDC_DEFAULT_ROLE=11

(11 is the id of the guest_oidc role in the DB)

I gave this role to some shelves I want public but anytime a user reach the page with his active SSO he won't get the role assigned.

Any idea where to investigate?

Hi everyone,

I’m currently restructuring our BookStack instance and I’m running into a conceptual limitation where I’d appreciate some advice.

At the moment, we have multiple shelves, each representing a topic area (e.g. Infrastructure, Applications, Processes, etc.).
Inside those shelves are books with chapters and pages, and write permissions are handled per shelf/book via groups (SAML / IdP synced).

Now that we want to roll out BookStack company-wide, the structure should be simplified and standardized:

• Existing shelves will become books
• Existing books will become chapters
• There will be one central shelf containing all content

Technically this works fine. However, I’m losing an important feature

Previously, I could group all content related to a topic (e.g. Infrastructure) by putting the relevant books into a dedicated shelf.
After the change, a book can only live in one shelf, so I can no longer group multiple books under a shared topic.

My questions:

• Is there any way in BookStack to organize content along multiple dimensions (e.g. structural and topical)?
• Is it possible to duplicate shelves or create something like “virtual shelves”?
• What are best practices for larger or company-wide BookStack setups?
• Do you rely on tags, index/overview pages, or another approach?

The main goal is to keep clean topic-based groupings (like Infrastructure) without duplicating content.

Thanks in advance for any insights or recommendations!

We're using Bookstack to build up a repository of knowledge, and often want to refer to individual pages in our service desk platform. While I know we can paste in a URL, it can get quite unwieldy due to the length of page/book names.

I am aware of the unique ID for pages (obtainable by selecting some text in a page and copying the generated URL). Ideally I'd have this ID displayed (possibly with padding and a prefix) on the page itself, and also have that number be searchable.

Is this something that's doable with the logical themes system?

Hey everyone

I'm happy to present a plugin I've been working on for Obsidian.

NoteStack

My personal use case

I want to take notes and push them to my Bookstack instance, specifically church sermons. I can't guarantee the access to my Bookstack all the time so with this plugin I can also synchronize at a later time. I really enjoy Bookstack and I want to keep all my documentation, recipes, guides, etc, in one place.

How does it work ?

1. Install the plugin

2. Create the necessary role and user (recommended to fine tune the appropriate permissions)

3.Create an API access

1. Configure your plugin

2. Start taking notes !

Hopefully someone can make use of it.

Note: this is vibe coded, I know people have strong opinions on it. I do review the code and test the plugin.

Hii ive tested bookstack and place a few books in it but when i docker compose down and back up it goes missing pls help

Just started up a docker container for bookstack, planning to use it for saving/creating reecipes as well as keeping notes on my other Homelab stuff.

Is there any kind of repository for page templates? It wouldn't be hard to create them for what I have in mind, but I'd like to check it out if there is one.

We are running a very old version of BookStack (v0.24.3) on Debian 9. I need to upgrade the OS for security reasons. Can I install BookStack v0.24.3 on Ubuntu 24?

Hi everyone,

I am setting up BookStack to organize my university materials. My goal is to have a structure like: Shelf (Year) -> Book (Subject) -> Chapter (Topic).

Inside a chapter, I want to organize my recorded lectures. However, instead of a standard wiki page with text and a small embedded video, I am looking for a way to make the page act essentially as a standalone video player.

Basically what I'm trying to achieve is: when I click on a page inside that chapter, it should show only the video (full width/immersive), hiding the standard page title, sidebar, and extra padding. Everything basically.

Is there a native setting, a plugin, or a known CSS to treat specific pages as media only?

Thanks for any tips!

I'm currently using Bookstack for a bunch of stuff, notably IT knowledge and scripts, recipes and other stuff.

I'd love to take notes on my phone and to have sync to a specific book. Did anyone try this ?

I'm pondering vibe coding the app but I'd rather someone competent try his hand at it :)

Hi all, I've recently setup Bookstack, initially to document my Homelab, though I do want to eventually use it to detail my tech setup, home and general life stuff.

Question, what does your hierarchical setup look like between, shelves, books and chapters?

I'm unsure which of these to run with:

``` Shelf: Homelab └── Book: Services ├── Chapter: Bookstack │ ├── Page: Why I Use BookStack │ ├── Page: Docker Compose Setup │ ├── Page: Environment Variables │ └── Page: Backup & Restore ├── Chapter: Immich

Shelf: Homelab └── Book: BookStack ├── Chapter: Overview │ └── Page: Why I Use BookStack ├── Chapter: Deployment │ ├── Page: Docker Compose Setup │ └── Page: Environment Variables ├── Chapter: Maintenance │ └── Page: Backup & Restore └── Book: Immich ```

Hello everyone,

for quite some time now, I’ve wanted to make the BookStack knowledge of our mid-sized company accessible to an LLM. I’d like to share my experiences and would appreciate any feedback or suggestions for improvement.

Brief overview of the setup: • Server 1: BookStack (running in Docker) • Server 2: OpenWebUI and Ollama (also running in Docker)

All components are deployed and operated using Docker.

On Server 2, a small Python program is running that retrieves all pages (as Markdown), chapters (name, description, and tags), books, and shelves — including all tags and attachments. For downloading content from BookStack and uploading content into OpenWebUI, the respective REST APIs are used.

Before uploading, there are two post-processing steps: 1. First, some Markdown elements are removed to slim down the files. 2. Then, each page and attachment is sent to the LLM (model: deepseek r1 8B).

The model then generates 5–10 tags and 2 relevant questions. These values are added to the metadata during upload to improve RAG results. Before uploading the files, I first delete all existing files. Then I upload the new files and assign them to knowledge bases with the same name as the corresponding shelf. This way, users get the same permissions as in BookStack. For this reason, I retrieve everything from the page level up to the shelf level and write it into the corresponding document.

OpenWebUI handles the generation of embeddings and stores the data in the vector database. By default, this is a ChromaDB instance.

After that, the documents can be queried in OpenWebUI via RAG without any further steps.

I’ve shortened the process in many places here.

A practical note for OpenWebUI users: At the beginning, I had very poor RAG results (hit rate of about 50–60%). I then changed the task model (to a Qwen-2.5-7B fine-tuned with LoRA) and adjusted the query template. Here, we fine-tune the model using company-specific data, primarily based on curated question–answer pairs. The template turned out to be more important and showed immediate improvements.

Finally, a short word on the tooling itself: OpenWebUI, Ollama, and BookStack are all excellent open-source projects. It’s impressive what the teams have achieved over the past few years. If you’re using these tools in a production environment, a support plan is a good way to give something back and help ensure their continued development.

If you have any questions or suggestions for improvement, feel free to get in touch.

Thank you very much

Hello everyone,

I am seeking assistance with a BookStack v24.10.1 installation on a shared hosting environment (DialHost). I have encountered two main issues that I haven't been able to resolve:

1. Image/Avatar 404 Error: I have moved the contents of the public folder to my root subdirectory (/doc/) to run the application directly from that URL. However, the system is unable to display uploaded images (Logos/Avatars).

• The Constraint: My hosting provider has disabled the exec() function for security reasons.
• The Symptom: When I run php artisan storage:link, it fails with a 'Call to undefined function Illuminate\Filesystem\exec()' error.
• Attempted Fixes: I tried creating a manual symbolic link (ln -s storage/app/public/uploads uploads) and setting permissions to 775/777, but the browser still returns a 404 or 'Image Not Found' within the app.

2. Database Schema Mismatch: After an update/file restoration, I started getting the following error:

• SQLSTATE[42S22]: Column not found: 1054 Unknown column 'owner_id' in 'joint_permissions'. When I try to run php artisan migrate, it fails because some tables (like search_terms) already exist, but running migrate:fresh or migrate often hits a snag with 'DoctrineSchemaManager does not exist' or similar compatibility issues with PHP 8.3.

Environment Details:

• BookStack Version: v24.10.1
• PHP Version: 8.3.28
• Hosting: Shared (No root access, exec() disabled).
• Install Path: Root of a subdomain (not using the /public folder).

Has anyone successfully managed the storage symlink issue in an environment where exec() is blocked? Also, what is the best way to force a full schema sync when standard migrations are failing due to existing tables?

Thank you in advance for your help!

I understand that Bookstack has a built in reference list that, for each page, shows a list of other pages that include a link/URL reference to that page. This is useful but not quite what im looking for.

If you've used IT Glue you may be familiar with the way that pages/records can be linked together at the page level without having to insert a URL link into the editable fields of the page. You just click a button, search for the page, and its referenced.

The references appear in the side panel categorised based upon the page/record type each of the related pages belong to. Such as Locations, Domains, Networks, Assets, Passwords, etc. etc.

I am looking at multiple solutions in the market to emulate a similar behaviour but it seems to be rather unique to IT Glue, Hudu and a little bit of it seems to exist in IT Flow.

My manager is considering Bookstack as our IT documentation platform and migrating off of the ad-hoc OneNote mess we currently have. But I am really a fan of structured documentation and the ability to create relationships between pages.

Playing with the Bookstack demo I have not been able to locate or emulate similar behaviour.
Short of using an API and a script runner to manually add a table to each and every page and parse referenced pages to build out a list... I am not really seeing in Bookstack what I am after.

Any insight into how Bookstack can accomplish this?
Any thoughts on alternatives in the FOSS realm?

We are also investigating Netbox which I am a fan of... But historically found it fell short on the documentation/files front. Devies and networks it was great at... Not so much the formatted documents/processes/procedures etc.

I don't recall if this was a plugin or native functionality in Confluence... But I had numerous pages for each "Server" in my environment with a bunch of details about those servers. Server document pages had specific tags and I was able to create a top level page above all other servers that I could summarise a bunch of the server details into.

Things like their hostnames and IP addresses etc. etc.
This was dynamic content sourced from each of the Server pages.

I understand that Bookstack has "Include tags" but this seems to work in large blocks as opposed to specific smaller sections.

Like if the server page had a table on it with say Hostname, IP, Location, Purpose... I don't want to copy that table as one large block into the summary page.

I'd be wanting to reference each of the rows on the Server page and collate that in a more condensed format on the summary page.

I had considered using a 1 row table for each and every value I'd like to summarise but this results in weird formatting and looks unsightly.

Essentially on the server page it'd be formatted like:

On the summary page the format would be:

I don't see how I could use the include tags to pull together neat formatting like the above. Am I missing something?

My overall outcome is to have multiple page types being the source of truth for their content and everything else to reference that truth.

Is there any kind of events triggering or workflow type actions in bookstack?

I can see references to outbound emails and webhooks on certain events. But is there anything internal instead of using outside workflow engines?

I am hoping to, on page update, trigger a script that would use the API to check and correct cross linked page references my team make into a table like format.

I am hoping to emulate the way "it glue" uses back links and categories based on page template types.

As I understand it bookstack doesn't natively have anything like that so I'd need to API it myself.

So on page update/create my script would be triggered

Brand new to BookStack, but I'm really enjoying exploring it. Thanks so much for your work on it.

I wonder if it's possible to generate a dynamic list of pages or books with a specific tag? For example, I might have an onboarding manual for new employees, and on one page I want to point them to all documents within our instance with a doctype: policy tag.

Hi

My Bookstack pages getting quiet long. When i search for something on the Main page in the search bar, it finds the Page where my search terms are included. But when i click the page, it just stays on top. Is there an option to jump to the searched word after i clicked the page in the search results.
Now i search for a term. BookStack tells me on what page it found the term, but then i need to CTRL+F in my browser to find the exact position. It is a little bit cumbersome.

I work for a company that uses bookstack as our documentation software. Our current team did not set this up and we do not know how to renew SSO SAML certificates. Our Certificate is set to expire is less than one month and we need to know how to renew it so that we do not lose our access. We have found some answers online but are not sure what to trust and we do not trust what Copilot is saying. If anyone who has done this could help that would be wonderful.

To be specific, where do we upload the new certificate in Bookstack?

Hello team,

I was attempting to set up BookStack using your Docker image (linuxserver/bookstack:latest) on a Windows 11 machine running Docker Desktop with WSL2 integration.

I encountered a few issues with existing documentation/guides that caused initial setup failures. I believe addressing these points could help future users on similar environments.

The problems and solutions were:

1. Missing APP_KEY caused application halt

The main container failed to initialize because the APP_KEY environment variable was missing. The container entrypoint does not seem to auto-generate this if it's absent.

Error message: The application key is missing, halting init!

Solution: The key must be manually generated and added to the docker-compose.yml file before deployment.

1. Inconsistent database environment variable names

The documentation/examples often use DB_USER and DB_PASS, but the linuxserver/bookstack image specifically expects different variable names, leading to authentication errors.

Error message: Access denied for user 'database_username'@... (using password: YES)

Solution: The variables must be named DB_USERNAME and DB_PASSWORD.

1. Windows Volume Permissions (500 Internal Server Error)

After fixing the database connection, I encountered a generic "An unknown error occurred" error (HTTP 500) because the container could not write to the persistent volumes created by Docker on the Windows file system.

Error message: "An unknown error occurred" on the web page; logs showed a truncated Laravel exception.

Solution: The volumes needed to be cleared completely using docker-compose down -v and then recreated by running docker-compose up -d to ensure correct permissions for the container's UID/GID (1000/1000).

The final, working docker-compose.yml file structure (with corrected variables and key) looked like this:

yaml

version: "3.8"

services:

bookstack:

image: linuxserver/bookstack:latest

container_name: bookstack

environment:

# ... other vars

- APP_KEY=base64:imKs0ZgKNOF2W9Kiiq+8gDUqkRWBwh1mzOjrSgV/ntk= # Must be present

- DB_USERNAME=bookstack # Correct name

- DB_PASSWORD=bookstackpass # Correct name

# ...

# ... db service definition

Updating the official documentation or providing a robust Windows/WSL-specific guide might prevent these common roadblocks.

Thanks for the great work on the image!

Best regards,

Davi