From ec49d14835a7105128e7d643654f6688edc9e656 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=20Erik=20St=C3=B8wer?= Date: Thu, 23 May 2024 21:58:59 +0200 Subject: [PATCH 1/6] Improvements to README --- README.md | 54 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 31 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 168f98df..b0217a4f 100644 --- a/README.md +++ b/README.md @@ -65,27 +65,13 @@ If you don't use Google PubSub, sett this property: spring.cloud.gcp.pubsub.enabled=false ## Running locally -### Build -To build the project from source, you need Java 21 and Maven 3. -To run the unit tests you need additionally to install the [Google PubSub emulator](https://cloud.google.com/pubsub/docs/emulator). -The emulator can be installed locally with the following commands: -``` -gcloud components install pubsub-emulator -gcloud components update -``` -You can then locate the installation directory of the GCloud tool kit with the following command: +### Build -``` -gcloud info --format="value(installation.sdk_root)" -``` -The emulator executable is located under the sub-folder ```platform/pubsub-emulator/lib``` -and can be used in unit tests by setting the following property in the Spring Boot properties file: -``` -entur.pubsub.emulator.path=/usr/lib/google-cloud-sdk/platform/pubsub-emulator/lib/cloud-pubsub-emulator-0.6.0.jar -``` +To build the project from source, you need Java 21 and Maven 3. ### Database + #### Via Docker Install Docker. @@ -98,21 +84,43 @@ Now a Docker container is running in the background. Check its status with `dock To stop, find its ID from `docker ps`, and run `docker stop theid` (beginning of hash). To restart it, find the ID from `docker container list` and run `docker restart theid`. -Run the [script](./src/main/resources/db_init.sh). +Run the [database init script](./src/main/resources/db_init.sh). ### Run + **IntelliJ**: Right-click on `App.java` and choose Run (or Cmd+Shift+F10). Open Run -> Edit configurations, choose the correct configuration (Spring Boot -> App), and add `local` to Active profiles. Save the configuration. -If you want to run with google pubsub emulator also add `google-pubsub-emulator` to Active profiles. - **Command line**: `mvn spring-boot:run` -### GraphQL endpoint -http://localhost:11701/services/flexible-lines/rut/graphql +Uttu web server will expose APIs on port 11701 by default. + +### GraphQL endpoints + +Provider-independent GraphQL endpoint: + + /services/flexible-lines/providers/graphql + +Provider-specific GraphQL endpoint (replace {providerCode} with provider's codespace code): + + /services/flexible-lines/{providerCode}/graphql ## Netex Export -This api exports generated netex file to gcp storage, which is used to build graph. + +Uttu provides possibility (via provider specific GraphQL API) to export generated NeTEx file to a blobstore repository. +Choose one of three implementations with profiles: + +- `in-memory-blobstore` - stores exports in memory, exports are lost on restarts, suitable for development and testing +- `disk-blobstore` - stores exports on disk +- `gcp-blobstore` - stores exports in Google Cloud Storage, requires additional configuration + +Alternatively, provide a +[BlobStoreRepository](https://github.com/entur/rutebanken-helpers/blob/master/storage/src/main/java/org/rutebanken/helper/storage/repository/BlobStoreRepository.java) +bean for custom behavior. + +The following endpoint exposes exports for direct download: + + /services/flexible-lines/{providerCode}/export/ ## Error code extension From 5712af4ac111bcfc4e33b5dca3d7dbaad11487b3 Mon Sep 17 00:00:00 2001 From: Esko Suomi Date: Fri, 24 May 2024 09:59:08 +0300 Subject: [PATCH 2/6] add platform parameter to allow easier copy-paste-run of the command on AArch64 Macs when Rosetta2 is not used If run in a shell which is configured to not use Rosetta2 automatically the plain docker run command fails because an image with same platform (aarch64) is not available. Explicitly setting the --platform parameter gets around this permanently. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index b0217a4f..a7961e14 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,8 @@ To build the project from source, you need Java 21 and Maven 3. Install Docker. ```bash -docker run --name=uttu -d -e POSTGRES_USER=uttu -e POSTGRES_PASSWORD=uttu -e POSTGRES_DB=uttu -p 5432:5432 -v db_local:/var/lib/postgresql --restart=always postgis/postgis:13-3.3 +docker run --platform linux/amd64 --name=uttu -d -e POSTGRES_USER=uttu -e POSTGRES_PASSWORD=uttu -e POSTGRES_DB=uttu -p +5432:5432 -v db_local:/var/lib/postgresql --restart=always postgis/postgis:13-3.3 ``` Now a Docker container is running in the background. Check its status with `docker ps`. From 7670eac37293b417f0b353092531416feecdeda5 Mon Sep 17 00:00:00 2001 From: Esko Suomi Date: Fri, 24 May 2024 09:59:08 +0300 Subject: [PATCH 3/6] add a runnable code snippet example of the database initialization script --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index a7961e14..9dbd35c7 100644 --- a/README.md +++ b/README.md @@ -86,6 +86,9 @@ Now a Docker container is running in the background. Check its status with `dock To stop, find its ID from `docker ps`, and run `docker stop theid` (beginning of hash). To restart it, find the ID from `docker container list` and run `docker restart theid`. Run the [database init script](./src/main/resources/db_init.sh). +```bash +(cd src/main/resources && ./db_init.sh) +``` ### Run From a16a44ae70829a3682a7d7ecb9eb7b5169df5e38 Mon Sep 17 00:00:00 2001 From: Esko Suomi Date: Fri, 24 May 2024 09:59:08 +0300 Subject: [PATCH 4/6] Formatting pass for README to make all code blocks well defined, line widths and whitespaces/newlines uniform etc. --- README.md | 89 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 9dbd35c7..c3e8fca6 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ Back-end for Nplan, a simple timetable editor. Front-end is [Enki](https://github.com/entur/enki). ## Codestyle + Uttu uses [Prettier Java](https://github.com/jhipster/prettier-java). Use `mvn prettier:write` to reformat code before pushing changes. You can also configure your IDE to reformat code when you save a file. @@ -11,29 +12,35 @@ pushing changes. You can also configure your IDE to reformat code when you save Running uttu with vanilla security features requires an Oauth2 issuer, which can be set with the following property: - uttu.security.jwt.issuer-uri=https://my-jwt-issuer +```properties +uttu.security.jwt.issuer-uri=https://my-jwt-issuer +``` -In addition, a UserContextService implementation must be selected. The following gives full access to all authenticated users: +In addition, a UserContextService implementation must be selected. The following gives full access to all authenticated +users: - uttu.security.user-context-service=full-access +```properties +uttu.security.user-context-service=full-access +``` ### Run without authentication For the purpose of running locally, authentication can be switched off altogether by combining the full-access property above with the `local-no-authentication` profile. - ## Organisation registry Uttu needs an organisation registry in order to populate authority and operator references. You may provide a NeTEx file of organisations with - uttu.organisations.netex-file-uri= +```properties +uttu.organisations.netex-file-uri= +``` -or provide your own implementation of the `OrganisationRegistry` interface –– -see `src/main/java/no/entur/uttu/organisation/spi/OrganisationRegistry.java`. +or provide your own implementation of the [`OrganisationRegistry`](src/main/java/no/entur/uttu/organisation/spi/OrganisationRegistry.java) interface. -Refer to `src/test/resources/fixtures/organisations.xml` for an example of a NeTEx file with organisations. +Refer to [`src/test/resources/fixtures/organisations.xml`](src/test/resources/fixtures/organisations.xml) for an example +of a NeTEx file with organisations. ## Stop place registry @@ -42,12 +49,14 @@ journey patterns with fixed transit stops, and with hail-and-ride areas. You may provide a NeTEx file of stop places with - uttu.stopplace.netex-file-uri= +```properties +uttu.stopplace.netex-file-uri= +``` -or provide your own implementation of the `StopPlaceRegistry` interface –– -see `src/main/java/no/entur/uttu/stopplace/spi/StopPlaceRegistry.java`. +or provide your own implementation of the [`StopPlaceRegistry`](src/main/java/no/entur/uttu/stopplace/spi/StopPlaceRegistry.java) interface. -Refer to `src/test/resources/fixtures/stopplace.xml` for an example of a NeTEx file with stop places. +Refer to [`src/test/resources/fixtures/stopplace.xml`](src/test/resources/fixtures/stopplace.xml) for an example of a +NeTEx file with stop places. ## Optional export notification message @@ -76,17 +85,20 @@ To build the project from source, you need Java 21 and Maven 3. Install Docker. -```bash +```shell docker run --platform linux/amd64 --name=uttu -d -e POSTGRES_USER=uttu -e POSTGRES_PASSWORD=uttu -e POSTGRES_DB=uttu -p 5432:5432 -v db_local:/var/lib/postgresql --restart=always postgis/postgis:13-3.3 ``` Now a Docker container is running in the background. Check its status with `docker ps`. -To stop, find its ID from `docker ps`, and run `docker stop theid` (beginning of hash). To restart it, find the ID from `docker container list` and run `docker restart theid`. +To stop, find its ID from `docker ps`, and run `docker stop theid` (beginning of hash). To restart it, find the ID from +`docker container list` and run `docker restart theid`. + +Run the [database initialization script](./src/main/resources/db_init.sh). Run the [database init script](./src/main/resources/db_init.sh). -```bash +```shell (cd src/main/resources && ./db_init.sh) ``` @@ -103,7 +115,7 @@ Uttu web server will expose APIs on port 11701 by default. Provider-independent GraphQL endpoint: - /services/flexible-lines/providers/graphql +/services/flexible-lines/providers/graphql Provider-specific GraphQL endpoint (replace {providerCode} with provider's codespace code): @@ -119,7 +131,7 @@ Choose one of three implementations with profiles: - `gcp-blobstore` - stores exports in Google Cloud Storage, requires additional configuration Alternatively, provide a -[BlobStoreRepository](https://github.com/entur/rutebanken-helpers/blob/master/storage/src/main/java/org/rutebanken/helper/storage/repository/BlobStoreRepository.java) +[`BlobStoreRepository`](https://github.com/entur/rutebanken-helpers/blob/master/storage/src/main/java/org/rutebanken/helper/storage/repository/BlobStoreRepository.java) bean for custom behavior. The following endpoint exposes exports for direct download: @@ -128,33 +140,38 @@ The following endpoint exposes exports for direct download: ## Error code extension -Some errors are augmented with a code extension. See [ErrorCodeEnumeration](src/main/java/no/entur/uttu/error/ErrorCodeEnumeration.java) for complete list of codes. +Some errors are augmented with a code extension. See [`ErrorCodeEnumeration`](src/main/java/no/entur/uttu/error/codes/ErrorCodeEnumeration.java) +for complete list of codes. The code is optionally accompanied by a key-value metadata map under the `metadata` extension. The extension appears in the response as follows (example is trimmed): +```json +{ + "errors": [ { - "errors": [ - { - "extensions": { - "code": "ORGANISATION_NOT_VALID_OPERATOR" - } - } - ] + "extensions": { + "code": "ORGANISATION_NOT_VALID_OPERATOR" + } } + ] +} +``` With metadata: - + +```json +{ + "errors": [ { - "errors": [ - { - "extensions": { - "code": "ENTITY_IS_REFERENCED", - "metadata": { - "numberOfReferences": 1 - } - } - } - ] + "extensions": { + "code": "ENTITY_IS_REFERENCED", + "metadata": { + "numberOfReferences": 1 + } + } } + ] +} +``` From 382cf2889ae15067cb993511dae5892cd16c4ab8 Mon Sep 17 00:00:00 2001 From: Esko Suomi Date: Fri, 24 May 2024 12:04:31 +0300 Subject: [PATCH 5/6] reformat docker command for both easier readability and easy copy-paste for terminal --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c3e8fca6..976078d0 100644 --- a/README.md +++ b/README.md @@ -86,8 +86,17 @@ To build the project from source, you need Java 21 and Maven 3. Install Docker. ```shell -docker run --platform linux/amd64 --name=uttu -d -e POSTGRES_USER=uttu -e POSTGRES_PASSWORD=uttu -e POSTGRES_DB=uttu -p -5432:5432 -v db_local:/var/lib/postgresql --restart=always postgis/postgis:13-3.3 +docker run \ + --platform linux/amd64 \ + --name=uttu \ + -d \ + -e POSTGRES_USER=uttu \ + -e POSTGRES_PASSWORD=uttu \ + -e POSTGRES_DB=uttu \ + -p 5432:5432 \ + -v db_local:/var/lib/postgresql \ + --restart=always \ + postgis/postgis:13-3.3 ``` Now a Docker container is running in the background. Check its status with `docker ps`. From a7e2800cef526b1f6f766d4e34244913166a1e56 Mon Sep 17 00:00:00 2001 From: Esko Suomi Date: Fri, 24 May 2024 12:05:05 +0300 Subject: [PATCH 6/6] a few more formatting adjustments which were missed in previous commit --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 976078d0..466155ed 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,6 @@ To stop, find its ID from `docker ps`, and run `docker stop theid` (beginning of Run the [database initialization script](./src/main/resources/db_init.sh). -Run the [database init script](./src/main/resources/db_init.sh). ```shell (cd src/main/resources && ./db_init.sh) ``` @@ -124,7 +123,7 @@ Uttu web server will expose APIs on port 11701 by default. Provider-independent GraphQL endpoint: -/services/flexible-lines/providers/graphql + /services/flexible-lines/providers/graphql Provider-specific GraphQL endpoint (replace {providerCode} with provider's codespace code): @@ -132,7 +131,7 @@ Provider-specific GraphQL endpoint (replace {providerCode} with provider's codes ## Netex Export -Uttu provides possibility (via provider specific GraphQL API) to export generated NeTEx file to a blobstore repository. +Uttu exports (via provider specific GraphQL API) generated NeTEx file to a blobstore repository. Choose one of three implementations with profiles: - `in-memory-blobstore` - stores exports in memory, exports are lost on restarts, suitable for development and testing