Skip to main content

Bookstack Proxmox VE Community Script

Installing Bookstack via Proxmox community scripts is very easy. It is installed via this Proxmox VE Community Script: Bookstack. It setups a lxc container with Debian

root@lxc-bookstack:~# cat /etc/os-release 
PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
NAME="Debian GNU/Linux"
VERSION_ID="13"
VERSION="13 (trixie)"
VERSION_CODENAME=trixie
DEBIAN_VERSION_FULL=13.2
ID=debian
HOME_URL="https://www.debian.org/"
SUPPORT_URL="https://www.debian.org/support"
BUG_REPORT_URL="https://bugs.debian.org/"
root@lxc-bookstack:~#

and installs and configures a MariaDB database

root@lxc-bookstack:~# systemctl status mariadb --no-pager
● mariadb.service - MariaDB 12.2.1 database server
     Loaded: loaded (/usr/lib/systemd/system/mariadb.service; enabled; preset: enabled)
    Drop-In: /etc/systemd/system/mariadb.service.d
             └─migrated-from-my.cnf-settings.conf
     Active: active (running) since Sun 2025-12-14 14:15:56 UTC; 19min ago
...

Backup

To backup bookstack files and entries, there is a cli tool which can be used.

  • Enter the LXC directly or use pct enter <CTID> to access the LXC container.
  • change into the bookstack folder cd /opt/bookstack
  • execute the cli cmd to backup 
    root@lxc-bookstack:~# cd /opt/bookstack/
root@lxc-bookstack:/opt/bookstack# ./bookstack-system-cli backup
WARNING: This CLI is in alpha testing.
There's a high chance of issues, and the CLI API is subject to change.

Checking system requirements...
Dumping the database via mysqldump...
Adding database dump to backup archive...
Adding BookStack upload folders to backup archive...
Adding BookStack theme folders to backup archive...
Saving backup archive...
Backup finished.
Output ZIP saved to: /opt/bookstack/storage/backups/bookstack-backup-2025-12-14-143913.zip
root@lxc-bookstack:/opt/bookstack#

Restore

To restore a backup, log in to the BookStack LXC and change into the BookStack installation directory. From there, run the BookStack system CLI with the restore command and provide the path to the backup file.

root@lxc-bookstack:/opt/bookstack# ./bookstack-system-cli restore storage/backups/bookstack-backup-2025-12-12-162653.zip

During the restore process, the CLI will display a summary of the contents found in the backup and warn about the implications of restoring:

  • Existing files and uploaded content will be overwritten
  • Existing database tables will be dropped
  • The target instance must be the same or a newer BookStack version
  • Server-level configuration is not restored

You will be prompted to confirm before the restore is executed.

Permissions note when restoring from outside the container

This probably solves the issue you might encounter after a restore when you want to upload files.

If you mounted the LXC root filesystem on the Proxmox host and copied a backup into the container from outside, do not run bookstack-system-cli on the host system. Running the CLI outside the container can result in incorrect file ownership and permissions.

If this has already happened, the permissions can be corrected from the Proxmox host.

In the following example, the BookStack container ID is 120. Adjust this value to match your environment.

# Mount the LXC root filesystem
pct mount 120
# mounted CT 120 in '/var/lib/lxc/120/rootfs'

# Change into the BookStack directory
cd /var/lib/lxc/120/rootfs/opt/bookstack

# Inspect current ownership
ls -l

Example output:

root@pve:/var/lib/lxc/120/rootfs/opt/bookstack# ls -l
total 755
drwxr-xr-x 23 100033 100033     23 Dec 14 12:52 app
-rwxr-xr-x  1 100033 100033   1685 Dec 14 12:52 artisan

To correct the ownership, apply the following command:

chown -R 100033:100033 *

In this setup, the UID and GID 100033 correspond to the www-data user and group inside the container.

Hint

Using php artisan bookstack:regenerate-permissions does not fix file ownership or filesystem permissions. As such, it cannot be used to resolve this issue.

Best practice is to mount the LXC root filesystem on the host, copy the backup file into place, immediately correct ownership and permissions, then unmount the root filesystem. After that, enter the container and execute the restore commands. This ensures that correct permissions are maintained throughout the entire process.

Back to top