# OpenSimulator on Docker

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](https://conference.opensimulator.org/2019/)
that is available at
[OSCC19 Dockerizing OpenSimulator](https://www.youtube.com/watch?v=-EnTepHqLA4) .

This is organized into building *images* and having *config*s 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.

## Image Operation

The `Dockerfile`s 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`).

## OpenSimulator Configuration

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.ini` is used unchanged from  the sources
- `OpenSim.ini.example` is copied to `OpenSim.ini` with no changes
- the files in `config-include` are 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.

## Running the Docker Image

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:

<pre>
$ 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
$ 
</pre>

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`.

[OpenSimulator]: https://opensimulator.org
[Docker]: https://www.docker.com
[Herbal3d]: https://www.herbal3d.org
[MariaDB]: https://mariadb.org/