soup-bowl / opensimulator-docker

Image compilation code for OpenSimulator and derivatives

OpenSimulator

From the OpenSimulator site:

OpenSimulator is an open source multi-platform, multi-user 3D application server. It can be used to create a virtual environment (or world) which can be accessed through a variety of clients, on multiple protocols.

This unofficial Docker configuration aims to assist in setting the server up for testing and general purpose use.

This is still experimental - thar be bugs!

Usage

docker run -d --name opensim -p 9000:9000 -p 9000:9000/udp soupbowl/opensimulator:latest

You can change settings with the following optional environmental overrides:

• -e GRID_NAME=... to define the name of your grid.
• -e GRID_WELCOME=... to show a custom message on the login screen.
• -e REGION_NAME=... to define the Region name.
• -e ESTATE_NAME=... to define the Estate name.
• -e ESTATE_OWNER_NAME=... to set the estate owner name (and creates a login) - format of 'Firstname Lastname'.
• -e ESTATE_OWNER_PASSWORD=... to define a login password.
• -e ESTATE_OWNER_UUID=... for a custom UUID, if desired.
• -e ESTATE_OWNER_EMAIL=... to define the estate email address.
• -e DATABASE_ENGINE=... to change the database engine (sqlite and mysql support so far) - defaults to sqlite.
• -e MYSQL_SERVER=..., -e MYSQL_DATABASE=..., -e MYSQL_USER=..., -e MYSQL_PASSWORD=... if DATABASE_ENGINE is mysql.
• -e PHYSICS_ENGINE=... to change the physics engine. Default is BulletSim with others being OpenDynamicsEngine, ubODE and basicphysics.

Once the server is running, you should be able to connect to it on localhost:9000. In Firestorm Viewer, you can go to Preferences, then Opensim, then under add new grid put localhost:9000 and you can then login.

If you don't define otherwise in the environments or a custom configuration, the login username is Foo bar and the password is password.

Custom Configurations

The environment list is not inclusive to the incredible range of options that OpenSimulator can be configured, and just covers a subset of the most popular settings. If you specify your own custom configuration file, it will be used instead of the image-generated configuration (you can define it as readonly (:ro) for assurance).

The working directory is /opt/opensim/bin/, so for example overriding OpenSim.ini would be "/path/to/local/OpenSim.ini:/opt/opensim/bin/OpenSim.ini:ro" (example).

SQLite Persistence

Outside of configurations, pretty much everything OpenSimulator does is stored in your chosen database provider. If you choose to leave the default on (sqlite), then your installation will not persist if you remove your container.

To aid the use of SQLite mode with persistent data, the default configuration has been modified to create the database directories into a dedicated directory (/opt/opensim/bin/sqlite-database). The following command will allow you to run a persistent SQLite setup.

(Note that if you use a custom SQLiteStandalone.ini file, this will not happen).

docker run -d --name opensim -p 9000:9000 -p 9000:9000/udp -v /path/on/your/system:/opt/opensim/bin/sqlite-database  soupbowl/opensimulator:latest

Limitations

Running Server Admin Commands

At current, there doesn't appear to be an implemented and/or documented approach to managing the server from outside the active TTY, and running docker attach opensim seems to produce a blank prompt. You can exec into the container or edit the bound configuration script and restart the server to make changes, but in some server instances you might need to intercept the prompt.

Until a better solution is made, you can get crafty with screen to get access to the current prompt in terminal, with the caveat that logging will no longer work.

You can achieve this with a Dockerfile like so:

FROM soupbowl/opensimulator:latest
CMD [ "screen", "-S", "OpenSim", "-D", "-m", "mono",  "./OpenSim.exe" ]

With a container running the above Dockerfile, you can access a controllable OpenSimulator administration prompt by running:

docker exec -it <container name> screen -r -d OpenSim

You can leave the screen session by pressing ctrl + a then d.

Physics in ARM

Each image has an ARM64 architecture build. Your mileage may vary with these as the server environment was not designed for use outside x86_64.

Currently, Physics environments do not appear to be natively supported, and running a server with BulletSim or OpenDynamicsEngine (ODE) will cause a fatal exception. You unfortunately currently have to run the server without physics. This can be achieved by setting the environment -e PHYSICS_ENGINE=basicphysics, or with the following OpenSim configuration adjustment:

[Startup]
   physics = basicphysics

Alternatively, a suitable drop-in library in lib64/libBulletSim-aarch64.so for BulletSim Physics could work, but may be unsupported.

I'm keen to support ARM architecture to the bounds of OpenSimulator. If you have any experience on this, please reach out to me.

Examples

See this repository for some example usages of this image.

Variants

Variant names are listed in Dockerhub format. They are also available from the GitHub Registry, replacing soupbowl/opensimulator with ghcr.io/soup-bowl/opensimulator-docker.

soupbowl/opensimulator:latest

The latest OpenSimulator image build using mono:latest as the build reference.

soupbowl/opensimulator:alpine-beta

A bleeding edge variant using Alpine as the build image with Mono dependency added. Mono is currently not in the stable packages build, so this image is considered unstable. Progress can be tracked on the #1 ticket.

soupbowl/opensimulator:source

Gets the latest available code from the OpenSimulator repoistory, and constructs a bleeding edge container. Configuration is not different, but this is compiled from source and should be treated as highly unstable.

These are compiled to use the official .NET root image, instead of the Mono Framework.

Source Code

The source code of the Docker image is found on the GitHub repository. You can find the OpenSimulator server software source code on their website.

opensimulator-docker's Issues

Alpine beta build

OpenSimulator Alpine Test

This is a test of the OpenSimulator Docker image running on an Alpine base.

Code | Container

As of commit 472637a, a 'latest' build is 883 MB, whereas the 'alpine' build is 398 MB!

For Graduation

Pass Verification

• Able to build successfully.
• Able to run successfully like or close to the main build.
• Does not depend on beta/alpha packages.

Steps for Pass

• Mono library leaves testing on the Alpine package registry.
• Fatal error occurs when SQLite engine is used.
  • MySQL engine works fine.

Supplied StandaloneCommon replaced with Docker Default

Experienced on source, but likely impacts all.

My StandaloneCommon.ini is replaced by the generic variant when starting up. I've bound it to read only, and it hits an error in the entrypoint. It appears to be due to a fault here.

opensimulator-docker/build/latest/docker-entrypoint.sh

Line 26 in ed012a8

if [ ! -e config-include/StandaloneCommon.ini ] || [ ! -e config-include/GridCommon.ini ]; then

0.9.3.0 Source Build Test

Source Build Test

This test is building the OpenSimulator code from source. 0.9.3.0 onwards is using Dotnet Core, which means I've been able to switch to the Dotnet Runtime container instead of Mono.

Code | Container

For Graduation

Graduation is blocked on this build since this is building edge, and so working on code that is not designed for production use. This is being used for future-proofing the container against the 0.9.3.0 release.

If you build the container from source, ensure to do a full rebuild to get the latest core code.