Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation updates based on onboarding experience #320

Merged
merged 6 commits into from
May 24, 2024
151 changes: 94 additions & 57 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,36 +4,43 @@
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.

## Security

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=<path-to-file>
```properties
uttu.organisations.netex-file-uri=<path-to-file>
```

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

Expand All @@ -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=<path-to-file>
```properties
uttu.stopplace.netex-file-uri=<path-to-file>
```

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

Expand All @@ -65,84 +74,112 @@ 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.

```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
```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 [script](./src/main/resources/db_init.sh).
```shell
(cd 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 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
- `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

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
}
}
}
]
}
```