Install Guide

The installation of Bunko Shelf is done through a Node.js command and you can choose between two methods to store your book library:

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

According to the method you choose, you will need to configure the LIB_PROVIDER environment variable in the .env file as local or cloud. The following sections describe both methods.

Reverse proxy required

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

Local library (on disk)

Start a Bunko Shelf instance

Inside the project directory, run the following command:

npx @itsmrtr/bunkoshelf .

The wizard will create:

.env local with the necessary environment variables
package.json minimum for it to work
Installation of the @itsmrtr/bunkoshelf package dependency

Configure the environment variables

The wizard will create a .env file with the following variables:

DATABASE_URL=postgresql://user:password@localhost:5432/bunkoshelf
JWT_SECRET=
PORT=3060
SITE_URL=http://localhost:3060
LIB_PROVIDER=local

Replace the value of DATABASE_URL with the URL of your PostgreSQL database. The value of JWT_SECRET will be generated automatically by the wizard. SITE_URL is the URL where your Bunko Shelf instance will be hosted and LIB_PROVIDER must be local for this installation method.

Start Bunko Shelf

npm start

Update Bunko Shelf

When a new version is available, you can update your instance using the following command:

npm run update

Remote library (cloud storage)

Start a Bunko Shelf instance

Inside the project directory, run the following command:

npx @itsmrtr/bunkoshelf . --cloud

The wizard will create:

.env local with the necessary environment variables
package.json minimum for it to work
Installation of the @itsmrtr/bunkoshelf package dependency

Configure the environment variables

The wizard will create a .env file with the following variables:

DATABASE_URL=postgresql://user:password@localhost:5432/bunkoshelf
JWT_SECRET=
PORT=3060
SITE_URL=http://localhost:3060
LIB_PROVIDER=cloud
R2_ENDPOINT=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET_NAME=bunko-shelf

To configure cloud storage, in this example the configuration for Cloudflare R2 is shown and you will find the values in your Cloudflare account. Place your bucket's endpoint in R2_ENDPOINT, the access keys in R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY and the bucket name in R2_BUCKET_NAME.

Start Bunko Shelf

npm start

Update Bunko Shelf

When a new version is available, you can update your instance using the following command:

npm run update

CORS Configuration

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

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

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

Bucket Privacy

Bunko Shelf utilizes pre-signed URLs to access files in the bucket, meaning the bucket can remain private and not be publicly accessible. Pre-signed URLs allow the application to access files securely without exposing the bucket to the public, which is the recommended approach for maintaining file privacy.

Save 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.