Skip to content

Commit

Permalink
adapted our docs
Browse files Browse the repository at this point in the history
  • Loading branch information
CommanderStorm committed Dec 11, 2022
1 parent 39d0a42 commit 8098e87
Show file tree
Hide file tree
Showing 10 changed files with 415 additions and 280 deletions.
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ For an overview of how the components work, have a look at the

- `data/` contains the code to obtain and process the data
- `server/` contains the API server written in Rust, including MeiliSearch as a search backend
- `feedback/` contains the feedback-API server written in Rust
- `webclient/` contains a JS based web-frontend for the API
- `deployment/` contains deployment related configuration
- `map/` contains information about our own map, how to style it and how to run it
Expand Down
105 changes: 8 additions & 97 deletions feedback/README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
# Server

This folder contains the backend server for NavigaTUM.
This folder contains the feedback-API server for NavigaTUM.

Our server is architected in different submodules, each of which is responsible for a specific task.
They share very few things and are mostly independent of each other.
This is separated from the server because:

- it has virtually no shared dependencies (natural faultline)
- this way, we can deploy the feedback-API independently of the main server (both in time, scaling and reliability)
- security: this way, we can increase our isolation

## Getting started

Expand All @@ -17,99 +20,7 @@ Please follow the [system dependencys docs](resources/documentation/Dependencys.
Run `cargo run` to start the server.
The server should now be available on `localhost:6000`.

Note that `cargo run --release` is used to start the server for an optimised production build (use this if you want to profile the `search` or `preview` functions, it makes quite a difference).

### Additional dependency's for some API endpoints

We have a few API endpoints which require additional dependencies.

As a general rule of thumb, if you probably want to **skip the tileserver**, but want to **do the SQLite Database** and **MeiliSearch** setup.
The reason for this is, that the `preview` endpoint is the only endpoint, which requires the tileserver and said endpoint is a non-essential part of the project.

#### How to Set up the Sqlite Database (needed for the `get`, `legacy_redirect` and `preview` endpoints)

##### Getting the data

To populate the database, you will need to get said data.
There are multiple ways to do this, but the easiest way is to download the data from our [website](https://nav.tum.de/).

(Assuming you are in the `server` directory)

```bash
mkdir -p data
wget -P data https://nav.tum.de/cdn/api_data.json
```

Alternatively, you can run the `data` part of this project and generate this file by that part of our docs.
To link the output directory to the server data directory, so that you don't need to copy on every update you can use:

```bash
ln -s ../data/output data
```

##### Setting up the database

To set up the database, you will need to run the `load_api_data_to_db.py` script:

```bash
python3 load_api_data_to_db.py
```

#### How to Set up the tileserver (needed for the `preview` endpoint)

To set up your tileserver, head over to the [`map`](https://github.com/TUM-Dev/NavigaTUM/tree/main/map) folder and follow the instructions there.

#### How to Set up MeiliSearch (needed for the `search` endpoint)

The server uses [MeiliSearch](https://github.com/meilisearch/MeiliSearch) as a backend for search.
For a local test environment you can skip this step if you don't want to test or work on search.

There are a lot of different ways to run MeiliSearch (see on their repo). Here we compile it
from sources:

```bash
# Clone MeiliSearch
cd ..
git clone https://github.com/meilisearch/MeiliSearch.git -b v0.22.0
cd MeiliSearch

# Build and run
cargo run --release
```

Next, we need to add our index and configure search:

```bash
# Create index
curl -i -X POST 'http://localhost:7700/indexes' --header 'content-type: application/json' --data '{ "uid": "entries", "primaryKey": "ms_id" }'

# Set filterable attributes
curl -X PUT 'http://localhost:7700/indexes/entries/settings/filterable-attributes' --data '["facet"]'

# Upload entries data
curl -i -X PUT 'http://localhost:7700/indexes/entries/documents' --header 'content-type: application/json' --data-binary @data/search_data.json

# Configure index
curl -X PUT 'http://localhost:7700/indexes/entries/settings/ranking-rules' --data '["words","typo","rank:desc","exactness","proximity","attribute"]'

curl -X PUT 'http://localhost:7700/indexes/entries/settings/synonyms' --data @../data/search_synonyms.json

curl -X PUT 'http://localhost:7700/indexes/entries/settings/searchable-attributes' --data '[ "ms_id", "name", "arch_name", "type", "type_common_name", "parent_building", "parent_keywords", "address", "usage" ]'
```

If you want to update the data in the index, run:

```bash
curl -i -X PUT 'http://localhost:7700/indexes/entries/documents' --header 'content-type: application/json' --data-binary @data/search_data.json
```

And if you want to delete the index, run:

```bash
curl -X DELETE 'http://localhost:7700/indexes/entries'
```

MeiliSearch provides an interactive interface at [http://localhost:7700](http://localhost:7700).
Note that `cargo run --release` is used to start the server for an optimised production build (use this if you want to profile performance, it makes quite a difference).

### API-Changes

Expand All @@ -135,7 +46,7 @@ st run --workers=auto --base-url=http://localhost:6000 --checks=all ../openapi.y
```

Some fuzzing-goals may not be available for you locally, as they require prefix-routing (f.ex.`/cdn` to the CDN) and some fuzzing-goals are automatically tested in our CI.
You can exchange `--base-url=http://localhost:6000` to `--base-url=https://nav.tum.sexy` for the full public API, or restrict your scope using a option like `--endpoint=/api/feedback/..`.
You can exchange `--base-url=http://localhost:6000` to `--base-url=https://nav.tum.sexy` for the full public API, or restrict your scope using a option like `--endpoint=/api/feedback/`.

## License

Expand Down
41 changes: 39 additions & 2 deletions openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,24 @@ paths:
type: string
example: 'https://github.com/TUM-Dev/navigatum/tree/eb10c1f4cfbbd66d37f2f9e5e13139c1fde15a4b'
tags:
- core
- health
/api/feedback/source_code:
get:
operationId: feedback-source_code
summary: Get link to running source-code
description: |
This endpoint returns a link to the source-code of the repository at the currently running version.
This endpoint is not required for modifications (as the license is not AGPL), but strongly encouraged.
responses:
'200':
description: The link to the source-code of the repository at the currently running version
content:
text/plain:
schema:
type: string
example: 'https://github.com/TUM-Dev/navigatum/tree/eb10c1f4cfbbd66d37f2f9e5e13139c1fde15a4b'
tags:
- health
/api/feedback/get_token:
post:
operationId: get_token
Expand Down Expand Up @@ -974,6 +991,26 @@ paths:
content: {}
tags:
- health
/api/feedback/health:
get:
operationId: feedback-health
summary: feedback-API healthcheck
description: |
If this endpoint does not return 200, the API is experiencing a catastrophic outage. Should never happen.
responses:
'200':
description: Ok
content:
text/plain:
schema:
type: string
enum:
- healthy
'503':
description: Service Unavailable
content: {}
tags:
- health
/cdn/health:
get:
operationId: cdn-health
Expand Down Expand Up @@ -1671,7 +1708,7 @@ tags:
- name: feedback
description: the API to access/search for room information
- name: health
description: 'These endpoints are used to check the health of the API, website and cdn'
description: 'These endpoints are used to check the health of our components'
externalDocs:
description: Visit our Github Page for more in-depth documentation
url: 'https://github.com/TUM-Dev/navigatum'
Loading

0 comments on commit 8098e87

Please sign in to comment.