chore(docs): add a basic README.md for running locally

LICENSE.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright (c) 2023 updraft0 and contributors
+Copyright (c) 2023-2024 updraft0 and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -0,0 +1,80 @@
+# `control-tower`
+
+> _an elevated glass-enclosed structure which has an unobstructed view of a landing field and from which air traffic 
+> may be controlled usually by radio_
+
+> **A new wormhole mapping tool for EVE Online**
+
+### ⚠ Alpha quality software ⚠
+
+Control Tower is a new mapping tool for [EVE][eve-online] that is focused on mapping J-space and being familiar to 
+existing users of [Pathfinder][pathfinder]. The motivation to write a new tool was **a.** _for fun_ and **b.** because 
+the Pathfinder codebase was hard to understand/modify. Complete feature parity is not the primary goal - but runtime 
+speed and ease of deployment certainly are.
+
+Current state:
+
+![Image of map view pre 0.1](./screenshots/map_pre_0.1_demo.png)
+
+## Running
+
+The github actions pipeline builds docker images for both the backend and frontend, currently only tagged `:latest`.
+
+To run using [docker-compose]:
+
+* Create a new [EVE Application][eve-online-developer-applications] and note the ESI client id and secret
+* Create the `secret.env` file by e.g. running [`./scripts/generate-secret-env.sh > secret.env`](./scripts/generate-secret-env.sh)
+* Update the `secret.env` with the values of your ESI client id and secret
+* Run `docker-compose up` (look in [`compose.yaml`](./compose.yaml) for things you might want to tweak)
+* Wait for the SDE import to run and go to http://localhost:8080 to login + create a map
+
+Current minimum runtime requirements are 4GB RAM and 1 CPU, because the full [SDE][eve-online-sde] is imported and 
+parsing hundreds of megabytes of YAML is memory consuming.
+
+## Features
+
+The feature list is intended as an overview of capabilities and current roadmap - for more details see the project view.
+
+Currently:
+
+* Multiple characters can log in and share a session
+* Each map has granular ACL permissions
+* Map canvas supports moving systems, adding new ones, creating connections
+* Jumps between systems are tracked (even if a character is not actively looking at the map)
+* Selecting a system gives signature scan information
+* Selecting a connection gives connection jump information
+* There are keyboard shortcuts available to e.g. rename or delete systems
+
+In the future:
+
+* [ ] Right-click context menu for common actions (such as setting the size of a connection)
+* [ ] Intel information is editable (e.g. system owner) and notes
+* [ ] Route calculation
+* [ ] Notifications for when systems become connected
+
+## Developing
+
+The project is almost exclusively written in the [Scala][scala-lang] 3 programming language with a functional style on 
+the backend - a tutorial is sadly beyond the scope of this README. To get started with being able to run locally (e.g. 
+to hack on the frontend CSS) on a Unix like system (tested on Linux only but should work in WSL 2 or on a Mac):
+
+* Install [mise] (or [asdf]) and run either `mise install` or `asdf install` - this should bring in the JDK, `sbt` and `npm`
+* Run `sbt` to bring up the build tool prompt and type `~ui/fastLinkJS` to hot-recompile the frontend `ui/` code
+* In a separate terminal tab, run `cd ui && npm run dev` to bring up [vite]
+* In a separate terminal tab, run `sbt server/run` (after having brought in all the appropriate environment variables)
+* Open up http://localhost:8091/ - you should be able to see the login screen and your maps
+
+## Contributing
+
+If you want to get in touch, report a bug or submit some code changes please either open an issue or start a discussion.
+A fuller `DEVELOPING.md` guide will probably be available eventually.
+
+[asdf]: https://github.com/asdf-vm/asdf
+[docker-compose]: https://docs.docker.com/compose/
+[eve-online]: https://www.eveonline.com/
+[eve-online-developer-applications]: https://developers.eveonline.com/applications
+[eve-online-sde]: https://docs.esi.evetech.net/docs/sde_introduction.html
+[mise]: https://github.com/jdx/mise
+[pathfinder]: https://github.com/goryn-clade/pathfinder
+[scala-lang]: https://scala-lang.org/
+[vite]: https://vitejs.dev/

compose.yaml

@@ -1,28 +1,38 @@
-version: '3'
+# see https://compose-spec.io/
+version: '3.7'
 services:
   frontend:
-    restart: always
-    image: ghcr.io/updraft0/controltower-fe
+    restart: no
+    pull_policy: always
+    image: ghcr.io/updraft0/controltower-fe:latest
     ports:
       - "8091:8080"
     volumes:
-      - ./ui/nginx.conf:/etc/nginx/nginx.conf:z,ro
+      - ./ui/nginx.conf:/etc/nginx/nginx.conf:ro
+    # - /path/to/ssl.key:/etc/ssl/your.fqdn.here.key:ro
+    # - /path/to/ssl.pem:/etc/ssl/your.fqdn.here.pem:ro
     depends_on:
       backend:
         condition: service_healthy
   backend:
-    restart: always
-    image: ghcr.io/updraft0/controltower
+    restart: no
+    pull_policy: always
+    image: ghcr.io/updraft0/controltower:latest
     env_file:
       - ./secret.env
     environment:
       - CT_HTTP_UI_PORT=8091
-#    volumes:
-#      - ./composedb:/app/db:Z
+      - JAVA_OPTS=-Xmx4G -XX:+UseZGC
+      - SDE_PARALLEL=1
+    # - CT_HTTP_PROTO=https
+    # - CT_HTTP_HOST=your.fqdn.here
+    # - CT_HTTP_UI_PORT=8443
+    volumes:
+     - ./ctdb:/app/db
     ports:
       - "8092:8092"
     healthcheck:
       test: ["CMD", "curl", "http://localhost:8092/api/reference/version"]
       interval: 10s
       timeout: 5s
-      retries: 3
+      retries: 3

scripts/generate-secret-env.sh

@@ -0,0 +1,7 @@
+#!/bin/sh -eu
+# Generates the secret.env file contents. See application.conf for how the environment variables are used
+echo "CT_AUTH_SECRET=$(head -c 32 /dev/urandom | python -m base64)}"
+echo "CT_ESI_CALLBACK_SECRET=$(head -c 32 /dev/urandom | python -m base64)"
+echo "CT_ENCRYPTION_SECRET=$(head -c 32 /dev/urandom | python -m base64)"
+echo "CT_ESI_CLIENT_ID=<insert here>"
+echo "CT_ESI_CLIENT_SECRET=<insert here>"

ui/nginx.conf

@@ -21,6 +21,10 @@ http {
   server {
     gzip on;
     listen 8080 default_server;
+    # listen 8080 ssl;
+
+    # ssl_certificate /etc/ssl/your.fqdn.here.pem;
+    # ssl_certificate_key /etc/ssl/your.fqdn.here.key;
 
     location /api/ {
       proxy_pass http://ct-backend;