Documentation

• 1: Getting Started
• 1.1: Running the app
• 1.1.1: Docker
• 1.1.2: Docker Compose
• 1.1.3: Kubernetes
• 1.1.4: Bare Metal
• 1.2: First Login
• 2: Tutorials
• 2.1: Notifications
• 2.2: OpenID Connect
• 3: Concepts
• 3.1: Environment Variables
• 4: Local Development
• 5: Contribution Guidelines

1 - Getting Started

Prerequisites

AudioBookRequest has been packaged as a Docker image to make it easy to deploy and run on servers. While it is possible to run ABR without Docker, that option should be avoided if possible and only used for local development, as a lot of things can change from version to version.

Setup

Head to Running the app for instructions on how to run ABR.

1.1 - Running the app

The app has a docker image that simplifies the deployment. The preferred methods of running the application all revolve around running the Docker image in different ways.

Select the method you want to use to deploy below or if your tool is not listed (for example Portainer), head to the docker page.

1.1.1 - Docker

If you prefer to run the app manually with docker, you can simply run the following command:

docker run -p 8000:8000 -v $(pwd)/config:/config markbeep/audiobookrequest:1

This will start the container on port 8000 and create the config/ directory in your current working directory.

The above command might break on Windows. Instead, use ${PWD}\config:/config ... in PowerShell or %cd%\config:/config ... in Windows Command Prompt.

1.1.2 - Docker Compose

Docker-compose works the similar way as Docker.

The basic docker compose file is as follows:

services:
  web:
    image: markbeep/audiobookrequest:1
    ports:
      - '8000:8000'
    volumes:
      - ./config:/config

If you want to add any environment variables, you can add them as explained here. It would look along the lines of this:

services:
  web:
    image: markbeep/audiobookrequest:1
    ports:
      - '8000:5432'
    volumes:
      - ./config:/config
    environment:
      ABR_APP__PORT: 5432
      ABR_APP__OPENAPI_ENABLED: true

1.1.3 - Kubernetes

Here’s an example for a kubernetes deployment file you’d use:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: audiobookrequest
  labels:
    app: audiobookrequest
spec:
  replicas: 1
  selector:
    matchLabels:
      app: audiobookrequest
  template:
    metadata:
      labels:
        app: audiobookrequest
    spec:
      containers:
        - name: audiobookrequest
          image: markbeep/audiobookrequest:1
          imagePullPolicy: Always
          volumeMounts:
            - mountPath: /config
              name: abr-config
          ports:
            - name: http-request
              containerPort: 8000
      volumes:
        - name: abr-config
          hostPath:
            path: /mnt/disk/AudioBookRequest/

For the volume you can assign it a host path on a node, or assign it to a PVC.

1.1.4 - Bare Metal

To run ABR locally without Docker, the same steps as for the local development have to be followed. First, follow the instructions to get local development working.

Once local development works, there are a few adjustments that have to be made to run the app in production mode instead of debug/local mode.

1. Delete the .env.local file or delete all contents in it.
2. Run the python script to fetch and download all required javascript files: uv run python /app/util/fetch_js.py. This should populate your static/ directory with some new js files.
3. Instead of running fastapi dev you want to execute fastapi start to start the webserver.
4. Create a file called .env and place any environment variables you want to set in there.
5. If you intend to change the port (documented as the env variable ABR_APP__PORT), you’ll have to run fastapi with the --port <PORT> flag:

   fastapi run --port 5432
   

With these changes your deployment will be running in production mode.

1.2 - First Login

Once you get AudioBookRequest running, you’ll be greeted with an initialization page when you visit the website.

On this page you have to set the type of login you want to use for the app and then create the login details for the root admin. You can choose from 3 login types on this page:

• Basic Auth: This is the most simple form of login. Your browser will show a popup login dialog which will then be used to log in to the site. Password managers usually don’t work for this type of login, but because it is very simple you can also easily send authenticated requests in scripts. Read more here.
• Forms: This is the standard type of login where you fill out a login-form. Password managers usually work with this.
• None: This turns off all authentication. This is best if you have a proxy and are the only user or you don’t mind everyone having root access to the site.

