{"id":18542170,"url":"https://github.com/heremaps/naksha","last_synced_at":"2025-04-09T18:31:32.671Z","repository":{"id":144495102,"uuid":"492048856","full_name":"heremaps/naksha","owner":"heremaps","description":"Naksha Hub is a RESTful web service for the access and management of geospatial data.","archived":false,"fork":false,"pushed_at":"2025-04-09T13:01:49.000Z","size":44421,"stargazers_count":6,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"v2","last_synced_at":"2025-04-09T14:24:36.666Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"heremaps/xyz-hub","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heremaps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-13T21:48:42.000Z","updated_at":"2025-04-08T05:51:47.000Z","dependencies_parsed_at":"2023-09-23T17:05:24.927Z","dependency_job_id":"aa27b1dd-42f6-4071-bbe4-c8181771bb6c","html_url":"https://github.com/heremaps/naksha","commit_stats":null,"previous_names":["heremaps/naksha"],"tags_count":182,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fnaksha","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fnaksha/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fnaksha/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fnaksha/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heremaps","download_url":"https://codeload.github.com/heremaps/naksha/tar.gz/refs/heads/v2","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248087753,"owners_count":21045584,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T20:07:36.588Z","updated_at":"2025-04-09T18:31:27.660Z","avatar_url":"https://github.com/heremaps.png","language":"Java","readme":"![Naksha (नक्शा) - XYZ-Hub](xyz.svg)\n---\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n[Naksha](https://en.wikipedia.org/wiki/Naksha) [(नक्शा)](https://www.shabdkosh.com/search-dictionary?lc=hi\u0026sl=en\u0026tl=hi\u0026e=%E0%A4%A8%E0%A4%95%E0%A5%8D%E0%A4%B6%E0%A4%BE) is the name of this fork of the [XYZ-Hub](https://github.com/heremaps/xyz-hub) (pronounced **nakshaa** or **nakśā**). It stays a web service for the access and management of geospatial data. This spin-off was done to independently realize needed new features, not planned to be supported in the original [XYZ-Hub](https://github.com/heremaps/xyz-hub) project. The architecture was modified to allow extensions and plug-ins.\n\nThe meaning of [Naksha](https://en.wikipedia.org/wiki/Naksha)-Hub is “Map-Hub”.\n\nNaksha service, has been designed to primarily offer:\n* GeoJson based REST API as service\n* GeoJson based Java API as library (interacting directly with database)\n* Support Postgres as default Storage system (with inbuilt transactional and history capabilities)\n* Support publishing Data Change events (with atleast-once messaging guarantee)\n* Additionally, Extension framework to provide ability:\n    * to integrate REST APIs with your own custom Storage mechanism\n    * to inject custom business logic as part of REST API request processing pipeline\n    * to inject custom business logic as part of Data change event processing pipeline (subscription based)\n\n\n# Overview\n\nNaksha features are:\n* Organize geo datasets in _collections_.\n* Organize access to your data via _spaces_.\n* Listen to changes done to your data via _subscriptions_.\n* Store and manipulate individual geo features (points, line-strings, polygons).\n* Retrieve geo features as vector tiles, with or without clipped geometries.\n* Search for geo features spatially using a bounding box, radius, or any custom geometry.\n* Implement own customer data processing logic as embedded handler or external extension handler.\n* Explore geo features by filtering property values.\n* Connect with your own data sources.\n* Use default PostgresQL implementation with your own database.\n* Build a real-time geo-data pipeline with processors.\n\nNaksha uses [GeoJSON](https://www.rfc-editor.org/rfc/rfc7946.html) as the main geospatial data exchange format.\n\n# Prerequisites\n\n* Java 17+\n* Gradle 7.2+\n* Postgres 14+ with PostGIS 2.5+\n\n# Getting started\n\nClone and install the project using:\n\n```bash\ngit clone https://github.com/heremaps/naksha.git\ncd naksha\ngradle clean build\n```\n\n### Containerized Postgres \u0026 running with extensions\n\nNaksha relies strongly on Postgres - you need running instance if you want to run Naksha locally.\nSupported Postgres version is 14+ (the newer the better).\nApart from bare Postgres, Naksha needs [PostGIS]() extension which is mandatory. Apart from that, optional, but highly recommended extensions that are supported include: `pg_hint_plan` and `pg_stat_statements`.\n\nYou can use standalone instance installed directly on your host machine but there's also a docker image that hosts Postgres 16 with all the extensions mentioned above already installed. You can find its definition in [this Dockerfile](here-naksha-app-service/src/test/psql_container/Dockerfile).\n\nTo use the containerized Postgres with your locally runnning Naksha:\n1) Navigate to [Dockerfile directory](here-naksha-app-service/src/test/psql_container):\n   ```\n   cd here-naksha-app-service/src/test/psql_container\n   ```\n2) Build the image:\n   ```\n   docker build --no-cache -t \u003cIMAGE_ID\u003e . \n   ```\n3) Run the container (supplied options omit all auth - use it only locally, tweak if needed):\n   ```\n   docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres -e POSTGRES_INITDB_ARGS=\"--auth-host=trust --auth-local=trust\" -e POSTGRES_HOST_AUTH_METHOD=trust \u003cIMAGE_ID\u003e\n   ```\n4) Now your database should be available on `localhost` with port `5432` - you can start Naksha the same way as described in [Run App](#run-app) section.\n\n5) \\[optional extension run\\] Now you can run naksha jar and include [example config with additional extensions enabled](here-naksha-app-service/src/main/resources/test-config-with-extensions.json) like so:\n```\njava -jar build/libs/naksha-2.0.6-all.jar test-config-with-extensions 'jdbc:postgresql://localhost:5432/postgres?user=postgres\u0026password=pswd\u0026schema=naksha\u0026app=naksha_local\u0026id=naksha_admin_db'\n```\n\n### Run App\n\n#### Running local fat jar\n\nThe service could also be started directly from a fat jar. In this case Postgres and the other optional dependencies need to be started separately.\n\nTo build the fat jar, at the root project directory, run one of the following:\n\n```bash\n# Using machine installed gradle (through apt, brew,... package managers)\ngradle shadowJar\n# Using gradle wrapper\n./gradlew shadowJar\n```\n\nThe jar can be found under `build/libs/`.\n\nTo ramp up Naksha with the jar, run:\n\n```bash\njava -jar \u003cjar-file\u003e \u003cconfig-id\u003e \u003cdatabase-url\u003e\n\n# Example 1 : Start service with test config against default Database URL (useful for local env)\njava -jar build/libs/naksha-2.0.6-all.jar test-config\n# Example 2 : Start service with given custom config and custom database URL (useful for cloud env)\njava -jar build/libs/naksha-2.0.6-all.jar cloud-config 'jdbc:postgresql://localhost:5432/postgres?user=postgres\u0026password=pswd\u0026schema=naksha\u0026app=naksha_local\u0026id=naksha_admin_db'\n# Example 3 : Start service with given custom config and default (local) database URL\njava -jar build/libs/naksha-2.0.6-all.jar custom-config\n\n```\n\nThen use a web browser to connect to `localhost:8080`, an OK message should be displayed if the service is up and running.\n\n#### Running Naksha in container\n\nTo run Naksha in container, take a look at [these docs](docker/README.md)\n\n### OpenAPI specification\n\nOnce application is UP, the OpenAPI specification is accessible at `http(s)://{host}:{port}/hub/swagger/index.html`, by default at [http://localhost:8080/hub/swagger/index.html](http://localhost:8080/hub/swagger/index.html)\n\n\n### Configuration\n\nThe service persists out of modules with a bootstrap code to start the service. Service provides default configuration in [default-config.json](here-naksha-lib-hub/src/main/resources/config/default-config.json).\n\nThe custom (external) configuration file can be supplied by modifying environment variable or by creating the `default-config.json` file in the corresponding configuration folder.\nThe exact configuration folder is platform dependent, but generally follows the [XGD user configuration directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html), standard, so on Linux being by default `~/.config/naksha/v{x.x.x}/`. For Windows the files will reside in the [CSIDL_PROFILE](https://learn.microsoft.com/en-us/windows/win32/shell/csidl?redirectedfrom=MSDN) folder, by default `C:\\Users\\{username}\\.config\\naksha\\v{x.x.x}\\`.\nHere `{x.x.x}` is the Naksha application version (for example, if version is `2.0.7`, then path will be `...\\.config\\naksha\\v2.0.7`)\n\nNext to this, an explicit location can be specified via the environment variable `NAKSHA_CONFIG_PATH`, this path will not be extended by the `naksha/v{x.x.x}` folder, so you can directly specify where to keep the config files. This is important when you want to start multiple versions of the service: `NAKSHA_CONFIG_PATH=~/.config/naksha/ java -jar naksha.jar {arguments}`.\n\nIn the custom config file, the name of the individual properties can be set as per source code here [NakshaHubConfig](here-naksha-lib-hub/src/main/java/com/here/naksha/lib/hub/NakshaHubConfig.java).\nAll properties annotated with `@JsonProperty` can be set in custom config file.\n\nConfig file is loaded using `{config-id}` supplied as CLI argument, as per following precedence on file location (first match wins):\n1. using env variable `NAKSHA_CONFIG_PATH` (full path will be `$NAKSHA_CONFIG_PATH/{config-id}.json`)\n2. as per user's home directory `user.home` (full path will be `{user-home}/.config/naksha/v{x.x.x}/{config-id}.json` )\n3. as per config previously loaded in Naksha Admin Storage (PostgreSQL database)\n4. default config loaded from jar (`here-naksha-lib-hub/src/main/resources/config/default-config.json`)\n\n```bash\n# Example of env variable NAKSHA_CONFIG_PATH\n\n# First, copy default config to custom location\nexport NAKSHA_CONFIG_PATH=/my-location/naksha\ncp here-naksha-lib-hub/src/main/resources/config/default-config.json $NAKSHA_CONFIG_PATH/\n\n# Modify config as per need\nvi $NAKSHA_CONFIG_PATH/default-config.json\n\n# Start application using above config\njava -jar naksha.jar default-config\n```\n\n# Usage\n\nStart using the service by creating a _space_:\n\n```bash\ncurl -H \"content-type:application/json\" \\\n-d '{\"id\": \"test-space\", \"title\": \"my first space\", \"description\": \"my first geodata repo\"}' \\\n\"http://localhost:8080/hub/spaces\"\n```\n\nThe service will respond with the space definition including the space ID (should you not specify an own `id`):\n\n```json\n{\n    \"id\": \"test-space\",\n    \"title\": \"my first space\",\n    \"description\": \"my first geodata repo\",\n    \"storage\": {\n        \"id\": \"psql\",\n        \"params\": null\n    },\n    \"owner\": \"ANONYMOUS\",\n    \"createdAt\": 1576601166681,\n    \"updatedAt\": 1576601166681,\n    \"contentUpdatedAt\": 1576601166681,\n    \"autoCacheProfile\": {\n        \"browserTTL\": 0,\n        \"cdnTTL\": 0,\n        \"serviceTTL\": 0\n    }\n}\n```\n\nYou can now add _features_ to your brand new space:\n```bash\ncurl -H \"content-type:application/geo+json\" -d '{\"type\":\"FeatureCollection\",\"features\":[{\"type\":\"Feature\",\"geometry\":{\"type\":\"Point\",\"coordinates\":[-2.960847,53.430828]},\"properties\":{\"name\":\"Anfield\",\"@ns:com:here:xyz\":{\"tags\":[\"football\",\"stadium\"]},\"amenity\":\"Football Stadium\",\"capacity\":54074,\"description\":\"Home of Liverpool Football Club\"}}]}' http://localhost:8080/hub/spaces/pvhQepar/features\n```\n\nThe service will respond with the inserted geo features:\n```json\n{\n    \"type\": \"FeatureCollection\",\n    \"etag\": \"b67016e5dcabbd5f76b0719d75c84424\",\n    \"features\": [\n        {\n            \"type\": \"Feature\",\n            \"id\": \"nf36KMsQAUYoM5kM\",\n            \"geometry\": {\n                \"type\": \"Point\",\n                \"coordinates\": [ -2.960847, 53.430828 ]\n            },\n            \"properties\": {\n                \"@ns:com:here:xyz\": {\n                    \"space\": \"pvhQepar\",\n                    \"createdAt\": 1576602412218,\n                    \"updatedAt\": 1576602412218,\n                    \"tags\": [ \"football\", \"stadium\" ]\n                },\n                \"amenity\": \"Football Stadium\",\n                \"name\": \"Anfield\",\n                \"description\": \"Home of Liverpool Football Club\",\n                \"capacity\": 54074\n            }\n        }\n    ],\n    \"inserted\": [\n        \"nf36KMsQAUYoM5kM\"\n    ]\n}\n```\n\n# Testing locally\n\nTo run tests locally run Gradle `test` task:\n```bash\n./gradlew test\n```\n\nCode coverage report is generated with use of [jacoco](https://www.jacoco.org/)\n\nTo generate **subproject** level coverage, use Gradle task `jacocoTestReport`:\n\n```bash\n./gradlew test jacocoTestReport\n```\n\nOutputs for each subproject will be stored in `/[module]/build/reports/jacoco/test/html/index.html`\n\nTo generate **root** level aggregated coverage, use additional Gradle task `testCodeCoverageReport`:\n\n```bash\n./gradlew test jacocoTestReport testCodeCoverageReport\n```\n\nOutputs will be stored in `/build/reports/jacoco/testCodeCoverageReport/html/index.html`\n\nTo validate test coverage, run `jacocoTestCoverageVerification` Gradle task:\n```bash\n./gradlew test jacocoTestReport jacocoTestCoverageVerification\n```\n\n\n\n\n# Acknowledgements\n\nXYZ Hub uses:\n\n* [Vertx](http://vertx.io/)\n* [Geotools](https://github.com/geotools/geotools)\n* [JTS](https://github.com/locationtech/jts)\n* [Jackson](https://github.com/FasterXML/jackson)\n\nand [others](./pom.xml#L177-L479).\n\n# Contributing\n\nYour contributions are always welcome! Please have a look at the [contribution guidelines](CONTRIBUTING.md) first.\n\n# License\nCopyright (C) 2017-2022 HERE Europe B.V.\n\nThis project is licensed under the Apache License, Version 2.0 - see the [LICENSE](./LICENSE) file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheremaps%2Fnaksha","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheremaps%2Fnaksha","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheremaps%2Fnaksha/lists"}