Introduction

Most homelabs eventually grow a documentation problem. You've got IP addresses in a spreadsheet, a Docker Compose file you'll "remember how it works," and a note-to-self in your phone about which port forward goes where. Then six months pass, something breaks, and you're staring at your own infrastructure like a stranger.

BookStack fixes that by giving you a real wiki — shelves, books, chapters, pages — that lives on hardware you control instead of inside someone else's cloud app. No monthly fee, no account limits, no company deciding to shut the product down.

This guide walks through installing BookStack inside an LXC container on Proxmox VE, using the community helper script that handles the web server, PHP, and database setup for you. You don't need prior Linux administration experience. Every command below gets explained before you run it.

By the end you'll have a working wiki reachable from any browser on your network, and a decent sense of how to keep it running when something inevitably needs a restart.

What You Will Learn

  • What BookStack actually is and how its shelf/book/chapter/page structure works
  • Why an LXC container is the right amount of overhead for an app like this
  • How to spin up a Debian 13 container and install BookStack with a single script
  • How to log in for the first time and lock down the default account
  • The specific errors people hit with this setup, and what's actually causing them
  • A few habits that will save you a headache a few months from now

What Is This Feature?

BookStack is an open-source wiki platform built for people who want structure, not a blank page. Content is organized into Shelves (collections of books), Books (a topic, like "Home Network" or "Server Runbooks"), Chapters (optional groupings inside a book), and Pages (the actual content, written in a rich text editor or Markdown). If you've used Confluence or Notion, the mental model will feel familiar — BookStack just doesn't ask for a credit card.

Under the hood it's a PHP application (the Laravel framework, specifically) backed by a MySQL-compatible database. The community script we're using installs it on Apache 2 with PHP 8.3 and MariaDB as the database engine — all running natively inside the container, no Docker layer involved.

We're putting this inside an LXC container rather than a full virtual machine. LXC (Linux Containers) shares the Proxmox host's kernel instead of emulating its own virtual hardware, so it starts in a couple of seconds and only uses the RAM the app actually needs. For something as lightweight as a PHP wiki, spinning up a full VM with its own kernel and boot process would be overkill.

Day to day, the editing experience is what sells it. Every page supports a drag-and-drop WYSIWYG editor or a Markdown mode, page revisions are kept automatically so you can roll back a bad edit, and search actually works — it indexes page content, not just titles, so a phrase you half-remember from a page you wrote eight months ago will still turn up. Pages can also carry tags, which matters once your book count grows past a dozen or so and browsing stops being practical.

Why Would You Use It?

The obvious use case is homelab documentation — VLAN layouts, which container has which static IP, the steps you always forget when renewing a certificate. But BookStack works just as well for anything you'd otherwise put in a stack of sticky notes: a family recipe collection, a small team's internal knowledge base, onboarding docs for a side project, even a personal journal if you set the permissions right.

Compared to a shared Google Doc or a wiki-as-a-service product, you get a few things those don't offer:

  • Full ownership of your content — nothing gets indexed, mined, or held behind a paywall later
  • Real access control per book, chapter, or page, not just "anyone with the link"
  • Version history and page comments built in, without a premium tier
  • It runs comfortably on a container using a single CPU core and a gig of RAM

Is it as polished as Notion? No, not quite. But for structured, searchable documentation that you actually own, it does the job well, and it does it for free.

There's also a practical angle a lot of people don't think about until it happens: services get discontinued, pricing tiers change overnight, and a "free" cloud wiki can turn into a paywall the day you have three years of content in it. A BookStack instance sitting on your own Proxmox host doesn't have that problem. Worst case, you restore last night's backup and you're back where you were.

Prerequisites

Before you start, make sure you have:

  • A working Proxmox VE host on version 8.x or 9.x (this guide was tested on 9.2)
  • At least 4 GB of free space on the storage you plan to use for the container
  • A network bridge (usually vmbr0) with either DHCP available or a static IP address you've picked out in advance
  • Root or administrative access to the Proxmox VE shell
  • About ten minutes — the install script does almost all of the work

You don't need Docker knowledge for this method, and you don't need to already know PHP or MariaDB. If you can copy a command and paste it into a terminal, you can follow along.

