Docker

The installation of Bunko Shelf is done using a Docker container and you can choose between two methods to store your book library:

Local library (on disk)
Remote library (cloud storage)

Depending on the method you choose, you must configure the LIB_PROVIDER environment variable in the compose.yml file as local or cloud. Both methods are described below.

Reverse proxy required

To use Bunko Shelf it is necessary to set up a reverse proxy (for example with Nginx or Traefik) and install a valid SSL certificate (Let's Encrypt).

Local library (on disk)

Create the Docker Compose

Below is an example of a Docker Compose (compose.yml) file that you can use to initialize your container; you can also find at the end of this guide how to generate the value for the JWT_SECRET variable.

services:
  bunkoshelf:
    image: itsmrtr/bunkoshelf:latest
    container_name: bunkoshelf
    restart: unless-stopped
    ports:
      - 3000:3000
    environment:
      NEXT_PUBLIC_SITE_URL: https://your-domain.com
      JWT_SECRET:
      LIB_PROVIDER: local
    volumes:
      - bunkoshelf_data:/app/prisma/data
      - bunkoshelf_covers:/app/public/covers

volumes:
  bunkoshelf_data:
  bunkoshelf_covers:

Start the container

docker compose up -d

Update the container

When a new image is available, you can update your container using these commands:

docker compose pull
docker compose up -d

Remote library (cloud storage)

Create the Docker Compose

Below is an example of a Docker Compose (compose.yml) file that you can use to initialize your container. Unlike the local installation method, in this case you must provide your R2 Bucket credentials in the corresponding environment variables. Also, there are a number of additional steps you must follow to properly configure R2 access and the application's operation.

services:
  bunkoshelf:
    image: itsmrtr/bunkoshelf:latest
    container_name: bunkoshelf
    restart: unless-stopped
    ports:
      - 3000:3000
    environment:
      NEXT_PUBLIC_SITE_URL: https://your-domain.com
      JWT_SECRET:
      LIB_PROVIDER: cloud
      R2_ENDPOINT:
      R2_ACCESS_KEY_ID:
      R2_SECRET_ACCESS_KEY:
      R2_BUCKET_NAME:
    volumes:
      - bunkoshelf_data:/app/prisma/data
      - bunkoshelf_covers:/app/public/covers

volumes:
  bunkoshelf_data:
  bunkoshelf_covers:

Start the container

docker compose up -d

Update the container

When a new image is available, you can update your container using these commands:

docker compose pull
docker compose up -d

CORS configuration

To allow the application to load/access files directly from R2 via pre-signed URLs, you must configure CORS rules on the bucket. These rules authorize your domain to make requests from the browser, enabling methods such as GET or PUT and allowing the headers used during download or upload. Without this configuration, the browser will block requests before they reach the bucket.

Log in to your Cloudflare account and navigate to the R2 Object Storage section, then in the Overview panel select your bucket to access its contents and settings. In the bucket settings, look for the CORS Policy section and click the Edit button, paste the following code changing the example domain to the one you will use for Bunko Shelf.

 [
  {
    "AllowedOrigins": [
      "https://your-domain.com"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "HEAD"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [
      "ETag"
    ],
    "MaxAgeSeconds": 3600
  }
]

Save the changes and you're done

Once you have pasted the code and changed the domain, save the changes to apply the CORS configuration and then you can use Bunko Shelf with Cloudflare R2 without issues.

Generate a JWT

A JWT (JSON Web Token) is a compact token that carries verified information between client and server. The data is encoded and accompanied by a signature that allows confirming the content has not been altered. This allows authenticating requests without resending credentials on every interaction.

Create the JWT

To generate a JWT, paste the following command into your terminal according to your operating system:

Debian (Linux) and macOS

tr -dc 'A-Za-z0-9' </dev/urandom | head -c 64

Windows 10/11 (PowerShell)

-join ((48..57 + 65..90 + 97..122) | Get-Random -Count 64 | % {[char]$_})

Use the JWT

Once generated, copy the JWT and paste it into the JWT_SECRET environment variable in your compose.yml.