Skip to main content

1.3.2.1 Docker Installation

This installation walks you through installing Bookstack on a machine that already runs docker. This could be a VM or a dedicated bare metal machine. Hence, it is assumed that you run a machine where docker is already installed with a fixed private IPv4 address attached to it.

1. The first thing I like to do is setup my reverse proxy to point to the VM or server that the application will be hosted on. I use the Caddy reverse proxy plugin created for my OPNSense firewall. This is extremely simple for a home lab since it provides a great WebGui and it is all handled on my router instead of on my servers. You can of course choose your own port but in this case I setup the following Caddy entry

2. The next thing we need to do is create an APP_KEY. So what is that ? Well The APP_KEY in Bookstack is used for session encryption and security purposes, ensuring that sensitive data is protected during user sessions. It is a unique key that helps secure the application against various types of attacks. For this enter your docker machine and generate the key with

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

3. If run correctly it will spit out an APP_KEY in the following format

base64:A8PyIIbsR8FZT+5F6QoZYVQesoJvJ0rsP3LXyzGdhHg=

4. Copy the APP_KEY including the base64 to a place that you can retrieve it from again later.

5. I assume that you have a dedicated docker folder in which you keep all your docker projects. If not you can create it with the following code below that will create a docker folder and inside it a bookstack folder.

mkdir -p docker/bookstack

6. Enter the docker/bookstack folder and create a new docker compose file with 

nano compose.yml

7. Then copy paste the boilerplate below inside of it.

Docker Compose File 
services:
  # The container for BookStack itself
  bookstack:
    # You should update the version here to match the latest
    # release of BookStack: https://github.com/BookStackApp/BookStack/releases
    # You'll change this when wanting to update the version of BookStack used.
    image: lscr.io/linuxserver/bookstack:version-v26.03.3
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      # APP_URL must be set as the base URL you'd expect to access BookStack
      # on via the browser. The default shown here is what you might use if accessing
      # direct from the browser on the docker host, hence the use of the port as configured below.
      - APP_URL=https://docs.rfeyn.org
      # APP_KEY must be a unique key. Generate your own by running
      # docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
      # You should keep the "base64:" part for the option value.
      - APP_KEY=base64:XSuNYw6vfOmXJ3kZfaloEVNE39BEClMrDXOlc2TIGT8=
      # The below database details are purposefully aligned with those
      # configured for the "mariadb" service below:
      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_DATABASE=sdf092jefjsdlkfj203fjlksdjfdsf
      - DB_USERNAME=9823fj98fj32jf0sjodfijsdf
      - DB_PASSWORD=j2j93jfjsodiifj023jf8349j93jfksjdfdf
    volumes:
      # You generally only ever need to map this one volume.
      # This maps it to a "bookstack_app_data" folder in the same
      # directory as this compose config file.
      - ./bookstack_app_data:/config
    ports:
      # This exposes port 6875 for general web access.
      # Commonly you'd have a reverse proxy in front of this,
      # redirecting incoming requests to this port.
      - 6875:80
    restart: unless-stopped
  # The container for the database which BookStack will use to store
  # most of its core data/content.
  mariadb:
    # You should update the version here to match the latest
    # main version of the linuxserver mariadb container version:
    # https://github.com/linuxserver/docker-mariadb/pkgs/container/mariadb/versions?filters%5Bversion_type%5D=tagged
    image: lscr.io/linuxserver/mariadb:11.4.9
    container_name: bookstack_mariadb
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      # You may want to change the credentials used below,
      # but be aware the latter three options need to align
      # with the DB_* options for the BookStack container.
      - MYSQL_ROOT_PASSWORD=sdfjop2fjisodifj203f9j0jfsklfjls
      - MYSQL_DATABASE=sdf092jefjsdlkfj203fjlksdjfdsf
      - MYSQL_USER=9823fj98fj32jf0sjodfijsdf
      - MYSQL_PASSWORD=j2j93jfjsodiifj023jf8349j93jfksjdfdf
    volumes:
      # You generally only ever need to map this one volume.
      # This maps it to a "bookstack_db_data" folder in the same
      # directory as this compose config file.
      # If you're hosting this stack on Windows, you may instead need to
      # use a named docker volume instead of a local path due to
      # filesystem issues causing problems with local mounts on Windows.
      - ./bookstack_db_data:/config
    # These ports are commented out as you don't really need this port
    # exposed for normal use, mainly only if connecting direct the the
    # database externally. Otherwise, this risks exposing access to the
    # database when not needed.
    # ports:
    #   - 3306:3306
    restart: unless-stopped

8. What is important to change in your docker compose file from the boiler plate is the following 

  • APP_URL=https://docs.example.org

  • APP_KEY=base64:Xjslkdjf....

  • DB_DATABASE=databaseusername

  • DB_USERNAME=bookstackusername

  • DB_PASSWORD=bookstackpassword

  •  MYSQL_ROOT_PASSWORD=randompassword

  • MYSQL_DATABASE=databaseusername

  • MYSQL_USER=bookstackusername

  • MYSQL_PASSWORD=bookstackpassword

If these are all changed then you are ready to run the application inside of the folder where the docker compose file is stored with docker compose up. I like to use docker compose up instead of docker compose up -d on the first run to see if the logs give any errors. Then you can directly fix what's wrong ;)

docker compose up 

9.  If the DNS and reverse proxy are set correctly you should now be able to launch your bookstack instance at https://docs.example.org

10. The first time login requires the following credentials

11. After Login I would recommend to directly change your username and password and save the credentials in an open source password manager like Vaultwarden.

Back to top