From f39f91af0cac25b0ffa1f6b595d002ef1bb4fbd6 Mon Sep 17 00:00:00 2001 From: Clayton Burlison Date: Thu, 16 Nov 2023 15:36:55 -0600 Subject: [PATCH 1/6] docs: Flygon to Dragonite --- docker-compose.example.yml | 58 ++++++++++++++++++++++--------- docs/pages/client/notes.mdx | 6 ++-- docs/pages/index.mdx | 2 +- docs/pages/integrations.mdx | 65 +++-------------------------------- docs/pages/setup/docker.mdx | 13 ++++--- docs/pages/setup/standard.mdx | 4 +-- 6 files changed, 59 insertions(+), 89 deletions(-) diff --git a/docker-compose.example.yml b/docker-compose.example.yml index 86565c46..0ac337dd 100644 --- a/docker-compose.example.yml +++ b/docker-compose.example.yml @@ -1,23 +1,49 @@ -version: '2' +version: "2" services: koji: image: ghcr.io/turtiesocks/koji:main container_name: koji restart: unless-stopped environment: - # Required - SCANNER_DB_URL: 'mysql://rdm_user:rdm_password@host:3306/rdm_database' - # CONTROLLER_DB_URL: 'mysql://rdm_user:rdm_password@host:3306/flygon_database' - KOJI_DB_URL: 'mysql://koji_user:koji_password@127.0.0.1:3306/koji_database' - KOJI_SECRET: 'your_super_secret' - # Optional - #START_LAT: 0 - #START_LON: 0 - #NOMINATIM_URL: "https://nominatim.openstreetmap.org" # highly recommended using your own - #MAX_CONNECTIONS: 100 - #LOG_LEVEL: info # error | warn | info | debug | trace - #mem_limit: 2048G - #mem_reservation: 256M - #cpus: 2 + # To escape special characters you must surround the values with single quotes ('') + # Commented out variables are optional + + # Your Golbat or RDM database + SCANNER_DB_URL: "mysql://rdm_user:rdm_password@host:3306/rdm_database" + + # Your Dragonite (if using) or RDM database (if you're using a hybrid Golbat/RDM setup) + # CONTROLLER_DB_URL: 'mysql://dragonite_user:dragonite_password@host:3306/dragonite_database' + + # Your Koji database + KOJI_DB_URL: "mysql://koji_user:koji_password@127.0.0.1:3306/koji_database" + + # Max Database connections + # MAX_CONNECTIONS: 100 + + # Your Koji API bearer token and client password + KOJI_SECRET: "your_super_secret" + + # Start latitude on initial client load + # START_LAT: 0 + # Start longitude on initial client load + # START_LON: 0 + # Nominatim URl used for searching and importing geofences from OSM + # NOMINATIM_URL: 'https://nominatim.openstreetmap.org' # highly recommended using your own + # Logging level | error | warn | info | debug | trace + # LOG_LEVEL: info + + # Memory limit for docker container + # mem_limit: 2048G + # Memory reservation for docker container + # mem_reservation: 256M + # CPU limit for docker container + # cpus: 2 + ports: - - '8080:8080' # change left one for external port + - "8080:8080" # change left one for external port + + + # If you want to use a non docker database enable following lines and + # change the Database URL to 'host.docker.internal' + #extra_hosts: + # - "host.docker.internal:host-gateway" diff --git a/docs/pages/client/notes.mdx b/docs/pages/client/notes.mdx index 8744a9ee..cdd15acc 100644 --- a/docs/pages/client/notes.mdx +++ b/docs/pages/client/notes.mdx @@ -33,8 +33,8 @@ While Kōji does connect directly to your scanner's database, most scanners have 1. In the Admin Panel, navigate to the `projects` page. 1. Edit (or create) a scanner project 1. Set `scanner` to true -1. Add the `api_endpoint` value, a hint is provided for both RDM and Flygon scanner endpoints -1. Add the `api_key` value, a hint is provided for both RDM and Flygon scanner endpoints +1. Add the `api_endpoint` value, a hint is provided for both RDM and Dragonite scanner endpoints +1. Add the `api_key` value, a hint is provided for both RDM and Dragonite scanner endpoints Now when you click the `Sync` button, either next to the respect project, geofence, or route, Kōji will automatically call this endpoint after saving the changes to the scanner database, making them immediately available to the scanner to use! @@ -42,7 +42,7 @@ Now when you click the `Sync` button, either next to the respect project, geofen Since most scanners have many other properties associated with their geofences and routes, Kōji provides a way to automatically add these properties to your geofences and routes when they are created. -- If using Flygon, in the Flygon Admin panel create a new `area` named `Default` and set any properties that you want, such as worker counts, to be added to all geofences and routes that are saved from Kōji. +- If using Dragonite, in the Dragonite Admin panel create a new `area` named `Default` and set any properties that you want, such as worker counts, to be added to all geofences and routes that are saved from Kōji. - If using RDM, you will need to name the files a little differently. For each available instance mode, you will need to take note of its acronym, below is the code that Kōji uses for your reference: | Mode | Acronym | diff --git a/docs/pages/index.mdx b/docs/pages/index.mdx index fdde3fb6..b5c74a78 100644 --- a/docs/pages/index.mdx +++ b/docs/pages/index.mdx @@ -29,7 +29,7 @@ Welcome to Kōji! ## Supported Backends - [Golbat](https://github.com/UnownHash/Golbat) (data) -- [Flygon](https://github.com/UnownHash/Flygon) (instances) +- [Dragonite](https://github.com/UnownHash/Dragonite-Public) (instances) - [RDM](https://github.com/RealDeviceMap/RealDeviceMap) (data + instances) ## Supported Browsers diff --git a/docs/pages/integrations.mdx b/docs/pages/integrations.mdx index 203d0bca..73ee7d90 100644 --- a/docs/pages/integrations.mdx +++ b/docs/pages/integrations.mdx @@ -93,71 +93,16 @@ import { GitHubLogo } from '../components/GitHub' - MultiPolygons ½ (Works, but is downconverted to a Polygon, may produce unexpected results) - Auto quest, Pokemon, and fort route calculations, both in the admin panel and used server side - - -## Flygon - -- Syncs all geofences from Kōji to Flygon in the given project at startup -- You must set two config values to use Kōji with Flygon - -1. First set your Kōji Bearer Token: - - - `koji.bearer_token` - - Your Kōji Bearer token - -1. Then set the Kōji url - - - `koji.url` - - Example: `http://{koji_ip}` - -1. Then set the Kōji project name that you want Flygon to use when calling the API - - - `koji.project_name` - - Example: `project_name` - -1. Lastly, since Flygon loads all of the areas at startup and overwrites them in the database at startup, there's a config option to enable or disable this behavior. - - - `koji.load_at_startup` - - `true` or `false` - -### Supported Features - -- Polygons ✅ -- MultiPolygons ½ (Works, but is downconverted to a Polygon, may produce unexpected results) - - - -## Flygon Admin - -- Enable buttons in the dashboard panel to make calls to Kōji to calculate clustered and bootstrapped routes. -- You must set two config values to use Kōji with Flygon Admin - -1. First set your Kōji Bearer Token: - - - `koji.bearer_token` - - Your Kōji Bearer token - -1. Then set the Kōji api_endpoint - - - `koji.api_endpoint` - - Example: `http://{koji_ip}` - -### Supported Features - -- Bootstrap 70m Circles -- Bootstrap 9x9 S2 Cells -- Pokemon 70m clustered routes -- Quest 78m clustered routes -- Gym 9x9 clustered routes - ## RealDeviceMap -- [PR 513](https://github.com/RealDeviceMap/RealDeviceMap/pull/513) +- RealDeviceMap (RDM) is marked as depreciated and support will be removed in the future. + +* [PR 513](https://github.com/RealDeviceMap/RealDeviceMap/pull/513) Date: Thu, 16 Nov 2023 20:31:34 -0600 Subject: [PATCH 2/6] fix: Add docker network by default This should be a straight win for _most_ users --- docker-compose.example.yml | 3 +++ docs/pages/setup/docker.mdx | 3 +++ 2 files changed, 6 insertions(+) diff --git a/docker-compose.example.yml b/docker-compose.example.yml index 0ac337dd..f6c0f6fa 100644 --- a/docker-compose.example.yml +++ b/docker-compose.example.yml @@ -42,6 +42,9 @@ services: ports: - "8080:8080" # change left one for external port + networks: + default: + name: scanner # If you want to use a non docker database enable following lines and # change the Database URL to 'host.docker.internal' diff --git a/docs/pages/setup/docker.mdx b/docs/pages/setup/docker.mdx index 33c5313d..83d6b7aa 100644 --- a/docs/pages/setup/docker.mdx +++ b/docs/pages/setup/docker.mdx @@ -53,6 +53,9 @@ services: ports: - '8080:8080' # change left one for external port + networks: + default: + name: scanner # If you want to use a non docker database enable following lines and # change the Database URL to 'host.docker.internal' From d3b908dab75bdb7437f24f73b89ab84add1395f3 Mon Sep 17 00:00:00 2001 From: Clayton Burlison Date: Thu, 16 Nov 2023 20:32:10 -0600 Subject: [PATCH 3/6] docs: Integration notes for Project API calls 90% sure this is accurate from our DMs and my notes --- docs/pages/client/getting-started.mdx | 5 ++++ docs/pages/integrations.mdx | 41 ++++++++++++++++++++++++++- 2 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/pages/client/getting-started.mdx b/docs/pages/client/getting-started.mdx index bfe81377..8e987ade 100644 --- a/docs/pages/client/getting-started.mdx +++ b/docs/pages/client/getting-started.mdx @@ -29,6 +29,11 @@ A "project" in Kōji is how you create custom endpoints for distributing your ge 1. Once you've completed those steps, your geofences assigned to this project will now be accessible at `http://{your_koji_url}/api/v1/geofence/feature-collection/ReactMap` 1. Projects don't have to be striclty used with external integrations though. Kōji's client can also import geofences by project so it may be convenient to group them for this reason as well. + + Please see [Integrations](/integrations) configuration assistance with a + specific project. + + ## Import existing Projects 1. After logging in, click the `Map` button on the landing page diff --git a/docs/pages/integrations.mdx b/docs/pages/integrations.mdx index 73ee7d90..9a7459b6 100644 --- a/docs/pages/integrations.mdx +++ b/docs/pages/integrations.mdx @@ -3,6 +3,8 @@ import { GitHubLogo } from '../components/GitHub' # External Integrations +In Kōji's architecture, various external integrations primarily leverage HTTP `GET` requests for data retrieval. These integrations can be configured to fetch the latest updates either during the initialization phase of a process or based on a predefined schedule. Additionally, Kōji supports an event-driven approach where it can proactively trigger updates in external services. This mechanism enables synchronization with Kōji's latest state changes, enhancing the responsiveness and efficiency of the integrated systems. + ## ReactMap - Remove the need to have an `areas.json` file by loading your managed geofences straight from Kōji @@ -44,6 +46,15 @@ import { GitHubLogo } from '../components/GitHub' - `config.geofence.path` - Example: `http://{koji_ip}/api/v1/geofence/poracle/{project_name}` +### Project setup + +This is configured inside your Kōji `/admin/project` and will allow hot reloading of your areas within PoracleJS. + +```yml +API Endpoint: http://{poraclejs_ip}:{port}/api/geofence/reload +API Key: X-Poracle-Secret:{config.server.apiSecret} +``` + ### Supported Features - Polygons ✅ @@ -87,10 +98,19 @@ import { GitHubLogo } from '../components/GitHub' - `koji.url` - Example: `http://{koji_ip}` +### Project Setup + +Use these values if Koji and Dragonite are on the **same** network. + +```yml +API endpoint: http://{drago_host_ip}:{drago_port}/reload +API key: Leave empty. Dragonite currently does not support authentication +``` + ### Supported Features - Polygons ✅ -- MultiPolygons ½ (Works, but is downconverted to a Polygon, may produce unexpected results) +- MultiPolygons ½ (Works, but is down converted to a Polygon, may produce unexpected results) - Auto quest, Pokemon, and fort route calculations, both in the admin panel and used server side +## Dragonite Admin + +- Outbound requests from Dragonite Admin are proxied through Dragonite +- Inbound requests from Kōji can be received by Dragonite Admin to update routes and geofences + +### Project Setup + +Use these values if Koji and Dragonite are on **different** networks. This will proxy the request through Dragonite Admin to Dragonite utilizing the api_secret value. + +```yml +API endpoint: http://{drago_admin_host_ip}:{drago_admin_port}/api/reload +API key: X-Dragonite-Admin-Secret:{your_api_secret_value} +``` + + + ## RealDeviceMap - RealDeviceMap (RDM) is marked as depreciated and support will be removed in the future. From 76bcec5bded19389d960dc15ff879af878e9d8f4 Mon Sep 17 00:00:00 2001 From: Clayton Burlison Date: Thu, 16 Nov 2023 21:02:44 -0600 Subject: [PATCH 4/6] docs: Drago quick start guide --- docs/pages/client/getting-started.mdx | 40 +++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/pages/client/getting-started.mdx b/docs/pages/client/getting-started.mdx index 8e987ade..46deeb84 100644 --- a/docs/pages/client/getting-started.mdx +++ b/docs/pages/client/getting-started.mdx @@ -30,8 +30,8 @@ A "project" in Kōji is how you create custom endpoints for distributing your ge 1. Projects don't have to be striclty used with external integrations though. Kōji's client can also import geofences by project so it may be convenient to group them for this reason as well. - Please see [Integrations](/integrations) configuration assistance with a - specific project. + Please [Integrations](/integrations) for assistance with a specific + project. ## Import existing Projects @@ -100,4 +100,38 @@ A "project" in Kōji is how you create custom endpoints for distributing your ge height={600} /> -1. Repeat for however many projects/files you want to import! The import wizard can import from all sorts of differnet sources, including Nominatim and shape files. +1. Repeat for however many projects/files you want to import! The import wizard can import from all sorts of different sources, including Nominatim and shape files. + +## Dragonite Quick Start + +1. Complete the above steps to initialize Kōji +1. If you are starting from scratch and have no existing areas + 1. Visit the Kōji Map + 1. Create a fence + 1. Name it and save to Kōji database +1. Visit the Kōji Map +1. Load your fence (if it isn't present) +1. Go to the Calculation tab +1. Select Bootstrap Mode + 1. Strategy: Radius (for pokemon), S2 (for forts) + 1. Save to Kōji Db: Enabled + 1. Save to Scanner db: Enabled + 1. Skip Rendering: Enabled +1. Click update +1. Once complete navigate to the Admin portal of Kōji +1. Click "Sync" on the geofence. This will create the Area in Dragonite if it doesn't exist. +1. Click "Sync" on the route. This will push the bootstrap route into Dragonite. +1. Then I add that new fence to my Dragonite project (and to my consumer (poracle/RM/golbat) project if I don't want to split it up). + +**In dragonite admin:** + +1. Edit the area and set the desired worked count + +**Back in koji:** + +1. Wait a few hours/a day for the bootstrap to update +1. Load the fence up into Kōji again, run pokemon route (again with save to koji and save to scanner dbs selected) - if I'm doing multiple, I load the fence names into a script (check docs) and call it via api. + +**Back in dragonite admin:** + +1. Go back into Dragonite Admin, update worker count to appropriate amount, enable quests and set quest hours From e3cd4a04dbd1d434b0ed00dc48f425b162d9737d Mon Sep 17 00:00:00 2001 From: Clayton Burlison Date: Fri, 17 Nov 2023 07:00:49 -0600 Subject: [PATCH 5/6] docs: missing word --- docs/pages/client/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/client/getting-started.mdx b/docs/pages/client/getting-started.mdx index 46deeb84..1e35f232 100644 --- a/docs/pages/client/getting-started.mdx +++ b/docs/pages/client/getting-started.mdx @@ -30,7 +30,7 @@ A "project" in Kōji is how you create custom endpoints for distributing your ge 1. Projects don't have to be striclty used with external integrations though. Kōji's client can also import geofences by project so it may be convenient to group them for this reason as well. - Please [Integrations](/integrations) for assistance with a specific + Please see [Integrations](/integrations) for assistance with a specific project. From 69e3863fbb139dfb77776cf2789e1dfbe5a07208 Mon Sep 17 00:00:00 2001 From: Clayton Burlison Date: Fri, 17 Nov 2023 07:28:59 -0600 Subject: [PATCH 6/6] docs: Minor clarity on scanner project --- docs/pages/integrations.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/integrations.mdx b/docs/pages/integrations.mdx index 9a7459b6..45c5c40b 100644 --- a/docs/pages/integrations.mdx +++ b/docs/pages/integrations.mdx @@ -100,7 +100,7 @@ API Key: X-Poracle-Secret:{config.server.apiSecret} ### Project Setup -Use these values if Koji and Dragonite are on the **same** network. +Use these values for your "scanner project" if Koji and Dragonite are on the **same** network. ```yml API endpoint: http://{drago_host_ip}:{drago_port}/reload @@ -125,7 +125,7 @@ API key: Leave empty. Dragonite currently does not support authentication ### Project Setup -Use these values if Koji and Dragonite are on **different** networks. This will proxy the request through Dragonite Admin to Dragonite utilizing the api_secret value. +Use these values for your "scanner project" if Koji and Dragonite are on **different** networks. This will proxy the request through Dragonite Admin to Dragonite utilizing the api_secret value. ```yml API endpoint: http://{drago_admin_host_ip}:{drago_admin_port}/api/reload