absulli

absulli

Docker app from operationETH's Repository

ABSulli is an Audiobookshelf companion dashboard inspired by the concept of Tautulli.

Overview
ABSulli is an Audiobookshelf companion dashboard inspired by the concept of Tautulli. Track audiobook and podcast listening activity, browse library stats, view history, manage notifications, and expose Prometheus metrics from one self-hosted web interface.

Logo Banner

A self-hosted companion dashboard for Audiobookshelf

Current Release License Docker Hub Pulls GHCR Pulls Unraid Community Apps Discord


[!NOTE] AI assistance was used during development of this project. The code has been reviewed and tested to the best of my ability, but ABSulli is still under active development. Users should review and validate it for their own environment before relying on it. If you find a bug, please open an issue.

ABSulli is an Audiobookshelf companion dashboard inspired by the concept of Tautulli. Track audiobook and podcast listening activity, browse library stats, view history, manage notifications, and expose Prometheus metrics from one self-hosted web interface.


Features

  • First-run setup wizard - no config file needed to get started
  • GUI settings management with optional environment variable overrides
  • Current listening activity
  • Library and user overview
  • Recently added media
  • Listening history
  • Built-in graphs and Prometheus metrics endpoint
  • Notification support (Gotify, ntfy, Discord, Slack, Telegram, Pushover, Pushbullet, Email, Webhook)
  • Private RSS feed for newly added media
  • Local SQLite storage - no external database
  • Built-in login with rate limiting and audit logging

Screenshots

ABSulli Screenshot 1 ABSulli Screenshot 2 ABSulli Screenshot 3 ABSulli Screenshot 4 ABSulli Screenshot 5 ABSulli Screenshot 6 ABSulli Screenshot 7


Quick start

docker-compose.yml

services:
  absulli:
    image: ghcr.io/operationeth/absulli:latest
    container_name: absulli
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    ports:
      - "8272:8272"
    environment:
      - TZ=America/Phoenix
      - PUID=1000
      - PGID=1000
    volumes:
      - ./data:/config
docker compose up -d

Then open http://<server-ip>:8272 and follow the setup wizard.

The wizard will ask for your Audiobookshelf URL and API key, create an admin login, and immediately start importing your data. No .env file required.

[!IMPORTANT] Until setup is finished, anyone who can reach port 8272 can complete the wizard and create the admin account. Run setup right after starting the container.

After setup, application settings can be managed from the Settings page.


Getting your Audiobookshelf API key

  1. Open Audiobookshelf and go to Settings → API-keys → Add API Key
  2. Name it ABSulli
  3. Select an admin user
  4. Copy the API token from the token field

ABSulli needs an Admin account to read users and listening sessions. To limit what the key can do, create a dedicated Audiobookshelf admin user for ABSulli and set its permissions as follows:

Permission Setting Reason
Can Download Off ABSulli only reads data
Can Update Off ABSulli only reads data
Can Delete Off ABSulli only reads data
Can Upload Off ABSulli only reads data
Can Create Ereader Off ABSulli only reads data
Can Access Explicit Content On Explicit items are hidden from ABSulli otherwise
Can Access All Libraries On Unselected libraries are hidden from ABSulli otherwise
Can Access All Tags On Items with restricted tags are hidden from ABSulli otherwise

These toggles don't remove admin-level access, such as managing users and server settings, so keep the key private.


Optional: pre-fill with environment variables

If you prefer to manage the Audiobookshelf connection via env rather than the setup wizard, create a .env file next to your docker-compose.yml:

ABS_URL=http://192.168.1.50:13378
ABS_API_KEY=your_abs_api_key_here

When these are set, the setup wizard shows them as read-only and uses them automatically.


API access

When authentication is enabled, the API token gives read-only GET access to:

  • /api/v1/status
  • /api/v1/activity
  • /api/v1/history
  • /api/v1/users
  • /api/v1/libraries

Deprecated /api/ aliases still work. Send the token as X-API-Key, X-Absulli-Api-Token, or Authorization: Bearer.

The API token can't open the admin UI, change settings, run jobs, or revoke sessions. To revoke all browser sessions, use Sign out everywhere in Settings. Prometheus /metrics needs its own metrics token.


Prometheus metrics

ABSulli exposes Prometheus metrics at /metrics. This can be scraped by Prometheus for Grafana dashboards or external monitoring.

To scrape with authentication enabled, configure a metrics token in Settings → Network and send it as a bearer token or with the X-Absulli-Metrics-Token header.


RSS feed

ABSulli can provide a private RSS feed containing new books, podcasts, and podcast episodes detected after the feed is enabled. Open Settings → Notifications, enable the RSS feed, save the settings, and copy the generated URL into your feed reader.

