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.** The app currently assumes the author's corner
> of space: production in **Fountain**, hauling based at **C-N4OD**, and a
> specific set of jump-drive skills and courier rates. If you live elsewhere the
> pages will render and the numbers will be **wrong rather than blank** — the
> cost model has no way to tell you it is quoting freight from a system you have
> never docked in. Making those configurable is the next milestone. Until then,
> treat this as usable only if you are in Fountain.

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

A fresh install has an empty reference database, so blueprint search and every
planner return nothing until this runs once. It downloads CCP's Static Data
Export and takes a few minutes:

```
docker compose exec app python -m app.sde.sync
```

Re-run it after a game patch — nothing does it on a schedule.

### 7. Log in

Open the address from your callback URL (without `/callback`) and add your
characters. Then use the **Data** page to pull assets, blueprints, jobs and
prices; nothing is fetched in the background, so that button is what makes the
rest of the app show anything.

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