wwtdatatool serve

The serve command starts a local HTTP server that allows you to preview a draft WTML file in WWT.

Usage

wwtdatatool serve [--port PORT] [--heartbeat] {PATH}

  • The PATH argument specifies the directory that will be used as the root for the files in the server

  • The optional --port PORT argument allows you to specify the specific port at which the server will listen for connections

  • The optional --heartbeat argument can be used in scripting scenarios to help make sure that the server exits when launched over SSH. It is unlikely that you will ever need to specify it explicitly.

Details

The HTTP server launched by this command is mostly a standard, fairly dumb static file server. If it receives an HTTP request for the path /foo/bar, it will search for a file at the path PATH/foo/bar and serve up its contents. It is powered by the Python http.server class.

However, the server specially handles WTML files. If a request is received for an HTTP path ending in the form .../{basename}.wtml, and there exists a file on disk named .../{basename}_rel.wtml, special logic is triggered. The WTML content will be loaded and reprocessed so that any relative URLs in the content will be converted to absolute URLs appropriate for the HTTP server. This supports the recommended workflow where you prepare WTML content in a file containing relative URLs, then use wwtdatatool wtml rewrite-urls to create files with the needed absolute URLs just before publishing them.

Furthermore, the server also supplies globally open CORS headers so that the data it returns are not blocked from the WWT web client by web browser security protocols.

When the server starts up, it will print out its base URL and the URLs of any “relative” WTML files it detects in its root directory. These URLs can be copy-pasted into the WWT web client for easy prototyping.

Be aware that your web browser will cache content between multiple invocations of the wwtdatatool serve command even if the data that you are serving have changed. You may need to force your browser to reload new content to get updated data. A quick way to avoid this issue is to launch the server using a new --port number.

The --heartbeat option causes the server to print out a line of text every second while it is running. This can be useful when launching the server over SSH, because if the connection is dropped, the printout will fail and cause the server to exit. It is unlikely that you will ever need to specify this option explicitly.

See Also