This provides a Docker container for running Cesium Terrain Server. It is capable of serving custom terrain tilesets with the option of also serving Cesium.js client side assets: it comes bundled with Cesium.js. This makes it a suitable platform for using in the development of Cesium.js web applications.
docker run -p 8080:8000 -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.
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/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.
A number of environment variables can be set on the container using docker run --env
which affect its behaviour:
-
Setting
SERVE_STATIC=0
will prevent the terrain server for serving up any of the static Cesium.js assets. Useful if you only want to serve terrain tilesets. -
Setting
WEB_DIR
to a directory will specify the directory from which to serve up the static assets. By default this is/var/www/cesium
. Note also settingSERVE_STATIC=0
will mean that no assets are served, no matter whereWEB_DIR
points to. -
Setting
BASE_TERRAIN_PATH
affects the base path under which terrain tiles are served. By default this is/tilesets
but can be set to e.g.BASE_TERRAIN_PATH=/tiles/terrain
. -
Setting
LOG_LEVEL
to one ofcrit
,err
,notice
,debug
will determine what is logged.LOG_LEVEL=debug
is useful when developing, especially checking what keys are being set in Memcached. -
Setting
LOG_REQUESTS=0
will prevent the logging of HTTP requests. -
Setting
MEMCACHED
enables caching tiles with Memcached. See the relevant section below for details.
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/.
The terrain server running within the container can be configured to use a memcache server to cache tileset data and increase performance. Note that the terrain server does not use the cache itself, it only populates for each request. The idea is that a reverse proxy attached to the memcache (such as Nginx) will first attempt to fulfil a request from the cache before falling back to the terrain server, which will then update the cache.
Caching is enabled by either specifying a memcached container to link to or
setting the MEMCACHED
environment variable.
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
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
.
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.
All output from the terrain server is logged under /var/log/terrain-server
.
This log is managed by svlogd.
Please report bugs or issues using the GitHub issue tracker.
Code and documentation contributions are very welcome, either as GitHub pull requests or patches.
The Apache License, Version 2.0.
Homme Zwaagstra [email protected]