Various configuration files and setups for running OpenSimulator in Docker containers. The model builds a Docker image of OpenSimulator and then that image can be run with different configurations (standalone, grid, ...).
There was a presentation on this project at the OpenSimulator Community Conference 2019 that is available at OSCC19 Dockerizing OpenSimulator .
This is organized into building images and having configs for those images. The model is for one to build a Docker image with one of the OpenSimulator images in it and, at runtime, choose one of the embedded configurations to run it with. The OpenSimulator "image" is a built version of the source code and the "config" is the collection of INI files that are used to run it.
Two images are currently present: image-opensim which is a built of the
straight OpenSimulator 'master' branch,
and image-opensim-herbal3d which is OpenSimulator built with
the Herbal3d addon modules.
(Since I'm the Herbal3d main developer, this is how I test it.)
The Docker images are run using docker-compose to set up ports
and environment. Additionally, if a database server is needed,
that is also started and linked to the OpenSimulator instance.
MariaDB is used for the external SQL server.
As an example, to create an image of standard OpenSimulator and sets it up to run with a separate SQL database server to store data:
# Get these configuration files
cd
git clone https://github.com/Misterblue/opensim-docker.git
# Use the regular OpenSimulator with a standalone setup for this example:
cd opensim-docker/image-opensim
# Select the runtime configuration to use
export CONFIG_NAME=standalone-sql
# Edit os-secrets with login and database passwords
cd config/$CONFIG_NAME
# Edit "config/$CONFIG_NAME/os-secrets"
# If you want to keep things hidden, one can follow the instructions in os-secrets
# and encrypt os-secrets.
# Do any additional OpenSimulator configuration
# Edit 'config/$CONFIG_NAME/Regions/Regions.ini for region location
# Edit 'config/$CONFIG_NAME/misc.ini for other settings
# Edit 'config'$CONFIG_NAME/config-include/*.ini for grid connections
# Build OpenSimulator image
cd
cd opensim-docker/image-opensim
./build-opensim.sh
# Run the composed container set
CONFIG_NAME=standalone-mysql CONFIGKEY=secretPassword EXTERNAL_HOSTNAME=whateverTheHostnameIs ./run-standalone.sh
Notice that nearly all of the configuration of the running OpenSimulator
is done in the misc.ini file. All the configurations from the OpenSimulator
sources and the defaults that are in the source repository and these values
are overlayed by the last INI file which, in this case, is misc.ini.
By default, the Docker image that is run is the local built image. Optionally, one can use an image in a remote repository. Most people will build their own local image, though, as you will probably want to be using the latest OpenSimulator sources and thus require a fresh build.
The Dockerfiles setup the image with a few scripts to configure and start
OpenSimulator, periodically check for crashes, copy crash'ed log files,
and restart the simulator if it's not running.
Which configuration is used is specified by environment variables which must be set. The environment variables are:
-- CONFIG_NAME: the configuration to use (like "standalone" or "standalone-sql") -- CONFIGKEY: (optional) the password for extracting secrets in .crypt files -- EXTERNAL_HOSTNAME: the external network address for the simulator
The container starts the script /home/opensim/bootOpenSim.sh which runs
configuration scripts and then starts the simulator. There are other scripts
to do setup (firstTimeSetup.sh), capture crash information (captureCrash.sh),
or to start the simulator (run.opensim.sh).
The simulator runs as the created user account opensim for a little security.
The README files in the sub-directories contain instructions on setup
of these configuration files and building the images. There are scripts
for building the images (e.g., build-opensim.sh) and then running
the images with docker-compose (e.g., run-opensim.sh).
The biggest problem with Docker'izing OpenSimulator is the configuration file setup -- OpenSimulator has manual setup and configuration files scattered around. Add to that the radically different runtime setups possible (standalone with or without databases and grid hosting or grid connected) and a generalized, containerable configuration becomes difficult.
The solution used here is to mostly null out the configuration that comes with the base OpenSimulator sources and to replace them with copies in a separate directory. In general,
OpenSimDefaults.iniis used unchanged from the sourcesOpenSim.ini.exampleis copied toOpenSim.iniwith no changes- the files in
config-includeare emptied so they don't do anything when included by any script - configuration uses the feature that OpenSimulator reads all the INI files in
bin/config
The latter feature is used by config/setup.sh which copies a $CONFIG_NAME/Include.ini
into bin/config and that is what includes all the necessary configuration files in
the $CONFIG_NAME directory.
docker-compose mounts the container's bin/config directory as the config/
directory so all of the configuration of the
The latter feature means that one could either use the configuration samples included
with these sources or one could mount a volume on top of /home/opensim/opensim/bin/config
and completely replace all the configuration files. This enables the flexibility
of either building configuration within the Docker image or supplying one's
own configuration at runtime.
Once the Docker image is built, it can be run with a command like:
CONFIG_NAME=standalone-mysql CONFIGKEY=secretPassword EXTERNAL_HOSTNAME=whateverTheHostnameIs ./run-standalone.sh
Once started, a docker ps will show something like:
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 368b0137d30c opensim-opensim "/home/opensim/bootO…" 25 minutes ago Up 25 minutes 0.0.0.0:8002->8002/tcp, 0.0.0.0:8002->8002/udp, :::8002->8002/tcp, :::8002->8002/udp, 0.0.0.0:9000->9000/tcp, 0.0.0.0:9000->9000/udp, :::9000->9000/tcp, :::9000->9000/udp, 0.0.0.0:9010->9010/tcp, 0.0.0.0:9010->9010/udp, :::9010->9010/tcp, :::9010->9010/udp opensim-standalone_opensim_1 6637e8548a0f mariadb:latest "docker-entrypoint.s…" 25 minutes ago Up 25 minutes 3306/tcp opensim-standalone_dbservice_1 $
Which shows the two containers started for the simulator and the database. (There will be only one container if using the SqlLite database.)
The number under "CONTAINER ID" is and ID one uses to address the container. The command
docker logs ID
will show the console output when starting the container. The configuration scripts output messages that will help finding any problems.
To get a console on the OpenSimulator container, the command is
docker exec -it ID /bin/bash
(that is, execute and interactive command on the container). This will open a Bash shell on the container.
OpenSimulator is started with Screen. Once running the Bash shell on the container, the command:
screen -r OpenSimScreen
will connect you to the OpenSimulator console. TO EXIT SCREEN the command is cntl-A followed by cntl-D.