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
```

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. Load the game data

Open the app and go to **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.

### 7. 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.

### 8. Add your characters and pull your data

**Characters → Add a character**, 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.