Skip to content

Background processing

Everything EVE Console does on a timer — ESI polling, market pricing, contracts, zKillboard, map statistics, alarms, the Scheduler, data retention and backups — is the background work. From 0.9.13 that work can run without a desktop window, so it keeps going after you close the app, or on a machine that never opens one.

This needs PostgreSQL

Detached background work is only possible when the app is on PostgreSQL. A SQLite file can be held by only one process, so a worker and a desktop client can't share it — the whole point of this mode is several clients on one server, one of which does the work.

One worker, many readers

When several clients share a PostgreSQL database, exactly one of them takes a lease and does the background work; the others read, and show what it's doing. The lease is what stops two machines duplicating the same polling.

  • A desktop client takes the lease if no one else holds it, and does the work in the background as usual.
  • A headless worker waits if a desktop client already holds the lease, and takes over the moment that client exits.
  • The title bar shows which client is doing the background work, so you can always tell.
  • The worker pushes its call logs, polling status and alarms out to the other clients, and each client can mute those independently.
  • Game and chat logs are the exception: every client reads its own log folders, so each machine's EVE logs are imported by the client running on it. See Logs & Map Data.

When a worker stops, it releases its lease on the way out, so the next client picks the work up on its next tick rather than waiting for the server to notice a dropped connection.

Watching the background work

To see what the background work is actually doing — recent ESI calls, what's due next, and how a long sweep is progressing — use the Background Processes tool, or click any of the per-process labels in the status bar. It reflects whichever client is doing the work.

Background work also slows itself when ESI's error allowance runs low, so it leaves room in the allowance your connection shares with other programs. While it does, ▲ ESI slowed shows in the title bar; see ESI limits.

Running headless

The worker runs with no UI when started with --headless. It's the same worker in every case — --headless and the Windows service alike — so the mode never means two different things. It needs no display or desktop session at all, so it runs on a server with no desktop or in a container.

Linux — systemd

Run it as a systemd user unit from the tarball or AppImage. The full walkthrough — the unit file, the environment file for the connection string, the vlc dependency and the AppImage's extract-and-run caveat — is in Running on Linux.

Docker

To self-host the worker in a container, use the Docker image and compose file in the source tree (packaging/docker). The compose file runs the worker beside its PostgreSQL server, and takes the connection string from the environment. Your desktop clients then connect to that server and leave the background work to the worker. See Running on Linux ▸ Running in Docker.

Windows — a service

On Windows the worker installs as a Windows service, managed from Settings ▸ Polling:

  • Install service / Remove service — installs or removes the background service. This needs elevation; Windows prompts for it.
  • Repoint — updates the service to the current build's location after an upgrade.

A service runs as LocalSystem and has no user session, so it reads its database from a machine-scoped configuration rather than your per-user profile — the app handles this when you install it from Settings.

A tray icon for the service

A Windows service can't draw anything on screen. If you want a visible sign that the worker is running in your own session, start the app with --tray for a notification-area icon and nothing else. There's a checkbox for it under Settings ▸ Polling.

A separate profile

--profile <name> runs a completely separate copy of the app — its own config, database and caches — under %LOCALAPPDATA%\EVE Console Data\Profiles\<name> on Windows or ~/.local/share/EveConsole/Profiles/<name> on Linux (or a folder path you give instead of a name). It can be combined with the other switches and runs alongside your normal copy; see the FAQ.

Supplying the connection string to a service

A background service has no login session, so it can't read the connection password saved through the desktop app (that lives in a per-user secure store). For headless/service use, supply the connection string through the environment instead:

EVECONSOLE_DB_CONNECTION=Host=…;Database=…;Username=…;Password=…

On Linux this goes in the unit's environment file; on Windows it's a machine or service environment variable; in Docker the compose file sets it. See Running on Linux for the Linux specifics.

A worker in a container has no settings window either, so it can be told where EVE's game and chat logs are the same way. Each takes one or more folders, separated by ;:

EVECONSOLE_GAMELOG_DIRS=/eve/Gamelogs
EVECONSOLE_CHATLOG_DIRS=/eve/Chatlogs

When set, they replace the folders saved in this machine's settings rather than adding to them. Without them the worker uses the saved folders; a fresh container has none, so it reads no logs, and each desktop client goes on reading its own. See Logs & Map Data.

Version safety

A worker checks its build against the database schema and exits deliberately if they don't match — the schema belongs to a different build, and running the wrong one against it could corrupt data. When the database is ahead of the worker, the log line also says whether a release that can open it is out. On Linux the shipped unit restarts on-failure but not on this exit, so a clear one-line failure doesn't turn into a restart loop. Keep the worker and your desktop clients on the same version.

A worker that is newer than the database upgrades it without asking, since a service is updated unattended and has nobody to ask, and writes that it did so to its log. A desktop client asks first; see Upgrading the database. So update the worker only when your desktop clients are ready to follow.

A desktop client, or one started with --tray, that finds the database ahead of it doesn't just stop: it offers to update itself there and then. See When this copy is older than the database.

The other way round — this client is newer, but another client still holds the background work on the older version — stops with This build does not match the database. Only the client doing the background work may upgrade the schema, so update that client, or close it and start the newer one first so it takes the work over.