SVPortal Installation: Overview

Overview

SVPortal is a fairly complex system – and there are a lot of steps to getting it working. Unlike projects such as “Dreamgrid” – it isnt a distribution of OpenSim that comes with a web interface – it is JUST a web interface. As such it isn’t really feasable to build an installer as everyone’s distribution will be different. However, a number of people have had issues installing it (even myself have had to double check things when installing it on multiple grids), so I am doing my best to provide some extra guidance.

I plan here to provide a “multi-step” approach to getting SVPortal working in stages from initial login to configuration of your grid as well as detailing some items that are outside of the scope of the portal install – but the portal MAY require.

Assumptions

Like a lot of software, SVPortal has some pre-requisites. Some have work arounds if you don’t have them – and some are hard requirements. There are also assumptions that are not hard rules – but you will have to work out for yourself as they are outside of the scope of this guidance.

SVPortal was written on Debian 13 with PHP8.4-fpm, Nginx and MariaDB. I have also confugured it for a friend on Apache2 and also know at least one person who has configured it for Apache2 AND MySQL. There ARE differences between MariaDB and MySQL which makes it generally easier to confgure for MariaDB. If you have the choice – I would definately recommend Debian 12, Nginx and MariaDB.

I WILL be including a sample config for Apache2 (your milage may vary), and hopefully some helpful guidance about MySQL – you WILL need to configure the pre-requisite software using the package manager on your Linux distribution (please note that SVPortal is designed for Linux only. It MAY be possible to reconfigure it for Windows but there will be many issues and I can provide no assistance with this).

Prerequisites:

  • PHP 8.3 or 8.4 with the following extensions:
    • pdo_mysql — all database access (db.php and everywhere it’s included)
    • mbstring — multi-byte string handling; missing this produces Fatal error: Uncaught Error: Call to undefined function mb_substr() (or mb_strlen(), etc.) rather than a friendlier warning
    • curl — outbound HTTP to ROBUST, RemoteAdmin, hypergrid destinations, and jsonSimStats
    • imagick (php-imagick) — JPEG2000 → PNG map tile conversion, and resizing uploaded profile/region/event/link images
    • simplexml — parsing ROBUST/hypergrid XML responses; missing this produces Fatal error: Uncaught Error: Call to undefined function simplexml_load_string()

On Debian/Ubuntu, one line covers all of the above for PHP 8.4 (adjust the version suffix to match your installed PHP):

sudo apt install php8.4-mysql php8.4-mbstring php8.4-curl php8.4-imagick php8.4-fileinfo php8.4-xml

(php8.4-xml provides simplexml, dom, and a few other XML-related extensions bundled together on Debian/Ubuntu — there’s no separate php8.4-simplexml package.)

fileinfo, simplexml, ctype, json, and session all ship enabled by default on a normal distro PHP build and are rarely worth a second thought — but a minimal/hardened install, a manually-compiled PHP, or some slimmed-down container base images can omit any of them, and the resulting fatal errors point at the calling code, not the missing extension, so they’re easy to misdiagnose. Run php -m and check the extension you need appears in the list if anything on this page throws an “undefined function” fatal.

  • MariaDB (shared with your OpenSim/ROBUST database, or separate) — MySQL also works but expect some collation/charset differences from what’s documented here, which assumes MariaDB defaults.
  • Nginx (or Apache — Nginx assumed throughout)
  • A working OpenSimulator grid with ROBUST running
  • PHPMailer is bundled in includes/phpmailer/ — no Composer needed
  • HTTPS — see below

HTTPS Requirement

SVPortal requires HTTPS and will not function correctly over plain HTTP.

Session cookies are set with the Secure flag (see includes/auth.php, session_start_secure()), which instructs the browser to withhold the cookie on any non-HTTPS connection. Without HTTPS:

  • Login will appear to fail at the CSRF check, even with correct credentials
  • Sessions will not persist between page loads
  • Users will be redirected back to the login page in a loop

This is a deliberate security default, not a bug. A portal that handles account passwords should not run over an unencrypted connection.

Before installing, make sure you have:

  • A domain or subdomain pointed at your server
  • A valid TLS certificate (e.g. via Let’s Encrypt / certbot)
  • Your web server (Nginx/Apache) configured to serve the portal over HTTPS

If you’re testing on a local/LAN-only box with no public domain, a self-signed certificate is sufficient — the browser will show a trust warning you can accept, but the connection will still be HTTPS.

Modifying the code to remove the Secure cookie flag in order to run over HTTP is possible under the Apache 2.0 license, but is unsupported. Running the portal without HTTPS exposes login credentials and session tokens to interception on the network.

Why does this differ from OpenSim itself? OpenSim’s own login/viewer protocol is largely unencrypted by design, and that’s a much harder problem to fix than it sounds. It would require a viewer build that enforces HTTPS, cooperation across every independently-run grid, and — critically — would break Hypergrid travel, since HG depends on interoperating with other grids you have no control over and can never guarantee will make the same change. Realistically, that fix is never coming hypergrid-wide.

The portal is different: it’s a single web application under your control, serving a browser, where HTTPS is the modern baseline and free certificates make it a low-effort fix with no interoperability dependencies. Leaving the portal on HTTP because OpenSim itself is HTTP would mean leaving an easy door unlocked because a much harder one exists elsewhere.

Scroll to Top