2 - Tutorials

2.1 - Notifications

Notifications allow you to send a POST request/webhook wherever you want. ABR works with all major notification systems like apprise, gotify, ntfy, and discord.

Here are a few examples for how the notifications body looks for different notification systems:

Apprise

For apprise you’ll want to have the title in "title" and the message body in "body".

Gotify

For gotify you’ll want to have the title in "title" and the message body in "message". Gotify also requires you to pass in your authorization token in the header.

Ntfy

Ntfy does not differentiate between title and body. You’ll want to select the text body type and then add your message.

Discord

You can send notifications to discord by using webhooks. Discord allows you to send plain messages or create bigger messages with embeds.

To make better looking webhook messages you can also use a message builder like one of the following pages:

• https://message.style/app/editor (Copy the JSON code)
• https://discohook.app (Options>JSON Editor to export)

2.2 - OpenID Connect

OIDC allows you to use the same login across multiple apps. This guide will show you how to set up OIDC with Authentik, but the concepts are the same or similar for other providers.

Setup a provider on Authentik

1. You want to first create an application on Authentik. The settings here don’t play a role for AudioBookRequest though.

2. You then want to create an OAuth2/OpenID Provider:

   

3. Configure the settings as preferred. The important two values are the Client ID and Client Secret. Take note of those. You should also set the redirect URL that the OIDC provider will redirect you to after a succesful login. This has to be the domain of your ABR instance with /auth/oidc appended.

   

   Warning

   Make sure you correctly set http or https in the redirect URL. This depends on how you access AudioBookRequest.

4. Set the scopes that ABR can get access to. You should always allow for the openid scope. Any other scopes are optional. You’ll have to check with your OIDC provider to see what what scopes are required to get a name/username and groups. “Subject mode” is a unique identifier for the user. This can be used as the username on ABR.

   

5. Assign your newly created provider to the ABR application.

Setup settings in ABR

1. On AudioBookRequest, head to Settings>Security and set the “Login Type” to “OpenID Connect”.
2. Paste the “Client ID” and “Client Secret” into the respective fields.
3. Your “OIDC Configuration Endpoint” depends on the OIDC provider you use. For Authentik, it’s usually along the lines of https://domain.com/application/o/audiobookrequest/.well-known/openid-configuration. You’ll have to find that for your own provider. Visiting the url should give you a JSON-formatted object with different endpoints and details given.
4. The “OIDC Scopes” are the ones defined above separated by a space. openid is always required. Any other scopes like email or group are only required if you intend to use the email for the username or respectively extract the group of the user.
5. “OIDC Username Claim” has to be a unique identifier which is used as the username for the user. sub is always available, but you might prefere to use email or username (with the correctly added scope).
6. Depending on what you used above for the redirect URL, set http or https.

   Warning

   http/s has to match-up with what protocol your redirect-url uses. Providers will reject logins if this does not match up.
7. Optional: The “OIDC Logout URL” is where you’re redirected if you select to log out in ABR. OIDC Providers allow you to invalidate the session on this URL. While this value is optional, not adding it might break logging out slightly because the session can’t properly be invalidated.

Groups

“OIDC Group Claim” is optional, but allows you to handle the role distribution of users in your OIDC provider instead of in ABR. The exact claim that sends along the information depends on your OIDC provider. The OIDC provider can provide a single string or list of strings.

The groups have to be named exactly one of untrusted, trusted, or admin. The letter case does not matter.

3 - Concepts

3.1 - Environment Variables

4 - Local Development

Requirements

• Python >3.12
• uv. Used as the package manager
• node.js. Exact version is not too important. Too old versions might fail when installing packages.

Setup

Virtual environments help isolate any installed packages to this directory. Project was made with Python 3.12 and uses new generics introduced in 3.12. Older python versions might not work or could have incorrect typing.

