OpenSim Engine -- Readme

Overwiew:

OpenSim Engine is intended to run OpenSim based simulators. Its main goal is to be part of a more elaborated solution to deploy simulators and/or grids, but can be used as is to test and even run (very simple) configurations inside containers.

Features:

• Built upon the latest version of Mono
• Contains minimal tools to download and manipulate ZIP compressed binaries inside the container
• It runs OpenSim.exe onto a detachable console you can access the main screen, see status and use CLI.
• Allows both standalone sims/grids (e.g. OpenSim, DivaDistro), and also connect your sims to existing grids (e.g. OSGrid)

NOTE: The image does not provide simulator files, you have to download/uncompress it yourself.

Requirements:

• Docker Engine. See Docker Documentation for further instructions
• Uncompressed main simulator folder tree, accessible by Docker with write permissions

Basic Usage

Useful for tests, and also for running very simple configurations (e.g. standalone and/or default SQLite setup):

docker run \

-it --restart=<restart-policy> \

--name <container-name> \

-v </path-to-main-folder>:/opensim \

-p 9XXX[-9YYY]:9XXX[-9YYY]/tcp \

-p 9XXX[-9YYY]:9XXX[-9YYY]/udp \

adrianparilli/opensim-engine[:<label>]

Where:

• <restart-policy>: no on-failure[max-retries] unless-stopped or always (see Restart Policies for more info

• <container-name>: Name you want to give for this container

• </path-to-main-folder>: Absolute path to the main simulator folder tree (containing inside 'bin' and 'doc' directories)

• 9XXX[-9YYY]:9XXX[-9YYY]: Port [or ports range] mapped to this container from the host, in order to connect to simulator(s) from your viewer. Both tcp and udp are need to be declared apart.

• label: If even provisioned, will use a specific version of this image. It should not be needed.

Example:

docker run -it --name opensim-test -v /data/docker/opensim:/opensim -p 9000:9000/tcp -p 9000:9000/udp adrianparilli/opensim-engine

The image will be downloaded and when runs, you will get attached to OpenSim.exe's first run CLI, being able to see the output and send commands to the simulator (e.g. setup, etc.)

• Detach from the console by pressing Ctrl+P and Ctrl+Qor Ctrl+P+Q (Simulator will keep running in background)

• Attach to the container again: docker attach <container-name>

• Start, restart or stop the container: docker start|restart|stop <container-name> (NOTE: you must attach the console and send the shutdown command before stop or restart the container)

• Delete the container with docker rm <container-name>. Simulator files will be kept.

You should be able to access simulator's region (once configured) via the ip (or dns name) and port where the container it is running. Example: http://localhost:9000

Advanced Usage

This section is an ongoing work (commits are welcome!). By now, it's useful to mention that along with this image, you will be able to:

• Dump a clean simulator folder tree onto a Docker volume or directly inside the container, and mount just the files you need to manage
• Customize your entire settings firat, and dump either to a volume or inside the container, and run without mounts
• You can add more mount points to import/export files (e.g. terrains, OARs, IARs, etc.)
• You can connect to an existing DB server (e.g. MySQL) and this can be also another container
• You can use this image to build and deploy your own OpenSim Stack with Docker composer, Kubernetes, etc.

TO DO

• Create an entrypoint.sh to 'shutdown' the simulator gracefully.