diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..d758233 --- /dev/null +++ b/.env.example @@ -0,0 +1,28 @@ +# Copy to `.env` in this directory and fill in. `.env` is read by docker +# compose automatically -- do not commit it, and do not share the secret. + +# -------------------------------------------------------------------------- +# EVE SSO -- from YOUR OWN application at +# https://developers.eveonline.com/applications +# +# Every instance needs its own registered application. The redirect URI below +# is registered per-application, and this is a confidential client (the token +# exchange sends the secret), so these cannot be shared between people. +# -------------------------------------------------------------------------- +EVE_SSO_CLIENT_ID= +EVE_SSO_CLIENT_SECRET= + +# Must match a "Callback URL" on that application EXACTLY, including the port +# and the /callback path. Use the address you will actually open the app at -- +# the LAN IP of the docker host, not localhost, unless you browse from the host +# itself. A mismatch fails at login with an SSO error, not at startup. +EVE_SSO_REDIRECT_URI=http://:8000/callback + +# -------------------------------------------------------------------------- +# Who is running this instance +# -------------------------------------------------------------------------- +# Sent as the contact address in the User-Agent on every call this app makes to +# ESI and to mokaam.dk. Both operators expect a real address, and CCP's +# published guidance is that it identifies whoever is running the software. +# Leave it unset and someone else answers for your traffic. +EVE_ASSISTANT_CONTACT_EMAIL= diff --git a/README.md b/README.md index adce793..19af392 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,130 @@ -# dist +# eve-assistant -Deploy eve-assistant: compose file, .env template and setup guide. Generated from the private source repo at each release -- do not hand-edit. \ No newline at end of file +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 , 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. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..9cdc78d --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,36 @@ +# eve-assistant -- deployment compose file. +# +# This file is GENERATED: it is copied here from the private source repo by +# scripts/release.sh at each release. Don't hand-edit it -- your changes are +# discarded by the next `git pull`. Put your own settings in `.env`. + +services: + app: + # Rewritten by scripts/release.sh at release time. Pinned, never `latest`: + # a release can carry a one-way database migration, so upgrading is + # something you do deliberately (`git pull`), not something a restart does + # to you. + image: forge.narog.fr/eve-assistant/app:0.2.0 + restart: unless-stopped + ports: + - "8000:8000" + volumes: + # Holds sde.db (game reference data) and app.db (your tokens, settings, + # and the latest snapshot of your assets). Both are latest-snapshot-only + # with no history, and app.db is the one you cannot re-download -- back it + # up before an upgrade whose release notes mention a migration. + # + # The container runs as uid 1000, so this directory must be writable by + # that uid on the host: `mkdir -p data && chown 1000:1000 data`. + - ./data:/app/data + environment: + # From .env -- see .env.example. The client id and secret come from YOUR + # OWN application registered at developers.eveonline.com; they are not + # shipped and cannot be shared between instances. + - EVE_SSO_CLIENT_ID=${EVE_SSO_CLIENT_ID} + - EVE_SSO_CLIENT_SECRET=${EVE_SSO_CLIENT_SECRET} + - EVE_SSO_REDIRECT_URI=${EVE_SSO_REDIRECT_URI} + # Identifies YOU to ESI and to mokaam.dk as the operator of this instance. + # Set it: unset, your API traffic is attributed to the author and he is + # the one CCP contacts if this instance misbehaves. + - EVE_ASSISTANT_CONTACT_EMAIL=${EVE_ASSISTANT_CONTACT_EMAIL:-}