For improved dependency management, uv is used instead of pip.

# This creates the venv as well as installs all dependencies
uv sync

For local development, environment variables can be added to .env.local and they’ll be used wherever required. This file is not used in production.

Initialize Database

Alembic is used to create database migrations. Run the following before starting up the application for the first time. It will initialize the directory if non-existant, create the database file as well as execute any required migrations.

uv run alembic upgrade heads

In case of any model changes, remember to create migrations using alembic revision --autogenerate -m "<message>".

Generate the CSS files

Tailwindcss is used to style elements using CSS. On top of that, daisyUI is for easy and consistent component styling.

Install daisyUI and start Tailwindcss watcher. Required for any CSS styling.

npm i
uv run tailwindcss -i static/tw.css -o static/globals.css --watch
# Alternatively npx can be used to run tailwindcss
npx @tailwindcss/cli@4 -i static/tw.css -o static/globals.css --watch

Tailwind has to run anytime something is changed in the HTML template files.

Run the app

Running the application is best done in multiple terminals:

1. Start FastAPI dev mode:

   uv run fastapi dev
   

   Website can be visited at http://localhost:8000.

2. Optional: Start browser-sync. This hot reloads the website when the html template or python files are modified:

browser-sync http://localhost:8000 --files templates/** --files app/**

NOTE: Website has to be visited at http://localhost:3000 instead.

Docker Compose

The docker compose can also be used to run the app locally. Any services that are required can be added to it for easy testing:

docker compose up --build

The local context (ABR) is in a docker compose profile called local, which is only run if explicitly stated as follows:

docker compose --profile local up

5 - Contribution Guidelines

We use Hugo to format and generate our website, the Docsy theme for styling and site structure, and Github Pages to manage the deployment of the site. Hugo is an open-source static site generator that provides us with templates, content organisation in a standard directory structure, and a website generation engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.

All submissions require review. We use GitHub pullas requests for this purpose. Consult GitHub Help for more information on using pull requests.

Quick start with Hugo

Here’s a quick guide to updating the docs. It assumes you’re familiar with the GitHub workflow and you’re happy to use the automated preview of your doc updates:

1. Fork the AudioBookRequest repo on GitHub.
2. Make your changes and send a pull request (PR).
3. If you’re not yet ready for a review, add “WIP” to the PR name to indicate it’s a work in progress. (Don’t add the Hugo property “draft = true” to the page front matter, because that prevents the auto-deployment of the content preview described in the next point.)
4. When you’re ready for a review, add a comment to the PR, and remove any “WIP” markers.

Updating a single page

If you’ve just spotted something you’d like to change while using the docs, Docsy has a shortcut for you:

1. Click Edit this page in the top right hand corner of the page.
2. If you don’t already have an up to date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
3. Follow the rest of the Quick start with Hugo process above to make, preview, and propose your changes.

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

1. Follow the instructions in Getting started to install Hugo and any other tools you need. You’ll need at least Hugo version 0.146.0 (we recommend using the most recent available version), and it must be the extended version, which supports SCSS.

2. Fork the AudioBookRequest repo into your own project, then create a local copy using git clone.

   git clone --branch v0.12.0 --depth 1 https://github.com/markbeep/AudioBookRequest.git
   

3. Run hugo server in the site root directory. By default your site will be available at http://localhost:1313/. Now that you’re serving your site locally, Hugo will watch for changes to the content and automatically refresh your site.

4. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request.

Creating an issue

If you’ve found a problem in the docs, but you’re not sure how to fix it yourself, please create an issue in the AudioBookRequest repo. You can also create an issue about a specific page by clicking the Create Issue button in the top right hand corner of the page.

Useful resources

• Docsy user guide: All about Docsy, including how it manages navigation, look and feel, and multi-language support.
• Hugo documentation: Comprehensive reference for Hugo.
• Github Hello World!: A basic introduction to GitHub concepts and workflow.