Todo
Insert todo’s here
TMLite Server
This server uses fastAPI to serve the contents of the prototype_model.json
file via a web interface.
Starting the Server
I would suggest that new users check out the documentation for fastAPI as this will clearly demonstrate how this is set up.
The simplest way to launch the current server is via docker-compose
. Running the following:
docker-compose up --build
This will execute the following docker-compose which will start a container running the server and exposing port 80 of the container:
version: '2'
services:
tmlite:
build:
context: .
dockerfile: Dockerfile
container_name: ska-sdp-tmlite-server
volumes:
- "/var/run/docker.sock:/var/run/docker.sock"
hostname: localhost
expose:
- "80"
ports:
- "80:80/tcp"
command: ["uvicorn", "ska.tmlite.main:app", "--host", "0.0.0.0", "--port", "80"]
Accessing The Server
One of the advantages of fastAPI is that it self documents. So once you have the server running simply connect to it:
> docker-compose up --build
.....
> ska-sdp-tmlite-server | INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit)
Assuming you kept the same port exposure open your browser at
http://localhost:80/docs
For example the request to obtain the full model is:
>curl -X 'GET' 'http://localhost/model/current' -H 'accept: application/json'
And this will return the full model
The Model Structure
On server construction there are two models created a “default” model and a “current” model. The default model should not be altered but the current one can be changed in part. Also new models can be added and altered at will. WHen the server shuts down all alterations are lost. THis scheme is not for the long term storage of models - but the short term access of them.
Storage backends
The initial Telescope Model data is loaded
from one of the supported storage backends.
The storage to be used is selected
by setting the STORAGE_BACKEND
environment variable
to the name of one of the supported storage backends.
Currently only a GitLab storage backend is supported,
gitlab
backend
The gitlab
storage backend
loads a Telescope Model file
from the SKA SDP TMLite data repository repository.
Please read its documentation,
as it explains how data is organised and presented.
Note that like this project,
the TMLite data repository is also currently designed
to work in a read-only fashion
from the standpoint of this TMLite server.
A set of environment variables control this process,
all of which must be prefixed with STORAGE_BACKEND__
:
CLONE_DIRECTORY
is the local directory holding the clone of the repository, defaults to<OS-temp-dir>/tmplite_gitlab_repository
.PRIVATE_TOKEN
,JOB_TOKEN
andOAUTH_TOKEN
, if defined, are used for authentication against GitLab.MODEL_PATH
is the file to be loaded from the repository clone as the Telescope Model, it defaults toprototype_model.json
.REPOSITORY_REF
indicates the git reference (SHA, branch, tag) to retrieve when cloning the repository. If not given, the default repository branch is used.
If the CLONE_DIRECTORY
doesn’t exist
then a clone of the repository is created in that location.
If it exists no further action occurs.
Note that this implies
that this backend can be used to point
to an existing directory/file in the local filesystem
containing a valid Telescope Model,
even if that directory is not a git repository.
At the moment, and as mentioned earlier, all editions are ephemeral: once the server shuts down they are all lost.
Example API tasks
Probably the simplest way to access this is via the python requests
module - but of course for the GET methods you
can even use a browser if you want.
Getting the full default model
A simple python api:
> import request
> url = "http://localhost/model/default/"
> response = requests.get(url)
Getting the current model
Is as simple as changing the URL:
> url = "http://localhost/model/current/"
But there are a number of methods coded up for you to get subsets of the model and even change things for example:
> url = "http://localhost/current/ska1_low/update_antennas"
> mccs = {"station_ids": ['0','1','2','3']}
> response = requests.post(url,json=mccs)
This will update the current model to only include antennas from the list.
Extending the Model and Server
This is a minimal hello world
implementation - You should have enough information to extend the server to respond more smartly to requests and
return slices through the model for example.