Skip to main content

Running headless

njMule does not need a window. Its engine runs headless on a server, a NAS, a Raspberry Pi or a computer nobody sits at, and you drive it from a browser through its web interface, from the command line through its remote-control API, or from the desktop app of another computer. The headless engine is the same program as the desktop app's, with the same settings, files and network behaviour.

Start it​

Every package has the njmule command, which runs the engine headless until you stop it:

njmule

The installer puts njmule.exe on your PATH; from the zip archive, run it from its folder. It is a console program: closing its window stops njMule (it saves first). To run njMule without anyone signed in, make it a Windows service.

The desktop app's window, njmule-gui, starts this same program for itself; on its own, njmule needs no window and no desktop. At start njMule prints its notice, then where its configuration and logs are and, when the web interface is on, its port; then it logs what happens until it stops.

Before the first headless start, give the web interface a password, or you will have no way to look at what njMule does:

njmule --webui-password --webui-lan    # asks for the password twice, then exits
njmule                                  # runs, with the web interface on port 4711

See Web interface for the options, and Web interface security before you turn on --webui-lan.

Where it keeps its data​

The headless engine uses the same folders as the desktop app on the same account: what one downloads, the other sees. The defaults follow each system's conventions (Linux: ~/.config/njmule, ~/.local/share/njmule, ~/.local/state/njmule/logs, completed downloads in ~/Downloads/njMule); Where njMule keeps its files lists them all.

  • --config-dir <dir> keeps everything below one folder instead (config, data, temp, cache, logs, gui and incoming), to run a separate profile or to keep a server's data in one place:

    njmule --config-dir /srv/njmule

  • A portable.flag file beside the programs of an archive does the same with a data folder next to them (Portable mode).

Only one njMule runs on one configuration at a time. A second headless start on the same configuration hands its links to the running one, or fails with njMule is already running with the configuration in … when it has none. A desktop app started meanwhile hands its links to it as well and says njMule already runs without a window on this profile instead of opening its window (The window does not open). Give one of them --config-dir if you want both at once, or drive the headless one instead.

Typical set-ups​

WhereHowPage
Docker, any Linux server or NASThe image ghcr.io/njmule/njmule: the headless engine and its web interface, data in a volumeDocker
Synology DSM 7The .spk package, started and stopped by the Package CenterSynology
WindowsThe service "njMule", started with Windows before anyone signs inWindows service
Linux desktop or serverThe systemd user unit of the deb and rpm packagesLinux service
Anywhere, by handnjmule in a terminal, tmux or screenthis page

Drive it​

  • From a browser: the web interface has every place of the desktop app.
  • From the command line: with the API turned on, njmule --remote status, njmule --remote add "ed2k://|file|…|/" and the other remote commands.
  • From another computer's desktop app: ⋯ → Connect to a remote njMule shows the headless njMule in a window of its own (Remote njMule).
  • With links: njmule "ed2k://|file|…|/" hands the links to the njMule running on the same configuration, which downloads them.

Stop it​

njMule saves its downloads, lists and settings before it exits, which takes a few seconds. Any of these stops it cleanly:

  • Ctrl+C in its terminal, or the SIGTERM signal of kill, docker stop or systemd;
  • njmule --exit from another terminal on the same computer and configuration (add --config-dir if it runs with one). It waits until njMule has saved and stopped, 30 seconds at most, and fails when no njMule runs there or when it still runs after that time;
  • njmule --remote shutdown, here or with --remote-url from another computer;
  • the stop of its supervisor: the Package Center, njmule --service=stop, systemctl --user stop njmule.

Give a supervisor the time to save: Docker's --stop-timeout 30, Compose's stop_grace_period: 30s.

Logs​

The headless engine logs to its console (standard output) and to njmule.log in the logs folder, which turns over every day and at 10 MB, and keeps 14 days and 200 MB at most. Under Docker, docker logs njmule shows the console; under systemd, journalctl --user -u njmule.

  • The level is INFO unless log.level in njmule.properties says otherwise; --log-level DEBUG overrides it for one run (ERROR, WARN, INFO, DEBUG or TRACE).
  • The web interface shows the latest lines under Network → Log, and njmule --remote log prints them.

Logs tells more about the files and what they hold.