Starting up PraxisMapper for the first time has been simplified down as much as possible. This covers the shortest, simplest path to get a server running against Release 8 of PraxisMapper. Previous versions required using the bootstrapping app, Larry, with some commands that could be tailored to specific needs. That option remains, but is no longer necessary for a basic environment to start messing around.

This tutorial assumes you want a fairly standard server: a Windows system that draws accurate map tiles to be displayed to a user, with overlays for game mode information.

In addition, PraxisMapper handles all sorts of common, complicated stuff you'll probably want to do already, and Hypothesis is an app full of example games already built to run against PraxisMapper. Once initial setup is done, you'll be vastly farther ahead of trying to start from scratch, and won't be relying on any external services to stay running for your game.

Part 1: Requirements

On the computer you'll use to test this, you will need to install the following:

NET 7 (Use the NET Runtime at a minimum. Grab the ASP.NET Hosting Bundle if you expect to upgrade to IIS in the future on the dev machine)

PraxisMapper (This guide is written against Release 8). I suggest extracting the files to C:\Praxis for this example.

Part 2: Map Data

You will need to go to geofabrik.de and look through the sub-regions until you find the smallest file for the gameplay area you want to cover. Whichever file you choose, it needs to be in the .osm.pbf format. For testing purposes, I suggest you find a US State file, then search for your county, city, or other sub-division on openstreetmap.org and write down the ID for it. Other countries may use different terminology, but the same rules should apply.

This guide will use Los Angeles County, California (396479) for example purposes. For that we'll navigate to North America\US\California\socal-latest.osm.pbf

Save the .osm.pbf file into C:\Praxis

Part 3: Config Files

Open up C:\Praxis\appsettings.json in a text editor. Find the 'useRelationForBounds' entry and set it to the ID you looked up in Part 2. All of the other settings should be fine on their default.

Part 4: Running Web Server

Run PraxisMapper.exe. If you haven't done this before, it will download and install LocalDB, then create and populate the database. This will take a few minutes, depending on the size of the PBF file. (In my testing, Los Angeles County takes about half an hour to process this way.) After that, it will open up the web server and listen for HTTP calls on port 5000.

You can test that this is running by going to localhost:5000/Server/Test and seeing "OK" as the reply. After that, we can visit localhost:5000/Slippy and get a typical web-view map, where you can zoom in and out and scroll by dragging the map around. This view starts in the geographic center of the server's bounds, so you may need to move around to find familiar map data. For this example, you'll need to zoom out and move up to find land. Once you zoom in and find some map data, you're done with initial setup!

Part 5: Advanced Steps

This guide on setting up a server for the first time is done. There is no way to do this any quicker or easier. There are advanced options that can be used as well that you may want to think about, though none are required:

• Plan on running this a few times? Look into using Larry to process the .pbf file into .geomdata files per block. They can be imported in bulk faster than saving each block directly to the database like PraxisMapper does.

• Install MariaDB and update the config values on PraxisMapper and Larry to match. You'll be able to get around the limits of LocalDB, and be able to directly view and edit data through the HeidiSQL app that comes with it.

  • Big fan of the Microsoft software stack? You can use SQL Server instead. LocalDB IS just a config-free, user-space-only version of SQL Server Express, so if storage is an issue you'll want to move into a paid version.

• Planning on going pro with this? You may want to set up PraxisMapper inside IIS or another full-feature web server, which can be done like any other ASP.NET CORE application. If you stick with LocalDB, you'll need to make sure your AppPool runs as the same user that did the initial LocalDB setup.

• Get one of the existing game plugins and drop into your C:\Praxis\plugins folder. Grab the appropriate app and point it at your server.

Troubleshooting and Gotchas

• Getting an error like "Could not allocate space for object in database because the 'PRIMARY' filegroup is full"? You're hitting limits in SQLLocalDB and the resulting DB is over 10GB in size. Maybe you forgot to punch in the Relation ID in appsettings.json to narrow the scope of your server? Maybe you'll need to install MariaDB and configure PraxisMapper for it to handle the area you want to cover? Maybe processed OSM data for Los Angeles County exceeded 10GB after I wrote this guide? For this last case, the short fix is to swap to using the Los Angeles CITY bounds (207359) instead while you follow this guide, which takes about 20 minutes to process intead of 30.

• On a coastline and the ocean isn't being drawn in as expected? This is a side-effect of how OpenStreetMap handles oceans (It doesn't, basically). There are OSM coastline shapefiles available that Larry can process with the '-processCoastlines:water_polygons.shp' argument (or whatever you've named the .shp file), and you can import the results of that to draw in the oceans as expected. Those files are available here, and take up another 1-2GB of storage in your database. Here's an example of what you might see without the coastlines import:

  

Recall that it'll be additional storage space to fill in the ocean polygons, and you may not have that if you're using LocalDB and/or covering a particularly dense.