Release 0.2.0

.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://<docker-host-lan-ip>: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=

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

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:-}