Step-by-Step Tutorial

Log in to your Proxmox VE web interface. In the left-hand tree, click your node's name, then click >_ Shell near the top of the page. This opens a root terminal running directly on the Proxmox host, not inside any VM or container.

Paste in the following command and press Enter:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/bookstack.sh)"

This pulls the BookStack install script from the Proxmox VE Community Scripts project and runs it. You'll see a colored menu appear asking whether to use Default Settings or Advanced Settings.

For a first run, Default Settings is fine — it creates an unprivileged Debian 13 container with 1 CPU core, 1024 MB of RAM, and a 4 GB disk, and grabs an IP address over DHCP automatically. If you want to set a static IP up front, pick a specific container ID, or bump the RAM to something more comfortable, choose Advanced Settings instead. I'd bump the RAM to 2048 MB if you plan on uploading a lot of images to your pages — 1024 MB works, but it's tight once the page cache fills up.

Once you confirm your settings, the script does the rest: it creates the container, installs Apache, PHP 8.3, MariaDB, Git, and Composer, downloads BookStack, sets up the database, and runs the initial Laravel migrations that build out the schema. This usually takes two to three minutes depending on your internet connection.

If you did choose Advanced Settings, you'll be walked through a handful of prompts one at a time: the container ID (Proxmox suggests the next free number, and you can usually just accept it), hostname, disk size, CPU core count, RAM, the network bridge to attach to, and whether to use DHCP or a static IP/gateway you type in yourself. None of these are permanent decisions — you can resize the disk or bump the RAM later from the container's Resources tab in the Proxmox UI, so don't overthink it on the first pass.

Once the script finishes, glance at the Proxmox VE web UI and confirm the new container shows up in the left-hand tree with a green running icon. It's a quick sanity check before you go looking for problems that might just be a container that hasn't fully booted yet.

When it finishes, the script prints a line like:

Access it using the following URL:
http://192.168.1.147

Open that address in a browser on the same network. You should land on the BookStack login page.

Log in with the default credentials that ship with a fresh BookStack install:

  • Email: admin@admin.com
  • Password: password

The very first thing you should do — before creating a single page — is change that email and password. Click your profile icon in the top-right corner, choose Edit Profile, and update both fields. Anyone on your network who knows those default credentials otherwise has full admin access to whatever you write.

From there, create a Shelf, add a Book to it, and write a test page to confirm everything's working end to end. If the page saves and you can navigate back to it, your install is good.

Commands Explained

Let's break down what actually happened in that install command:

  • curl -fsSL <url> downloads the script from GitHub. The -f flag makes curl fail silently on server errors instead of printing an HTML error page, -s suppresses the progress bar, -S shows an error message if something does fail, and -L follows redirects.
  • The bash -c "$(...)" wrapper takes the downloaded script text and executes it immediately, without saving a file to disk first.

A couple of commands you'll want if you need to poke around inside the container later:

  • pct list — run on the Proxmox host, lists every container and its ID so you can find the one you just created.
  • pct enter <CTID> — drops you into a root shell inside the container, replacing <CTID> with the number shown by pct list.
  • cat /opt/bookstack/.env — run inside the container, shows the configuration file BookStack reads on startup, including the database credentials and the APP_URL setting.
  • systemctl status apache2 and systemctl status mariadb — run inside the container, tell you whether the web server and database are actually running.

To update BookStack later, run the exact same install command again, but from inside the Proxmox host shell (not inside the container). The script detects the existing installation and updates it in place instead of creating a second container.

Common Errors

A blank white page or a "500 Internal Server Error" when you first load the site almost always means the .env file has a bad value in it, or the storage folder doesn't have the right permissions. This is more common if you edited the .env file by hand and left a stray space or quote mark somewhere.

"This site can't be reached" usually means one of two things: the container isn't actually running (check the Proxmox VE web UI to confirm its status is green), or the container picked up a new DHCP lease and its IP address changed. That second one bites a lot of people who didn't set a static IP or a DHCP reservation up front.

If image uploads fail or thumbnails never generate, it's typically a permissions issue on the storage folder inside /opt/bookstack. The install script sets these correctly on a fresh install, so this usually only shows up after a manual file copy or a botched update.

