OwlBoard/backend
1
0
Fork 0
Code Issues 4 Pull Requests Packages Projects Releases Wiki Activity

Update 'README.md'

Browse Source
This commit is contained in:
Fred Boniface 2023-08-05 16:15:39 +01:00
parent 68207d1e5e
commit ca6f245a84
1 changed files with 11 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
README.md
View File

@ -4,70 +4,18 @@ OwlBoard is both a backend API, and a frontend Arrival/Departure board webapp.
Powered by Node.JS and using the ldbs-json module, the OwlBoard API provides up to date train departure information for any station in the UK. Powered by Node.JS and using the ldbs-json module, the OwlBoard API provides up to date train departure information for any station in the UK.
Whilst the application is open source, the webservice (owlboard.fb-infra.uk) is not openly available. National Rail Enquiries have limits on API access so to use this software yourself, you'll need to run your own instance after obtaining your own API key. ## Build
The webservice (owlboard.fb-infra.uk) may contain ads to support the running of the service, To build the application with Docker, clone the repository and run `docker build`
if ads are implemented, I intend to avoid 'dubious' advertisers that target and track users.
Currently only the public API is available as I am currently unable to request a key for the staff version.
## Requirements:
To run this server you will need:
- Docker or Kubernetes
## WebApp Colours:
- See CSS Variables
## API Endpoints: ## API Endpoints:
- /api/v1:
- /list: API Documentation has been removed as it is now out of date. I do intent to re-write the documentation at a later date.
- /stations:
- GET: Get list of stations
- Authenticated: No
- Returns JSON: `{"STATION NAME":{"CRS":"code","TIPLOC":"code"}}`
- /corpus:
- GET: Get full CORPUS Data
- Authenticated: No
- Returns JSON in original CORPUS format minus any blank values.
- /ldb:
- /{crs}:
- GET: Get arrival/departure board for {crs}
- Authenticated: No
- Returns JSON: Formatted as per ldbs-json module.
- /gitea:
- POST: Post issue to Gitea Repo
- Authenticated: Yes
- Not yet implemented, submit issues at https://git.fjla.uk/fred.boniface/owlboard
- /kube:
- /alive:
- GET: Check alive
- Authenticated: No
- Returns JSON: `{"status":"alive"}`
- /ready:
- GET: Check ready
- Authenticated: No
- Returns JSON: `{"state":""}` ready or not_ready.
## Stack:
- app.js -> Launches server, Entry Point, defines routers and middlewares.
- routes -> Routers - Directs requests to controllers.
- controllers -> Checks auth, sends response. Request doesn't pass further.
- services -> Provide data and do tasks, uses other services and utils.
- utils -> Provide utility functions that can be called by services.
- configs -> Provide configuration details for other files.
- static -> Holds files for static service, should be hosted behind a caching proxy.
## Configuration: ## Configuration:
The app is designed to be run within Kubernetes or within a Docker container, as such configuration is provided with environment variables. See the variable name and default options below. If a required configuration is not present the program will exit when that feature is initialised.
Configuration options are set through environment variables.
These configuration options are shared with other programs in the OwlBoard ecosystem.
|VAR|DEFAULT|REQUIRED|PURPOSE| |VAR|DEFAULT|REQUIRED|PURPOSE|
|:-:|:-----:|:------:|:-----:| |:-:|:-----:|:------:|:-----:|
@ -80,8 +28,8 @@ The app is designed to be run within Kubernetes or within a Docker container, as
|OWL_DB_HOST|localhost|NO|Database Server Host| |OWL_DB_HOST|localhost|NO|Database Server Host|
|OWL_LDB_KEY||YES|National Rail LDBWS API Key| |OWL_LDB_KEY||YES|National Rail LDBWS API Key|
|OWL_LDB_SVKEY||NO|National Rail LDBSVWS API Key| |OWL_LDB_SVKEY||NO|National Rail LDBSVWS API Key|
|OWL_LDB_CORPUSUSER||YES|Network Rail CORPUS API Username| |OWL_LDB_CORPUSUSER||YES|Network Rail NROD Username|
|OWL_LDB_CORPUSPASS||YES|Network Rail CORPUS API Password| |OWL_LDB_CORPUSPASS||YES|Network Rail NROD Password|
|OWL_GIT_ISSUEBOT||NO|Gitea API Key for issue reporting| |OWL_GIT_ISSUEBOT||NO|Gitea API Key for issue reporting|
|OWL_GIT_APIENDPOINT||NO|Gitea API Endpoint| |OWL_GIT_APIENDPOINT||NO|Gitea API Endpoint|
@ -89,16 +37,8 @@ In the case that OWL_LDB_SVKEY is not available, staff versions of departure boa
In the case that OWL_GIT_ISSUEBOT is not available, the 'Report Issue' page will not be able to POST data. In the case that OWL_GIT_ISSUEBOT is not available, the 'Report Issue' page will not be able to POST data.
## Database Layout ## Database
The OwlBoard application will build the database if required at startup. All it needs is authentication details for a MongoDB server. OwlBoard uses MongoDB
### Collections The OwlBoard database is managed by the dbmanager application which will configure and maintain the database and should be run at least twice a day to ensure timetable data is up to date, see https://git.fjla.uk/owlboard/db-manager.
|Collection|Contents|Purpose|
|:--------:|:------:|:-----:|
|corpus|Raw CORPUS data with blank keys removed|Code lookups|
|stations|Cleaned CORPUS Data, any objects with blank 3ALPHA & STANOX fields are removed|Validation before fetching Arr/Dep boards|
|meta|Lists the update time of corpus and station data|Will be used to update after a predetermined time period|
Note that even after removing all objects from the CORPUS with a blank 3ALPHA & STANOX, many items remain which are not stations and will not have a board available. Going forwards methods to remove non-stations from this data will be introduced.