Skip to content

Linux Launcher

The Linux launcher is a bibliogon-launcher-linux ELF binary that starts Bibliogon with a click: no docker compose commands, no terminal session kept open. Docker still runs the actual app; the launcher just starts and stops it for you.

What the launcher does for you. On first run, the launcher detects whether Bibliogon is already on disk. If it is not, the launcher offers to download and set up Bibliogon for you (see "First launch" below). The only thing you have to install yourself is Docker; Docker's licensing terms prohibit silent third-party installation. See the Installation overview for the cross-platform picture.

System requirements

  • A recent 64-bit Linux distribution (Ubuntu 22.04+, Fedora 38+, Debian 12+, Arch, or equivalent). The binary is built on ubuntu-22.04, so glibc 2.35 or newer is required. Older distributions are not supported.
  • Docker Engine or Docker Desktop, with your user in the docker group.
  • The Tk runtime (python3-tk on Debian/Ubuntu, tk on Arch, python3-tkinter on Fedora) if the bundled Tk in the PyInstaller binary complains. Most distributions already have this; reports of missing Tk have not surfaced so far.

One-time setup

1. Install Docker

See the Bibliogon Docker installation guide for the full picture plus a "Is Docker safe to install?" section. On Linux, two routes are common:

  • Docker Engine (native, recommended for servers and minimal desktops): docs.docker.com/engine/install. After install, add your user to the docker group and log out/back in:
sudo usermod -aG docker "$USER"

Verify Docker is reachable without sudo:

docker info

2. Download the launcher

From the Bibliogon releases page, download two files attached to the release:

  • bibliogon-launcher-linux
  • bibliogon-launcher-linux.sha256

Save them anywhere; ~/Downloads is fine.

The launcher is not signed. To confirm the binary you downloaded is the exact file published, open a terminal where you saved it and run:

sha256sum bibliogon-launcher-linux
cat bibliogon-launcher-linux.sha256

The hash from sha256sum should match the hex string in the .sha256 file. If it does not, do not run the binary and report it on GitHub Issues.

4. Make the launcher executable

chmod +x bibliogon-launcher-linux

Optionally move it somewhere on your PATH (for example ~/bin or ~/.local/bin) if you want to call it from any directory.

First launch

Run the launcher from a terminal:

./bibliogon-launcher-linux

Or, if your desktop environment supports launching executables from a file manager, right-click the file and choose "Run" or "Open" (GNOME Files users: enable "Executable Text Files: Ask what to do" in Preferences).

What happens on first launch

The launcher's first job is to detect what is already in place.

  1. Docker check. The launcher confirms Docker is installed and reachable without sudo. If Docker is missing, a dialog with the install URL appears and the launcher exits. If Docker is installed but not running (or the user is not yet in the docker group), a dialog asks you to start Docker and click Retry; the launcher tries up to three times.
  2. Bibliogon check. The launcher looks for an existing Bibliogon install via its manifest (~/.config/bibliogon/install.json) or, on a clean machine, checks the default location ~/bibliogon.
  3. Already installed: the launcher proceeds straight to step 3.
  4. Not installed: a welcome dialog appears: "Bibliogon is not installed on this computer yet". Three buttons: Install (the launcher downloads the latest release ZIP, extracts to a folder you pick, generates a fresh .env, and builds the Docker images - first build takes 3-5 minutes), Open install guide (opens the docs in your browser), or Close.
  5. Start. A small "Starting Bibliogon..." window appears while Docker brings up the containers.
  6. Browser. When Bibliogon is ready, your default browser opens at http://localhost:7880 (or whatever port is configured in .env).
  7. Status window. The small window switches to "Bibliogon is running on localhost:7880" with a Stop Bibliogon button.

Stopping Bibliogon

Click Stop Bibliogon in the launcher window, or just close it. The launcher runs docker compose down and exits. Docker keeps running in the background; only the Bibliogon containers stop.

Running a second time

Run the launcher again. If Bibliogon is already running (for example because you minimised the launcher window and forgot), the launcher detects the running instance and just opens the browser at the correct URL without starting a second copy.

Troubleshooting

"Docker is not running" or "permission denied" on docker.sock Check that Docker is reachable without sudo:

docker info

If that fails with a permission error, you are not in the docker group yet. After sudo usermod -aG docker "$USER" you have to log out of your session completely (not just close the terminal) and log back in. On Wayland, a full reboot is sometimes the only way to get the group change picked up.

"Bibliogon install not found" The launcher cannot find docker-compose.prod.yml at the default or configured path. Click OK, then pick the folder where you cloned or unzipped Bibliogon. That folder typically contains README.md, Makefile, and the docker-compose.prod.yml file.

"Port 7880 is in use" Another program is already using the Bibliogon port. Options: stop the other program, or edit .env in your Bibliogon folder and set BIBLIOGON_PORT to a different value (for example 7881), then start the launcher again.

"Bibliogon did not start in time" The first start of a fresh install needs to build Docker images, which can take several minutes. Click Retry to wait another 60 seconds. If it still fails, check the last log lines in the dialog and run:

docker compose -f ~/bibliogon/docker-compose.prod.yml logs --tail=100

"./bibliogon-launcher-linux: cannot execute: required file not found" The binary needs glibc 2.35 or newer. You are on an older distribution. Upgrade the distribution, or install Bibliogon via install.sh from the repository instead of the launcher.

"error while loading shared libraries: libtk..." Tk is not installed. Install the Tk package for your distribution (python3-tk on Debian/Ubuntu, tk on Arch, python3-tkinter on Fedora). An AppImage that bundles Tk is tracked as D-03a and depends on how often this issue surfaces.

Activity log Every launch writes to ~/.config/bibliogon/install.log (1 MB rotation, 1 backup). Attach this file to bug reports. See the Activity log section for details.

Activity log

Every launcher action (install, uninstall, Docker operations, errors) is written to:

~/.config/bibliogon/install.log

The log rotates at 1 MB with one backup (install.log.1). When reporting an issue on GitHub, attach the current log file or paste the last 50-100 lines; it usually shows exactly what failed.

Uninstalling

See Uninstall for the launcher UI path and the uninstall.sh script fallback.

Short version: click Uninstall inside the launcher window and confirm. The launcher removes the installation directory and its own manifest. Docker volumes (your book data) are preserved by default; add them explicitly if you want a complete wipe.