Skip to main content

Testing GIPS locally with Simple Web Server

Why a local web server is needed​

GIPS has to be served over http://, not opened by double-clicking index.html. Browsers block most of what a web app does from a file:// URL: fetching JSON, tiles or PMTiles with fetch(), loading ES modules, and byte-range requests all fail silently or with CORS errors. Simple Web Server is a free Windows/macOS app that serves a folder over HTTP with no command line, which makes it the easiest way to test a GIPS Lite or Pro deployment on your own machine before handing it to IT.

These steps assume you have a deployment folder on disk: the folder written by Export GIPS Lite... or Export GIPS Pro..., which contains index.html plus its JS, CSS and data files (see Files in a deployment).

1. Install Simple Web Server​

  1. Go to the download page and get the installer for your OS (Windows or macOS). On a Mac you can also install it from the Mac App Store.
  2. Run the installer and open the app. No account or configuration is needed; the main window is just a list of servers (empty at first).
  3. Optional: on Windows, if SmartScreen warns about an unrecognized app, choose More info → Run anyway. The app is open source under the MIT license.

2. Create a server for the GIPS folder​

  1. Click New Server (the + button) in the main window.
  2. Folder path: click the folder picker and select the deployment folder (the one that contains index.html).
  3. Port: leave the default 8080 unless something else is already using it. The site will be at http://localhost:8080.
  4. Leave Automatically show index.html on (it is on by default), so http://localhost:8080 opens GIPS directly.
  5. Toggle the server on (the switch at the top of the server panel). The status turns green and the address appears next to it.

Make sure that the following Basic options are enabled:

  • Automatically show index.html
  • Exclude .html extension

The rest should be disabled.

Disable all of the Advanced options.

The server keeps running in the background even if you close the window, so you only need to set this up once. Next time, just open the app and toggle it on.

Not a production server

Simple Web Server is for testing only. It does not send the Cache-Control, ETag or Content-Security-Policy headers a real deployment needs — see the IT Guide for those.

3. Open and test GIPS​

  1. Open a browser and go to http://localhost:<port> where port is the port that you configured the server to be on. GIPS should load the same way it does on the deployed site.
  2. Open the browser's developer tools (F12, or Cmd+Option+I on a Mac) and watch the Console and Network tabs while you click around. A clean console and all requests in the 200 range means the deployment is serving correctly.
  3. To test a new export, copy the new files over the same folder (or point the server at the new folder in its settings) and hard-refresh the page with Ctrl+Shift+R / Cmd+Shift+R so the browser does not use cached JS.
  4. When you are done, toggle the server off in the app. Leaving it on is harmless; it only listens on your own machine unless you enabled local network access.

Troubleshooting​

SymptomLikely causeFix
Browser shows a file listing instead of GIPSThe folder you picked is one level too high (no index.html in it)Point the server at the folder that directly contains index.html.
Blank page, console says a .js or .css file returned 404The build uses absolute paths (/assets/...) expecting to be served from the site root, or the folder is wrongServe the deployment folder itself as the root, not a parent folder.
Page loads but map data or tiles do not appear; console shows CORS errorsData is coming from another origin (a second local server, or a remote bucket that does not allow localhost)For a second local server, enable Set CORS headers on the server hosting the data. For a remote bucket, add http://localhost:8080 to its allowed origins or test with the production data URL.
Server will not start: port already in useAnother app (often a dev server) is on 8080Change the port to 8081 or similar and use that in the URL.
Old version keeps appearing after you copied in a new exportBrowser cacheHard-refresh (Ctrl+Shift+R / Cmd+Shift+R) or tick Disable cache in the Network tab of dev tools while it is open.
Colleague cannot reach http://<your-IP>:8080Local network access is off, or the firewall blocked itEnable Accessible on local network and allow the firewall prompt; both machines must be on the same network.

Sources: Simple Web Server, server options reference, Mac App Store listing.