Public | Automated Build

Last pushed: 2 years ago
Short Description
A container for serving Cesium.js applications and custom generated terrain tilesets
Full Description

Cesium Terrain Server

This provides a Docker container for serving Cesium.js
client side assets in conjunction with custom terrain tilesets using
Cesium Terrain Server.

Within the container an instance of the Apache web server serves up the relevant
server side assets provided by Cesium.js. Apache also reverse proxies HTTP
requests to /tilesets/terrain to an instance of Cesium Terrain Server for
serving up terrain data. This combination allows for easy testing of custom
terrain tilesets as well as providing a base for developing Cesium applications.

Usage

docker run -p 8080:80 -v /data/docker/tilesets/terrain:/data/tilesets/terrain \
    geodata/cesium-terrain-server

Note that if the /data/tilesets/terrain directory is not present on the
container the terrain server will fail to run, as this is where it expects to
find subdirectories representing terrain tilesets.

Running the previous command will serve up the Cesium resources on
http://localhost:8080/. For instance you will be able to access the Cesium
Hello World application at http://localhost:8080/Apps/HelloWorld.html. Apache
runs on port 80 on the container, with the Cesium Terrain Server being exposed
on port 8000.

The only change in the container to the stock Cesium.js download is the addition
of a top level index.html (this will be the resource returned by
http://localhost:8080/). index.html is a very minimally modified version of
Apps/HelloWorld.html provided by Cesium which additionally loads terrain
pointed to by the the url /tilesets/terrain/test. In the above example this
requires the host directory /data/docker/tilesets/terrain/test to contain a
terrain tileset, which will in turn expose the tileset to
/data/tilesets/terrain/test in the container.

Logging

All requests to the apache server are logged to
/var/log/apache2/other_vhosts_access.log. All output from the terrain server
is logged under /var/log/terrain-server. This log is managed by
svlogd.

Creating and serving tilesets

This container has been designed to be work with the
Cesium Terrain Builder
docker image to simplify creating and viewing terrain tilesets. Assume you have
the following folder structure available on your host system:

/data/docker/
├── rasters
│   └── DEM.tif
└── tilesets
    └── terrain

where /data/docker/rasters/DEM.tif contains the height data in GeoTiff format
that you would like to view in Cesium.

First you would use the ctb-tile command to create the terrain tileset:

docker run -v /data/docker:/data homme/cesium-terrain-builder \
    ctb-tile --output-dir /data/tilesets/terrain/test /data/rasters/DEM.tif

Then you would serve up the terrain data using Cesium as per the general usage
instructions above:

docker run -p 8080:80 -v /data/docker/tilesets/terrain:/data/tilesets/terrain \
    geodata/cesium-terrain-server

The terrain data should now be visible at http://localhost:8080/.

Caching tiles with Memcached

The terrain server running within the container can be configured to use a
memcache server to cache tileset data and increase performance. This is done by
either specifying a memcached container to link to or setting the MEMCACHED
environment variable.

Linking

Any container running memcached on port 11211 and linked with the alias
memcached will be used. E.g. assume the following memcached container is
running:

docker run --name memcache -d memcached

This can then be used by a terrain server image:

docker run --name terrain -d --link memcache:memcached geodata/cesium-terrain-server

MEMCACHED Environment variable

A memcached server that is not linked can be still used by setting the container
MEMCACHED environment variable to point to the memcached network address e.g.

docker run --name terrain -d --env MEMCACHED=memcache.me.org:11211 geodata/cesium-terrain-server

Linking takes precedence over setting MEMCACHED.

Developing Cesium applications

You can use the container as a base for developing bespoke Cesium applications
with custom terrain data. General workflow would be to create tilesets as
described in the previous section. You would then need to edit
/var/www/cesium/index.html in the container to suit your taste. You may also
want to customise the terrain server itself. See the
Cesium Terrain Server
project repository for further details on this.

Note that the terrain server will serve up any terrain tilesets present as
subdirectories of /data/tilesets/terrain in the container. You are therefore
not limited to the default test directory, and you can serve multiple terrain
tilesets at once. To make tilesets other than the default test available to
the Cesium client, however, you will need to edit or replace the index.html
file to appropriately reference these alternative tileset resources.

You can edit /var/www/cesium/index.html directly in the container, but the
recommended approach would be to use the container as a base for your own
application. To do this:

  • Clone or download the
    Cesium Terrain Server
    repository.
  • Edit docker/root-fs/var/www/cesium/index.html to suit.
  • Build the container defined by the context in docker/.

The recommended way to build the container on GNU/Linux distributions is to take
advantage of the Makefile in the project root: running make docker-local
will create a docker image tagged geodata/cesium-terrain-server:local. This
image, when run with a bind mount to the project root directory, is very handy
for developing and testing.

Issues and Contributing

Please report bugs or issues using the
GitHub issue tracker.

Code and documentation contributions are very welcome, either as GitHub pull
requests or patches.

License

The Apache License, Version 2.0.

Contact

Homme Zwaagstra hrz@geodata.soton.ac.uk

Docker Pull Command
Owner
geodata
Source Repository