Pageless

A self-hosted audiobook server built with Phoenix LiveView.

Highlights

• Scan filesystem libraries for .m4b audiobooks and accompanying metadata.
• Browse and search the library; filter by authors, narrators, publishers, language, genres, series, collections, playlists, libraries, and listening progress; and sort by metadata, dates, size, duration, or progress timestamps.
• Stream audio in the browser, track listening progress, manage bookmarks, and organize books into series, collections, and playlists.
• Use the offline-first native Android client through the token-authenticated JSON API.

Local development with Docker (recommended)

Requires Docker with Compose v2.

# (Optional) point at a host folder of audiobooks to scan.
# Defaults to ./audiobooks if unset.
export PAGELESS_LIBRARY_DIR=/path/to/your/audiobooks

docker compose up

The app is served at localhost:5050. On first boot it installs deps, creates/migrates the database, and seeds a default admin:

• email: admin@example.com
• password: changemechangeme

Inside the container your audiobooks are mounted at /audiobooks — use that path when adding a library folder in Manage Libraries. Extracted cover art is persisted in the media volume at /data/media.

Useful commands:

docker compose exec app mix test          # run the test suite
docker compose exec app iex -S mix         # an IEx shell
docker compose down                        # stop (add -v to wipe volumes)

Local development without Docker

Requires Elixir, PostgreSQL, and ffmpeg/ffprobe on your PATH.

• Run mix setup to install dependencies and set up the database
• Start the server with mix phx.server (or iex -S mix phx.server)

Now you can visit localhost:5050 from your browser.

Production image

A multi-stage Dockerfile builds an OTP release. It requires DATABASE_URL and SECRET_KEY_BASE at runtime, and respects PAGELESS_MEDIA_PATH (defaults to /data/media). The entrypoint runs migrations before booting.

The release workflow publishes Docker images to Docker Hub as:

• dcaixinha/pageless:<timestamp>-<sha>
• dcaixinha/pageless:latest

Release tags are timestamp-based app releases, not SemVer library versions. They use UTC format YYYYMMDDHHMMSS-<short-sha> and are generated by the manual GitHub Actions release workflow.

The same value is passed into the Docker image as PAGELESS_VERSION, which is returned by the mobile /api/me response as server_version.

For a self-hosted Docker Compose example, reverse-proxy notes, and first-boot setup steps, see docs/self-hosting.md.

Ready to run in production? Please check our deployment guides.

Learn more

• Official website: https://www.phoenixframework.org/
• Guides: https://phoenix.hexdocs.pm/overview.html
• Docs: https://phoenix.hexdocs.pm
• Forum: https://elixirforum.com/c/phoenix-forum
• Source: https://github.com/phoenixframework/phoenix

License

Copyright (C) 2026 Pageless contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.