173 lines
6.3 KiB
Markdown
173 lines
6.3 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. **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.
|