From ca6f245a84ed3b1330c964c4984f199a8f414196 Mon Sep 17 00:00:00 2001 From: Fred Boniface Date: Sat, 5 Aug 2023 16:15:39 +0100 Subject: [PATCH] Update 'README.md' --- README.md | 82 ++++++++----------------------------------------------- 1 file changed, 11 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index 0a92818..30df414 100644 --- a/README.md +++ b/README.md @@ -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. -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, -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 +To build the application with Docker, clone the repository and run `docker build` ## API Endpoints: - - /api/v1: - - /list: - - /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. +API Documentation has been removed as it is now out of date. I do intent to re-write the documentation at a later date. ## 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| |:-:|:-----:|:------:|:-----:| @@ -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_LDB_KEY||YES|National Rail LDBWS API Key| |OWL_LDB_SVKEY||NO|National Rail LDBSVWS API Key| -|OWL_LDB_CORPUSUSER||YES|Network Rail CORPUS API Username| -|OWL_LDB_CORPUSPASS||YES|Network Rail CORPUS API Password| +|OWL_LDB_CORPUSUSER||YES|Network Rail NROD Username| +|OWL_LDB_CORPUSPASS||YES|Network Rail NROD Password| |OWL_GIT_ISSUEBOT||NO|Gitea API Key for issue reporting| |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. -## 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 - -|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. \ No newline at end of file +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.