Creates a new ORS instance object that operates on a Docker instance of
OpenRouteService. This R6 class is typically constructed by
ors_instance. ORSDocker requires Docker to be
installed on the system and accessible by the current user. If these
requirements cannot be met, consider using ORSJar or
ORSWar.
For technical details on the setup of local ORS instances, refer to the
Running with Docker documentation.
For details on how to use ORSDocker objects, refer to the installation
vignette:
vignette("ors-installation", package = "rors")Details
ORSDocker defines methods for all four steps in the ORS setup:
Extract: Download an extract and set it up for graph building.
Compose: Change docker settings that control how the service is set up.
Configuration: Change the way ORS computes routes.
Docker: Send commands to docker to control the ORS container.
Docker commands
Local ORS instances are built using Docker containers. Initializing
ORSLocal downloads a docker-compose.yml file that tells
Docker how to build an ORS container. The Docker backend is pulled as
a Docker image (see
Dockerhub).
rors communicates with Docker from within R to setup and manage ORS
containers.
On Unix systems, Docker requires superuser permissions. In Unix shells,
this is not problematic. However, R cannot communicate with Docker without
explicitly being granted superuser permissions or at least permissions to
access Docker. Thus, ORSLocal checks if the current user is the
superuser or if the current user has access to the Docker group. If not,
it aborts. For more details on how to manage Docker as a non-root user on
Linux, refer to the
Docker documentation.
Note that this procedure grants root-level privileges to a user and can
negatively impact your system's security.
Manual changes
ORSLocal provides a range of convenience methods to change the
setup of the ORS instance. All of these methods automatically read or write
their changes to disk. It is also possible to make direct changes to the
(parsed) configuration and compose files. In this case, reading and writing
also need to be done manually. To write changes to disk, run
$update(), e.g.:
ors$compose$parsed$services$`ors-app`$container_name <- "new-name-123"
ors$update()To read changes done manually to the files on disk, run
$update("self").
Configuration files
Contrary to what is written in the
ORS documentation,
ORSLocal does not search for a pre-defined configuration file.
Instead, it explicitly creates a configuration file in the runtime directory.
Configurations are passed using an .env file but changes to the
configuration file are done using a .yml file due to easier reading and
writing within R. Accordingly, changes made to the .env file are
overwritten when $update("fs") is called and cannot be read using
$update("self"). All manual changes should be made to the .yml file.
Alternative configuration files can be specified by modifying the
ORS_CONFIG_LOCATION option in the compose file:
ors$compose$parsed$services$`ors-app`$environment$ORS_CONFIG_LOCATION <- "ors-config.yml"
ors$update()Super classes
rors::ORSInstance -> rors::ORSLocal -> ORSDocker
Public fields
pathsList of relevant file paths for the ORS setup. Includes the top directory, compose file, config file, and extract file.
versionVersion of the local ORS backend
composeInformation of the compose file (
docker-compose.yml). The compose file holds various settings for the Docker setup. The most important settings are included in this field:ports: A 2×2 matrix with Docker portsname: Name of the Docker containermemory: List with memory information on total and free system memory as well as initial and max memory allocated to the Docker instance.image: Version of the ORS image."latest"refers to the latest stable version."nightly"refers to the devel version.parsed: Parsed compose file. When making changes to this object, make sure to run$update()to apply the changes. For details, refer to the official reference.
configInformation of the configuration file (
ors-config.yml). The config file holds various options about the ORS instance. This field gives details about:profiles: A named vector of active routing profiles
parsed: Parsed configuration file. When making changes to this obhect, make sure to run
$update()to apply the changes. For details, refer to the ORS reference.
extractInformation on the extract file. Contains the name and size of the selected extract file.
Methods
Inherited methods
rors::ORSInstance$get_status()rors::ORSInstance$get_url()rors::ORSInstance$is_mounted()rors::ORSInstance$is_ready()rors::ORSLocal$add_profiles()rors::ORSLocal$report()rors::ORSLocal$rm_extract()rors::ORSLocal$rm_profiles()rors::ORSLocal$set_endpoints()rors::ORSLocal$set_extract()rors::ORSLocal$update()
Method new()
Initialize the ORSDocker object.
Usage
ORSDocker$new(
dir = ".",
version = NULL,
overwrite = FALSE,
dry = FALSE,
verbose = TRUE,
prompts = interactive(),
...
)Arguments
dir[character]Custom OpenRouteService directory. If not specified, the compose file will be downloaded to the current working directory. If a directory called
"openrouteservice-{version}"is present, the download will be skipped. Ignored ifserveris notNULL.version[character]The OpenRouteService version to use. Can either be a version number (e.g. 8.1.1) or
"master". Defaults to the most recent supported version.overwrite[logical]Whether to overwrite the current OpenRouteService directory if it exists.
dry[logical]Whether to start a dry instance, i.e. initialize a docker instance without requiring docker. This allows you to manipulate config, compose file, and extract but does not allow you to interact with docker.
verbose[logical]Level of verbosity. If
TRUE, shows informative warnings and messages, spinners, progress bars and system notifications.prompts[logical]Whether to ask for permission throughout the setup. Defaults to
TRUEin interactive sessions....Not used.
Method purge()
Purge ORS instance, i.e. take down container, (optionally) delete image, delete ORS directory, and clean up R6 class.
This method can be useful for testing and writing reproducible
examples and can easily be used together with on.exit.
Method set_port()
Set a port for the localhost of the ORS container.
Arguments
port[numeric]/NULLPort to use for the container. Can be a vector of length 1 or 2. The first port is for the API, the second port is optionally for additional monitoring. If
NULL, assigns a random port usingrandomPort().
Method set_memory()
Set initial and max memory that the ORS container is allowed to use.
Arguments
init[numeric/NULL]Initial memory in gigabytes. This can change if more memory is needed. If not specified, uses
max. If both areNULL, estimates required memory.max[numeric/NULL]Maximum memory in gigabytes. The container is not allowed to use more memory than this value. If not specified, uses
init. If both areNULL, estimates required memory.
Method set_graphbuilding()
Graph building specifies whether routing graphs should be (re-)built. Turning graph building on enables new profiles to be built or the extract to be changed but significantly increases setup time. Turn this off if you are changing configuration options that do not alter routing graphs. Usually, you do not need to call this method yourself because it is called automatically when a new extract is set or when the setup is completed.
Method set_image()
Set version of the ORS Docker image. The version should be compatible with the compose version.
Method up()
Create the ORS docker container and set up the ORS backend on a local host.
Arguments
waitlogicalWhether to run a spinner and show a system notification when the setup is completed. If
FALSEreleases the console after the Docker container is created. You can then check the service status using$is_ready()....Additional flags passed to the
docker upcommand.
Details
The exact command run by $up() is:
docker compose -p [name] -f [compose file] up -d --no-build [...]
The -p flag allows docker to run multiple ORS containers and keep
them separate. It uses the service name defined in the compose file.
If not found, $up() builds the underlying OpenRouteService docker
image specified by version during the initialization of
ORSLocal.
Usually in detach mode (-d), docker returns terminal control back
to the user. By default, $up() blocks the console, checks for
errors and notifies the user when the service setup has finished. This
behavior can be suppresed by setting wait = FALSE. The service
status can then be checked using $is_ready() or
ors_ready(). Container logs can be accessed by typing
docker logs [name] in the terminal.
Method down()
Stop and remove the ORS docker container. Use this if you want to make changes to a running ORS setup such as changing the extract or selected profiles.
Method start()
Start the ORS docker container.
Method show_logs()
Show container logs as returned by docker logs. Useful for
debugging docker setups.
Method is_built()
Checks if the ORS container is built. You can control this state
using $up() and $down().
Method is_running()
Checks if the ORS container is running. You can control this state
using $start() and $stop(). Check $is_ready() to see
if the ORS setup succeeded.
Method is_init()
Checks if ORS is initialized. ORS is initialized if it was built
for the first time. An initialized ORS instance has a subdirectory
called "graphs" that contains built graphs for at least one
routing profile. $is_init() therefore checks for the
existence of at least one sub-directory of "graphs".
Examples
if (FALSE) { # \dontrun{
# Download ORS, start docker and jumpstart a default session
ors <- ors_instance(tempdir())
# Set a new extract file
ors$set_extract("Rutland")
# Allocate 100 MB of RAM
ors$set_ram(0.1)
# Add a routing profile
walking <- ors_profile("walking")
ors$add_profiles(walking)
# Set random port
ors$set_port()
# Change project name
ors$set_name("example-ors")
# Set up ORS
ors$up()
# If the setup fails or produces warnings, you can check
# using $show_logs()
ors$show_logs()
# Check if ORS container exists and is running
ors$is_built() # TRUE
ors$is_running() # TRUE
# Check if ORS is ready to use
ors$is_ready()
# You can stop and start a container
# This does not remove a container but only interrupts it
ors$stop()
ors$is_built() # TRUE
ors$is_running() # FALSE
ors$start()
# Take down container, e.g. to make configuration changes
# This removes a container so that you have to rebuild it
ors$down()
ors$is_built() # FALSE
ors$is_running() # FALSE
# Make changes to the configuration
ors$set_endpoints(matrix = list(maximum_routes = 1e+05)) # default is 2500
# Change default profile settings
default <- ors_profile(maximum_snapping_radius = -1)
ors$add_profiles(default)
# If we make manual changes to the configuration, we need to apply the
# changes explicitly
ors$config$parsed$ors$engine$profiles$car$elevation <- FALSE
ors$update() # writes the current object state to the disk
# If the compose or config files are changed on disk, the object can be
# refreshed
ors$update("self") # reads the disk state to the R object
bike <- ors_profile("bike-road")
ors$add_profiles(bike)
# Additionally, graphs are only re-built if we enable graph building.
# When changing the extract, this happens automatically, but we can also
# control graph building manually, e.g. for adding new profiles.
ors$set_graphbuilding(TRUE)
# Finally, start the container again to run the newly configured service
ors$up()
} # }