The feed contains up to 100 of the most recently detected books, podcasts, and podcast episodes. Anyone with the URL can read it without signing in to ABSulli. Disabling the feed blocks access. Regenerating the URL immediately invalidates the previous one.

Set the ABSulli Public URL under Settings → Network when the generated feed URL should use a reverse proxy address.

[!NOTE] The RSS feed must be reachable by the RSS reader. Remote readers may require a VPN, reverse proxy, or other external access configuration.


Data and privacy

ABSulli stores all data locally in /config:

File Contents
absulli.db SQLite database - activity, history, settings
secret_key Session signing key - keep private

ABSulli talks to your Audiobookshelf instance and checks GitHub (api.github.com) for new releases. No listening data or credentials are included in update checks. Notification requests are only sent if you configure notification agents.

The /config directory and its backups contain listening data and sensitive credentials, including Audiobookshelf and notification tokens. Keep the directory and all backups private. Do not upload absulli.db to bug reports or commit it to a repository. ABSulli restricts the directory to its container user and creates sensitive files with owner-only permissions.


Upgrading

Before upgrading, back up your config directory. The most important file is /config/absulli.db, which contains your ABSulli settings, activity, and listening history. If you use the example compose file, that is usually ./data/absulli.db on the host.

To upgrade a Docker install:

docker compose pull
docker compose up -d

ABSulli runs database migrations automatically during startup. Watch the logs after upgrading to confirm the app starts cleanly:

docker logs absulli -f

For local development builds, rebuild and restart instead:

docker compose build --no-cache
docker compose up -d

Database migrations

ABSulli uses Alembic for database schema migrations. Migrations run automatically on startup.

Existing installs created before Alembic are safely baselined on first start: ABSulli keeps the old additive column check for that one upgrade path, stamps the database at the current migration, and future schema changes are handled through Alembic revisions.


Reverse proxy

ABSulli runs on port 8272 by default. Proxy to http://absulli:8272, and if serving over HTTPS, enable HTTPS Secure Cookies in Settings → Network or set ABSULLI_COOKIE_SECURE=true.

ABSulli sets its own security headers (Content-Security-Policy, X-Frame-Options, Referrer-Policy, etc.) on every response. You do not need to add these in your proxy config.

To rate-limit logins by client IP behind a reverse proxy:

  1. Enable proxy trust in Settings → Network or set ABSULLI_TRUST_PROXY=true.
  2. Add your reverse proxy's IP under Trusted Proxy IP Addresses or ABSULLI_TRUSTED_PROXY_IPS. Use a static IP and avoid trusting entire Docker subnets.
  3. Restrict direct access to port 8272 with firewall rules or Docker networking.

ABSulli uses the last X-Forwarded-For address for login rate limiting. Your reverse proxy must append the client IP to this header.


Notification cover art

Gotify and Discord notifications can include cover art. Set the ABSulli Public URL under Settings → Network and enable Include Cover Art for the agent. Leave the Public URL blank to send notifications without covers.

ABSulli uploads Discord covers itself, so only ABSulli needs to reach the Public URL. Gotify loads the cover from the Public URL, so every device showing the notification must be able to reach it.

[!NOTE] If Gotify's web UI runs on a public address and the Public URL resolves to a local IP, browsers may block the cover. In Chrome, allow Local network access in the site settings for your Gotify web UI.


Security

ABSulli ships with the following enabled by default:

  • PBKDF2-SHA256 (600,000 iterations) for password storage
  • Signed session cookies with server-side revocation
  • Per-request CSP nonces - no unsafe-inline
  • Login rate limiting with lockout, persisted across restarts
  • Login audit log (IP, user agent, outcome, reason)
  • CSRF protection on all form submissions
  • Separate API and metrics tokens with independent scopes
  • Runs as a non-root user with read-only application files

Authentication is enabled by default after setup. Keep it enabled for all installs.


Categories

Download Statistics

9,163
Total Downloads

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/operationeth/absulli:latest
Last Updated2026-10-27
First Seen2026-09-08

Runtime arguments

Web UI
http://[IP]:[PORT:8272]/
Network
bridge
Shell
sh
Privileged
false
Extra Params
--restart unless-stopped --security-opt no-new-privileges:true

Template configuration

WebUI PortPorttcp
Target
8272
Value
8272
ConfigPathrw
Target
/config
Default
/mnt/user/appdata/absulli
Value
/mnt/user/appdata/absulli
PUIDVariable
Default
1000
Value
1000
PGIDVariable
Value
1000
TZVariable
Value
UTC