# OpenSim Engine

## 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](https://docs.docker.com/get-docker/) 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](https://docs.docker.com/engine/reference/commandline/run/#restart-policies---restart) 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. Default is `latest`

### 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+Q`or `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 `entrypoint.sh` to shut down the simulator gracefully.