Login rejected with correct-looking credentials? Double-check you're using admin@admin.com, not admin@admin.local or some other guess — it's an easy typo to make from memory.

If the install script itself fails partway through — usually with a Git or Composer error near the end — it's almost always a temporary network hiccup or GitHub rate-limiting a burst of requests. Wait a minute or two and re-run the exact same command; the script is safe to run again and will pick up where a partial install left off.

Troubleshooting

Start by confirming the container is actually up. In the Proxmox VE web UI, click the container in the left tree and check that its status shows green and running. If it's stopped, right-click it and choose Start.

From there, get into the container with pct enter <CTID> and check the two services BookStack depends on:

systemctl status apache2
systemctl status mariadb

If either shows as failed, restart it with systemctl restart apache2 or systemctl restart mariadb, then check the logs for the actual error:

tail -n 50 /var/log/apache2/error.log

If the app loads but throws database errors, confirm the credentials in /opt/bookstack/.env match what MariaDB actually has. You can test a login manually with mysql -u bookstack_user -p bookstack_db using the password from the .env file.

If the container's IP address changed and broke your login redirect, edit the APP_URL line in the .env file to match the new address, then clear the cache so BookStack picks it up:

cd /opt/bookstack
php artisan cache:clear

Honestly, most of this section becomes irrelevant the moment you set a static IP or a DHCP reservation for the container. Do that early and you'll skip half these headaches entirely.

One more spot worth checking if the install seemed to hang near the database step: run df -h inside the container. A 4 GB disk fills up faster than you'd expect once package caches and migration logs pile up, and a full disk causes MariaDB to fail in ways that don't always produce an obvious error message.

Best Practices

Set a static IP or a router-level DHCP reservation for this container before you write anything important in it. BookStack's APP_URL setting is tied to the address you access it through, and a surprise IP change is the single most common thing that breaks a working install.

Change the default admin email and password immediately after your first login — not later, not "after I finish setting things up." It takes thirty seconds and closes an obvious hole.

Back up the container regularly using Proxmox VE's built-in vzdump backups, either scheduled through the Datacenter backup jobs or triggered manually before any update. A wiki that's slowly become your team's or your household's source of truth is exactly the kind of thing you don't want to lose to a bad disk.

Don't expose port 80 directly to the internet if you want remote access. Put a reverse proxy in front of it (Nginx Proxy Manager works well for this) and terminate HTTPS there instead, so credentials and page content aren't traveling in plain text.

If you're running this for more than just yourself, look at BookStack's built-in roles and permissions rather than sharing the admin account. You can restrict editing to specific books or chapters per user, which matters more than it sounds like it would once more than one person is contributing.

Settle on a naming convention for shelves and books before you write fifty pages and regret it. It doesn't need to be fancy — "Homelab," "Networking," "Recipes" as shelves, with books underneath each — but retrofitting structure onto a pile of loose pages later is far more tedious than it sounds.

Frequently Asked Questions

Is BookStack free to use?
Yes. It's open source under the MIT license, with no paid tiers, seat limits, or feature gates.

Do I need to know Docker for this method?
No. The community script installs BookStack natively with Apache, PHP, and MariaDB directly inside the LXC container.

Can multiple people edit at the same time?
Yes, with individual accounts and permissions per book or chapter. There's no live co-editing like a Google Doc, though — edits are saved per page, one at a time.

Does BookStack support Markdown?
Yes. You can switch any page between the WYSIWYG editor and a Markdown editor from the page creation screen.

How much storage will I actually need?
The default 4 GB disk is plenty for text-heavy wikis. If you're uploading a lot of images or file attachments, give it more room upfront — resizing later means editing the container's disk in the Proxmox UI.

Can I reach this from outside my home network?
Yes, but don't just port-forward 80 straight to the container. Put it behind a reverse proxy with HTTPS, or connect over a VPN like WireGuard or Tailscale instead.

Conclusion

You now have a self-hosted wiki running on hardware you control, installed in a container light enough that you'll forget it's even using resources. The setup took one script and a few minutes — the actual work starts now, with whatever you decide to document first.

Start small. Write down the thing you always have to look up when something breaks, and build out from there. Six months from now, future-you will be glad this exists.