dist/README.md
2026-10-02 14:23:47 +02:00

175 lines
6.5 KiB
Markdown

# 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. **Market region.** Search for the region you sell in. This is where the app
prices what you make and which market Procurement and Orders compare
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. **Hub systems**: every system you build, react or stage in. The app stores
all of your assets wherever they are, but the planners count only stock
sitting in a hub. Anything else shows on Stock as "outside hubs".
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 — see
[CHANGELOG.md](CHANGELOG.md) for what each version added and whether it needs
anything from you. 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.