Skip to Content
Installation

Install BookStack

Document the routines in shelves, books and chapters, with a Swedish interface and the command that corrects the address afterwards.

Last reviewed:

What BookStack is

A documentation program built as a bookshelf system. At the top are shelves, in them books, in the books chapters, and in the chapters pages. The structure is fixed in advance, and that is the whole idea.

Most wiki programs let you create pages however you like, and after three months nobody has any idea where anything is. BookStack forces a decision at the moment the page is created: which book does this belong in? It feels stiff the first week and saves you in March.

One company uses it for its routines. One book for production, one for sales, one for everything to do with finances. The search function looks through the text, and every page has a history so you can see what was changed and by whom.

This is a server program

BookStack needs a web server and a database. Docker gives you both in one file. If you do not have Docker, start with Install Docker.

The program itself is free and open source. If you want to avoid running it yourself, there are companies that run BookStack for you for a fee, and the project lists them at bookstackapp.com.

Windows and Linux Mint

The same file on both. Create a folder called bookstack in the home folder, that is in C:\Users\ert-namn on Windows and in /home/ert-namn on Linux Mint. Put a text file in the folder called compose.yaml:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Stockholm
      - APP_URL=http://localhost:6875
      - APP_KEY=BYT_UT_MIG_NYCKEL
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_USERNAME=bookstack
      - DB_PASSWORD=BYT_UT_MIG_1
      - DB_DATABASE=bookstackapp
    volumes:
      - ./config:/config
    ports:
      - "6875:80"
    depends_on:
      - bookstack_db
    restart: unless-stopped

  bookstack_db:
    image: mariadb:11
    environment:
      - MARIADB_ROOT_PASSWORD=BYT_UT_MIG_2
      - MARIADB_DATABASE=bookstackapp
      - MARIADB_USER=bookstack
      - MARIADB_PASSWORD=BYT_UT_MIG_1
    volumes:
      - db:/var/lib/mysql
    restart: unless-stopped

volumes:
  db:

Three things need to be replaced. The two lines called BYT_UT_MIG_1 are the database password and must be identical. BYT_UT_MIG_2 is another password that only the database uses internally. Save both where the company saves passwords.

APP_KEY is special and cannot be just any string. It should look like the word base64: followed by exactly 44 characters. On Linux Mint you create one with the command below, and you paste the result into the file. We ran it, and it gives the right format:

echo "base64:$(openssl rand -base64 32)"

On Windows, openssl is not available by default, and Docker Desktop's internal Linux distribution is only there to run Docker itself, not a shell you can open and type commands in. Instead, run the image's own help command in PowerShell, it only requires Docker:

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

It prints a ready-made APP_KEY in the same format, which you paste into the file.

Open the terminal and go into the folder. On Windows that is PowerShell:

cd $HOME\bookstack

On Linux Mint the program is called Terminal:

cd ~/bookstack

Then start:

docker compose up -d

If the answer is that no compose.yaml was found, you are in the wrong folder. Otherwise wait one to two minutes while the database is set up and open http://localhost:6875. The default login is admin@admin.com with the password password. We ran this exact file, and the version that started was BookStack v26.05.5.

localhost is always the local computer. The wiki is therefore only visible on the machine it runs on, and if you send the address to someone in the company, that person ends up on their own computer. That is enough to build the structure and write the first pages. If the company is to read the same books, BookStack needs to run on a machine that stays on, and APP_URL should then point to that machine's address.

Three things to do first

  1. Change the password on the administrator account before you do anything else. password appears in every guide online, including this one.
  2. Change the display language to Swedish under the account settings (it was called Edit Profile in older versions, and is now under My Account). It only affects the interface, not the content, and makes BookStack considerably less intimidating for the person in the company who would rather avoid English.
  3. Create a book and write a real page in it the same evening. The structure is easy to love in theory and worthless without text.

The most common trap

Losing APP_KEY. BookStack encrypts certain data with that key, including settings for logging in against other services. If you restart with a new key, that data can no longer be read, and the error message rarely says that the key is the problem.

So save the key together with the passwords the moment you create it. If you make a backup of the config folder and the database but forget the key, you have a backup that cannot be fully restored.

The second common mistake is that the page loads but looks broken, without images and formatting. Then APP_URL points to the wrong address. Enter exactly the address you type in the browser, including the port number, and run docker compose up -d again. If you have already created pages, old links in the text may point wrong, and then there is a built-in command that rewrites them:

docker compose exec bookstack php /app/www/artisan bookstack:update-url http://gamla-adressen http://nya-adressen
Back to the guides

Cart