Skip to content

Commit

Permalink
Merge pull request #320 from esuomi/onboarding
Browse files Browse the repository at this point in the history 
Documentation updates based on onboarding experience
  • Loading branch information
@testower
testower authored May 24, 2024
2 parents 447f9ea + a7e2800 commit 653b4ba
Showing 1 changed file with 94 additions and 57 deletions.
151 changes: 94 additions & 57 deletions README.md
View file
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
}
}
}
]
}
```

0 comments on commit 653b4ba

Please sign in to comment.