Auspice fork from github of
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

85 lines
4.4 KiB

  1. ======================================
  2. Auspice servers
  3. ======================================
  4. The Auspice client (i.e. what you see in the web browser) requires a server behind it to
  5. - (a) serve the client HTML, CSS & JavaScript to the browser and
  6. - (b) handle certain `GET <>`_ requests from the client, for instance "give me the zika dataset to display".
  7. We provide a basic server to run Auspice locally -- any time you run `auspice view` or `auspice develop` you're running a server!
  8. In these cases, the server is running on your computer, sending datasets and narratives, which are stored on your machine, to the Auspice client.
  9. Alternatively, you can build your own server -- it just needs to satisfy the above two requirements.
  10. GET Requests
  11. ======================================
  12. Currently the client is able to make three requests:
  13. .. csv-table::
  14. :header: "address", "description"
  15. :widths: 1, 2
  16. `/charon/getAvailable`, return a list of available datasets and narratives
  17. `/charon/getDataset`, return the requested dataset
  18. `/charon/getNarrative`, return the requested narrative
  19. For instance, when you're running `auspice view` if you go to `localhost:4000/charon/getAvailable <http://localhost:4000/charon/getAvailable>`_ you'll see a list of the available datasets and narratives known to the server.
  20. Similarly, is a server which has handlers for these three API endpoints, so if you visit ` <>`_ you'll see Nextstrain's available datasets.
  21. See `the server API <../server/api.html>`_ for details about each of these requests.
  22. .. note::
  23. Note that "/charon" can be changed to any address you wish by customising the client at build time.
  24. See `the client-cusomisation API <../customise-client/api.html>` for more details.
  25. The "Default" Auspice Server
  26. ======================================
  27. The server provided with Auspice is intended to be run on your local setup.
  28. It thus scans the directories you provide when you run it in order to find datasets and narratives to serve.
  29. It has "handlers" for each of the above 3 requests -- i.e. bits of code that tell it how to handle each request.
  30. Customising the Default Auspice Server
  31. ======================================
  32. You can customise the default Auspice server by supplying your own handlers for each of the three GET requests.
  33. See `the API documentation <../server/api.html#suppling-custom-handlers-to-the-auspice-server>`_ for how to define these and provide them to `auspice view`.
  34. AGPL Source Code Requirement
  35. ============================
  36. Auspice is distributed under `AGPL 3.0 <>`_.
  37. Any modifications made to the auspice source code, including the auspice server, must be made publicly available.
  38. Writing Your Own Custom Server
  39. ======================================
  40. The provided Auspice server also lets you define your own handlers, allowing plenty of flexibility in how requests are handled.
  41. But if you _really_ want to implement your own server, then you only need to implement two things:
  42. - serve the `index.html` file (and linked javascript bundles) which are created by `auspice build` _and_
  43. - handle the three GET requests detailed above
  44. (If you're interested, this is what we do with ` <>`_, where only some of the pages use Auspice. You can see all the code behind that server [here](
  45. Deploying via Heroku
  46. ======================================
  47. It should be simple to deploy a custom version of auspice to any server, but we have experience using `Heroku <>`_ apps for this.
  48. Deploying to Heroku is straightforward, but there are a few points to note:
  49. 1. You must set the config var `HOST` to `` for the app.
  50. 1. You will need to either create a `Procfile` or a `npm run start` script which calls `auspice view` (or `npx auspice view` depending on how you implement auspice)
  51. 1. Make sure the datasets to be served are either (a) included in your git repo or (b) downloaded by the heroku build pipeline.
  52. `We use option (b) <>`_ by specifing a npm script called `heroku-postbuild`.
  53. .. toctree::
  54. :maxdepth: 0
  55. :titlesonly:
  56. :caption: Pages available
  57. api
  58. authentication