gOSWI

Go (lang) OpenSimulator Web Interface

gOSWI (Go OpenSimulator Web Interface) is a Web-based, backend administration console for virtual world grids running the OpenSimulator software.

Note: if you don't know what OpenSimulator is, then very likely you won't need this package ever!

Note: Some knowledge of the Go programming language is definitely required; a working Go environment is an absolute necessity!

Quick-start installation

• Make sure you have a fairly recent version of the Go environment installed for your system; use your operating system's favourite package manager or follow the instructions

• Install the developer version of ImageMagick, preferably version 7, according to the GoGraphics imagick instructions

• Make sure you have a working, command-line C/C++ compiler installed on your system (e.g., clang, GCC, Roslyn, mingw, Xcode for macOS...); if you're on Unix or any of its variants, you should be good to go

• Run (under an unprivileged user) the following command on your local shell:

  export CGO_CFLAGS_ALLOW='-Xpreprocessor'
  go build github.com/GwynethLlewelyn/goswi
  

  If this is the first time compiling anything in Go, this step will populate your home directory with quite a lot of files (under ~/go), and the overall compilation may take some time to complete. The Go toolchain is notoriously silent, so you might wish to append a -v for some additional verbosity.

• If all went well, you should have an executable file called goswi on the same directory (possibly goswi.exe if you've attempted to compile it under Windows)

• Note that you can run it from the console, but it's much more likely that you wish to set it up as a proper service (running in the background); also note that goswi will need some directories to be present

• Now skip the next chapter and go straight to the Configuration section!

Purpose of this project

While OpenSimulator adds a lot of base functionality to pretty much run everything 'out of the box', historically, a handful of functions were deliberately left out of the 'core' system, and left to third-party modules in C#, or, through a few APIs (mostly using XML-RPC, but not all), delegated to external systems (thus allowing a distributed approach in terms of deployment of a 'whole' grid). Relatively simple things (such as the 'splash screen' — what is shown when you select a grid on Firestorm and other OpenSimulator-compatible viewers) as well as much complex ones (such as running the economy system) have been pushed out of the core code, for several reasons, including ideological/theological ones (i.e. the concept that OpenSimulator-based grids should not have an economy because the love of money is the root of all evil — defended both by extreme-left, atheist, progressive activists, as well as right-wing, conservative Christians), legal ones (running a virtual economy might be illegal in several jurisdictions, or at least require a special license to do so), and practical ones (the 'splash screen' is often used to convey information about the grid which may rely upon statistics processed 'outside' the core OpenSimulator code).

Another area that is underdeveloped is the management of local grid users. Although OpenSimulator includes some console commands to do some user management — basically, creating users, changing their passwords, or email addresses — which is more than enough for a small grid of close-knit developers and content creators, running a large grid, with hundreds of thousands of users, each being able to have multiple 'alts', belonging to different groups, etc. is far beyond the purpose of the 'simple' console commands. Similarly, OpenSimulator doesn't even come with tools to do estate management — although it's fully supported (newly created regions, for instance, must be assigned to an existing estate), the whole backoffice mechanisms to deal with them are left for third-party developers to do. You can always do everything manually, using phpMyAdmin and doing the changes directly on the database, but this approach, again, is just meaningful for managing a handful of estates.

Thus, since OpenSimulator's inception, several 'grid management solutions' have been around, many of which free and open-source. Some are merely plugins for larger content management systems (such as jOpensim for Joomla, Xoopensim for XOOPS, d4os for Drupal); others are standalone (see a 'complete' list on http://opensimulator.org/wiki/Webinterface); most, unfortunately, have stopped their development ages ago. This is especially true of PHP administration tools which relied on pre-PHP PDO functions to connect to the database; unfortunately, such functions have been deprecated and require a lot of time to rewrite... I tried to do that with Xoopensim, but after two weeks of making change after change, and stumbling over and over again on deprecated usage of old PHP functions, I gave up.

Therefore, this project was born — not in PHP, not in C# (which I hate with passion), but in Go — because it's easy to compile in pretty much everything out there (and I revere the creators of Go with all my heart!). If you're not really willing to learn how to do Go programming and/or basic installation, no worries, you will just need to get the appropriate binaries (once I compile them, of course).

Configuration

• Because Second Life® and OpenSimulator internally use JPEG2000 for all images (including raw map tiles), we have to convert those to browser-friendly images, which we'll do with ImageMagick 7 — so make sure you are correctly set up to use the Cgo-based ImageMagick wrapper:

  • Install ImageMagick according to https://github.com/gographics/imagick (choose version 7)
  • If you're on Ubuntu/Debian Linux, which are still mostly stuck with ImageMagick 6.9, you might be able to install all required dependencies from the Debian repositories. Take a peek at the GitHub action to compile the code to get a list of the fundamental packages that are needed. Note that GitHub, when running this action, will essentially start with a fresh, clean container, and has to install everything it needs; your mileage may vary (an 'unclean' environment might either not require so many things to be installed, or, worse, get blocked with some dependency conflicts)
  • Make sure that your particular version of ImageMagick supports JP2 (that's JPEG2000)
  • Don't forget to set export CGO_CFLAGS_ALLOW='-Xpreprocessor' in your shell.

  My apologies for having to resort to ImageMagick, but there is no native Go library to decode JPEG2000 images; believe me, I've tried a lot of alternatives (including several kinds of external applications/commands). Decoding JPEG2000 is immensely complex (even if the code to do so in C is open source) and way, way, way beyond my abilities as a programmer

• Copy config.sample.ini to config.ini and adjust for your system (namely, adding the DSN to connect to your database)

• To get a fully-functional map, adjust assets/js/leaflet-gridmap.js with your system's configuration

• Do not forget to set cookieStore to a randomly generated password!

• Note that by default gOSWI will try to load config.ini from the directory where you've got your sources (e.g. if you used go get -u github.com/GwynethLlewelyn/goswi, then the path will be set to ~/go/src/github.com/GwynethLlewelyn/goswi); the same applies to the static files under ./templates/, ./lib, and ./assets/ — no matter where you actually place the compiled binary. You can change that behaviour by changing the templatePath (which actually changes more than that) and passing the -config parameter directly to the compiled binary (or, at best, have the config.ini in the same directory as the executable)

• I had to move from session storage in cookies to a memory-based approach, simply because the session data stored in cookies was growing and growing until it blew the established 4K limit. Now, if the application is not running, all the stored session data is lost. I've been toying around the following possibilities:

  • Using either Redis/memcached as permanent KV storage for the session data; this, however, requires that people configure one of those servers, and I'd have to offer several possibilities: check if either Redis/memcached is running and call the appropriate library (but all would have to be compiled into the code — or offer a tag-based approach for compiling with one or the other option), and, if not, fall back to the memory store

  • Adapt Gin-Gonic to use the Gorilla FileSystem storage (Gin-Gonic sessions use Gorilla sessions underneath)

  • Adapt Gin-Gonic to use one of the embedded KV stores I'm already using for persisting data (e.g. the image cache)

  • Use browser-based local storage to replace cookies (which I wasn't originally aware of)

    I haven't still decided what I'll do...

Special notes for macOS using MacPorts

As of 2025, both ImageMagick versions 6 and 7 are in use, with developers undecided about which to use. MacPorts allows both to be deployed at the same time; the default is ImageMagick 6.9.x, while version 7 currently has its own package, ImageMagick7.

We're using version 3 of the Go Wrapper, so it requires ImageMagick 7 (unless this code gets tagged one day; see the note below).

MacPorts (like other package managers) will usually leave the tw