Getting started ​

Requirements ​

• Docker (recommended) — or Node.js 22+ to run from source
• Somewhere to put comics — a local folder or a network share

Install with Docker (recommended) ​

The published image is ghcr.io/backissueapp/backissue — latest tracks releases, version tags (e.g. 0.8.4) pin a release, and nightly is the newest development build.

Every one of those tags also has a browser build, the same tag with -browser on the end (latest-browser, 0.8.4-browser, nightly-browser). It bundles a real Chromium and a virtual display, which makes it roughly a gigabyte larger, so run the lean image unless something asks you not to. What asks is a download source: a few sites escalate headless browsers — FlareSolverr included — to a manual captcha, and only a real browser window gets through. Those sources say they need the browser build; on the lean one they stay switched off and their card says why. See Download sources.

With Docker Compose:

services:
  backissue:
    image: ghcr.io/backissueapp/backissue:latest
    container_name: backissue
    ports:
      - "8787:8787"
    volumes:
      - ./data:/data              # database, settings, installed plugins
      - /path/to/comics:/comics   # your comic library
    environment:
      - PUID=99    # file owner for /data and imported comics (run `id` for yours)
      - PGID=100
      - UMASK=022
      - TZ=Europe/Dublin   # local time for schedules
    restart: unless-stopped

docker compose up -d

Or with plain docker run:

docker run -d -p 8787:8787 \
  -e PUID=99 -e PGID=100 -e TZ=Europe/Dublin \
  -v /path/to/data:/data \
  -v /path/to/comics:/comics \
  ghcr.io/backissueapp/backissue:latest

Those four variables are the ones almost everyone sets; the rest, including what to do behind a reverse proxy and how to serve on a different port, are in the environment variable reference.

Then open http://localhost:8787. Mount your comic library at /comics and point a library at it under Settings → Library; if a download client (SABnzbd, NZBGet, qBittorrent) runs in another container, mount its completed-downloads folder too so BackIssue can import finished downloads.

Unraid ​

BackIssue is in Community Applications, so there's nothing to write by hand: open the Apps tab, search for BackIssue, and click Install. The template arrives with ports, paths and permissions already mapped — point the comics volume at your share, and the appdata volume takes care of itself.

Without Community Applications, add https://backissue.app/unraid/backissue.xml as a template URL on the Docker tab (or copy it into /boot/config/plugins/dockerMan/templates-user/), then create the container from the BackIssue template.

An optional companion: FlareSolverr ​

Several download sites sit behind Cloudflare, and the sources that use them share one setting — FlareSolverr URL in Settings → Downloading. It is a small service you run yourself, so if you plan to use those sources, add it to the same Compose file as a second service beside backissue:

  flaresolverr:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    container_name: flaresolverr
    ports:
      - "8191:8191"
    restart: unless-stopped

Then set the FlareSolverr URL to http://flaresolverr:8191/v1 (the two containers need to share a network — Compose does that for you). Leave it blank if none of your sources are behind Cloudflare; see Download sources.

Updating ​

Pull the newer image and recreate the container:

docker compose pull
docker compose up -d

With plain docker run, pull, remove and start again with the same options — docker pull ghcr.io/backissueapp/backissue:latest, then docker stop backissue && docker rm backissue, then your original docker run line. Your /data volume carries the database, settings and installed plugins across, so nothing is lost.

Install from source ​

npm install
npm run up      # builds the web UI, then starts the server

Then open http://localhost:8787.

Other useful commands:

First-run setup ​

The first time you open BackIssue it asks you to create the admin account (a fresh install never runs unsecured), then a short wizard walks you through the essentials:

1. Metadata — nothing to do: series and issue data comes from the built-in BackIssue metadata service. (Prefer querying ComicVine directly? Paste your own API key here — switchable anytime in Settings → Metadata.)
2. Libraries — create one or more named libraries, each with a type — Comics and Manga are built in, and Books and Audiobooks arrive with their plugins — and its own folder on disk (Docker: /comics). A Comics library is set up for you; add more, or leave a folder blank to decide later, and manage them anytime in Settings.
3. A download source — enable at least one of Usenet or torrents so BackIssue can actually fetch comics. You can skip this and set it up later — see Download sources.
4. Plugins — pick optional plugins (the in-browser reader, Discover, OPDS, Requests, extra sources…); they download and activate when you finish. More can be added anytime from the Plugins page.

Everything the wizard sets can be changed later in Settings.

A quick tour ​

The app is laid out with a sidebar of sections on the left and the content on the right:

• Library — a poster wall (or dense list — toggle ⊞/≣) of every series you track, with owned/total counts and badges for missing, untagged, or corrupt files. A row of filter chips, a sort dropdown, and search sit at the top — see the Library view for what each chip does. Click a series to open its issue list.
• Series page — the full ComicVine issue list for a series: what you own, what's missing, per-issue read/download buttons, and series-level actions (download missing, search sources, search packs, tag files, add to a reading list, and more).
• Sidebar sections — Library, Collections (multi-volume book and audiobook series), Wanted, Queue (live download progress), Releases (this week's issues for series you follow), Lists (reading lists), History, Stats, plus plugin entries like Discover, Requests, and reading tools. Admins also get a System area: Users, Plugins, a unified System page (Jobs, Tools and Logs on tabs), and Settings.
• Header — global search, a notification bell, and a ? help button that explains whatever page you're on.

Every filter and view is reflected in the URL, so you can bookmark or share any view. Buttons you don't have permission for simply don't appear.

Adding your first comics ​

Click + Add on the Library page, search ComicVine, and pick the volume. By default, adding a volume immediately queues its issues to download — so a fresh series starts filling itself in. You can turn that off (Settings → Downloading → "Download on add") if you'd rather add empty and download by hand.

Prefer to browse rather than search? The Discover section surfaces new and notable comics to add with one click — see Discover.

Core concepts ​

Install as an app (iPad, phone, desktop) ​

BackIssue is installable: open it in the browser and use Add to Home Screen (iOS/iPadOS Safari: Share → Add to Home Screen; desktop Chrome/Edge: the install icon in the address bar). It launches full-screen with its own icon, like a native app.

Accounts and access ​

The first account (created on first run) is the admin. To give household members their own logins, roles, permissions, and reading history, add accounts under Users — see Users & access.

Where your data lives ​

Everything lives in one data directory — /data in Docker (keep that volume persistent!), or next to the app when running from source:

• catalog.db — the database: series, issues, the file index, history, and accounts, roles, reading history, reading lists, and requests. Back it up from System → Tools → Back up database (it keeps the newest 5 snapshots).
• settings.json — your settings, written whenever you save Settings.
• plugins/ — plugins installed from the in-app catalog (Docker: under /data so they survive image updates).

Comics themselves live in your library folders, organized by your naming patterns — by default one Publisher/Series (Year) folder per series.