dist/README.md

eve-assistant

A self-hosted planning tool for EVE Online industry: reactions, planetary interaction, T2/T3 manufacturing, hauling and Loyalty Point trading. It reads your characters' assets, blueprints and industry jobs through EVE's official API and does the arithmetic locally.

Single user, several characters. It is not a service and there is no hosted version — you run it on your own machine and your data stays there.

Read this before you deploy. This is a tool one person built for their own corner of space and then made configurable. It should now work anywhere, but every figure it quotes rests on settings you have to supply — your reprocessing yield, your jump skills, your hulls, your courier's rate. The defaults are somebody else's. Work through Configuration before trusting a number.

What you need

• A host running Docker with the Compose plugin.
• An EVE account with the characters you want to track.
• While access is invite-only: an account on forge.narog.fr with read access to the image.

Setup

1. Get the files

git clone https://forge.narog.fr/eve-assistant/dist.git eve-assistant
cd eve-assistant

This repo holds only the compose file and this README — the application itself comes down as a container image.

2. Register an EVE application

At https://developers.eveonline.com/applications, create an application with Authentication & API Access, and add these six scopes:

esi-assets.read_assets.v1
esi-characters.read_blueprints.v1
esi-industry.read_character_jobs.v1
esi-markets.structure_markets.v1
esi-planets.manage_planets.v1
esi-universe.read_structures.v1

Set the Callback URL to the address you will open the app at, ending in /callback — for example http://192.168.1.20:8000/callback. It has to match what you put in .env exactly.

A scope you do not register makes login fail with invalid_scope, and the error is only visible in a browser. If you add characters and then find a feature says its data is missing, the usual cause is a scope granted after that character consented — re-authorise it from the Characters page.

3. Configure

cp .env.example .env
$EDITOR .env

Fill in the client id, the secret, the callback URL, and your own contact email.

4. Create the data directory

The container runs as uid 1000 against a bind mount, so the directory has to be writable by that uid on the host:

mkdir -p data && chown 1000:1000 data

Prefix the chown with sudo unless your own account happens to be uid 1000.

Skipping this is the most common first failure: the container starts and then cannot write its database.

5. Start it

docker login forge.narog.fr     # only while access is invite-only
docker compose up -d

6. Log in — and claim the instance

Open the address from your callback URL (without /callback) and click Log in with EVE Online. Everything below is behind this: the Data and Configuration pages both redirect to the login until you have done it.

The first character to log in claims the instance. After that an unknown character is refused unless you are already logged in and adding it yourself. So log in once before the port is reachable by anyone else.

7. Load the game data

Data → Download game data. This pulls CCP's Static Data Export — blueprints, recipes, systems, market groups. It is a few hundred megabytes and takes a few minutes.

Nothing works before this: the database schema exists but is empty, so every planner renders blank. Re-run it after a game patch; nothing does it on a schedule.

8. Configure, in this order

Go to Configuration. The order matters — later steps depend on earlier ones.

1. Production system. Search for the system you build in. This is the one setting that decides your production region, which is where the app prices what you make and which market Procurement compares against. Nothing that involves selling works until it is set.
2. Contact address, under General. Sent to ESI and mokaam.dk in the User-Agent to identify you as the operator. Data refuses to fetch anything until this is set — it is not optional.
3. Staging systems, if you stage separately from where you build.
4. The panels that apply to you — Routing (your haulers, hulls, jump skills and courier rate), Industry (taxes, fees, assumed ME), Reactions, Planetary industry, Procurement, LP. Every field explains what it means and what it affects. The defaults are the author's, not yours.
5. Structures, on each planner's own config page — /industry/config, /reactions/config, /pi/config. These are lists rather than settings, so they live with the view that uses them.

9. Add your other characters and pull your data

Characters → Add a character for each alt, then Data → Refresh to pull assets, blueprints, industry jobs and prices. Nothing is fetched in the background, so that button is what makes the rest of the app show anything.

Your settings are a file you can keep

Every save also writes data/config.toml, a plain text file with a comment above each value explaining what it does. It holds no credentials and is safe to commit.

Two things that buys you:

• Back it up. Copy it somewhere you control and a rebuilt install is one file away from being configured again.
• Edit it by hand. Change a value, restart the container, and it applies.

The database is what the app reads at runtime; the file is rewritten from it on every save and read back at startup.

Upgrading

git pull
docker compose up -d

git pull brings the new image tag and the release notes together. Schema changes are applied automatically at startup.

Back up data/app.db first when the release notes say a migration is destructive. Most upgrades can be rolled back by checking out the previous tag; those cannot, and app.db holds your tokens, structures, routes and settings — everything the app cannot re-download.

Notes

• Do not expose this to the internet. There is no access control beyond EVE SSO login, and no allowlist of who may log in: anyone who reaches the port and completes a login lands in the same instance as you. Keep it on your LAN or behind a VPN.
• The app calls ESI only when you press a refresh button, and renders pages from its local database. There is no scheduler.