BookStack FileSystem

A FUSE based filesystem which lists the contents of a BookStack instance via REST API exports. This allows browsing of BookStack books, chapters and pages like normal directories & files on a filesystem.

Note: This is a demo project to test out the idea, and has been written with lacking expertise of the language & APIs used while also missing tests, so it's prone to issues. Also, this should not be used for backup operations since this uses page exports, which would lack much of the detail and metadata needed for actual BookStack backup.

Requirements

• A linux system to run this on (Only tested on Fedora so far).
• A BookStack instance, on a relatively recent version (tested on v25.02).
  • Working REST API access credentials for your instance.
• A built copy of the application.
  • You can find built binaries on the releases page.

Usage

Run the executable, passing in an existing directory path to use as the mount point:

./bsfs [options] <mount-point>

# Simple example
./bsfs /mnt/bookstack

# Mount with html-based pages
./bsfs -format html /mnt/bookstack

# Specify connection options via command line
./bsfs -base-url=https://docs.example.com -api-token-id=abc123 -api-token-secret=def456 /mnt/bookstack

You'll need to configure access to your BookStack instance either through options, or via environment variables. See the options section below for details.

You can run with the --help flag to show usage details on the command line.

Options

The following options are available:

• -api-token-id: BookStack api token id (defaults to BS_TOKEN_ID environment option)
• -api-token-secret: BookStack api token secret (defaults to BS_TOKEN_SECRET environment option)
• -base-url: Your BookStack base url (defaults to BS_URL environment option)
• -format: Format to used for reading pages [txt/html/pdf/md] (defaults to txt)

Building

The source can be built using Go like so:

# Download required modules
go mod download

# Build code
go build

Known Issues

• File sizes will appear wrong, at least until files are accessed, due to not knowing actual sizes without performing (expensive) API requests.
• Sometimes it won't unmount correctly, requiring a manual sudo umount <path>.

Contributions

Feel free to raise issues for bugs experienced. I'd also welcome pull requests for fixing issues. Issues for feature requests can also be opened but keep in mind the scope of this will be kept fairly narrow to avoid maintenance burden.

Licensing & Attribution

This project code is provided under an MIT License.

This project makes heavy use of the bazil/fuse library, which also makes use of software from other sources. These become part of any binaries built using this project's source code. The copyright & license details of these can also bee seen in our LICENSE file.