Panoramax streetviewing

Setting up and running a self-hosted Panoramax streetview instance is fairly straightforward.

1. Panoramax API and Website

Discussed elsewhere are essential ingredients for effective field-view imaging, namely:

  • the accurate geotagging of images using the new Galileo worldwide and free-of-charge HAS correction service (see Implementation Note);
  • a self-hosted Panoramax "streetview" API inorporated into web maps to manage and display field and trail views and to allow accurately geotagged images captured using a smartphone to be uploaded (see Implementation Note).

Discussed here is the setting up of the Panoramax API and a Panoramax map and photo viewer that are incorporated into a web mapping application.

For a fully updated Ubuntu 22.04 system, installing the Panoramax API and Website are straightforward. Be aware that the default versions for Panoramax git clones are development versions (git clone https://gitlab.com/panoramax/server/api.git; git clone https://gitlab.com/panoramax/server/website.git).

Panoramax requires a PostgreSQL data base version 12 or greater and PostGIS extension 3.4+. Currently (March 2025), Postgres version 14 and PostGIS extension (version 3.5.2) can be installed using standard terminal commands:

  • sudo apt install postgres
  • sudo apt install postgresql-12-postgis-3

2. Panoramax API

For a Panoramax API, the database setup is standard. For the API, a virtual enviroment is needed for the directory where the API clone is stored (in say /home/user/geovisio):

  • cd /home/user/geovisio
  • python3 -m venv .
  • source bin/activate

Dependencies are then installed:

  • pip install -e .

To start with Panoramax, it is probably best to use the built-in Flask server:

  • flask run

Flask requires a .env file in /home/user/geovisio. A suitable .env is:

FLASK_APP=geovisio

# optional FLASK_DEBUG=1

# optional FLASK_ENV=development

DB_URL=postgres://ertert:ertert@localhost:5432/geovisio

FS_URL=/home/ertert/geovisio/data

INFRA_NB_PROXIES=1

FLASK_RUN_HOST=0.0.0.0

API_WEBSITE_URL=false

FLASK_SESSION_COOKIE_DOMAIN=peterboswell.net

# optional FLASK_SESSION_COKKIE_NAME=panosession

FLASK_SESSION_COOKIE_HTTPONLY=false

FLASK_SESSION_COOKIE_SAMESITE=none

FLASK_SESSION_COOKIE_SECURE=true

OAUTH_PROVIDER=osm

OAUTH_CLIENT_ID=*********************

OAUTH_CLIENT_SECRET=***********************

FLASK_SECRET_KEY=**********************

# fine tuning

#GEOVISIO_IMAGE_TAG=latest

#API_FORCE_AUTH_ON_UPLOAD=false

#API_DEFAULT_COLLABORATIVE_METADATA_EDITING=false

#API_ENFORCE_TOS_ACCEPTANCE=false

#API_ACCEPT_DUPLICATE=false

#DEBUG_PICTURES_SKIP_FS_CHECKS_WITH_PUBLIC_URL=true

#API_PERMANENT_PICTURES_PUBLIC_URL=true

3. Panoramax website

Setting up a Panoramax website requires NodeJS (version >= 18.13.0) and npm. Following "git clone https://gitlab.com/panoramax/server/website.git" in say "/home/user/panoramax", run:

  • npm install

As described in the guidance, then create a .env settings file in "home/user/panoramax", which in our case is as follows for JuraMap trails at pano.peterboswell.net:

VITE_API_URL=https://pano.peterboswell.net/

VITE_INSTANCE_NAME=JuraMap

VITE_ENV=prod

VITE_TILES=https://www.juramap.org/tiles/pnorman.json

VITE_ZOOM=8

VITE_MAX_ZOOM=20

VITE_CENTER=6.16,46.45

VITE_TITLE=JuraMap

VITE_META_DESCRIPTION=Panoramax website

VITE_META_TITLE=Panoramax website

The website is built for production and then run at the Vite default port (5173):

  • npm run build
  • npm run start

The VITE_TILES setting is for a JSON file that has the JuraMap vector tiles configuration for a TileKiln Mapbox Vector Tiles server. This server uses the Street Spirit style, as discussed in an Implementation Note.

4. Web server setup

While most of API and website .env settings are discussed in the Panoramax settings documentation (with further details on the Flask website), some require more attention, especially settings related to the way the webserver is set up.

Installation guidance indicates that the Panoramax website and API should be on the same host. While this is probably the simplest arrangement, it is unclear it is a requirement.

In our case there is a single host at pano.peterboswell.net behind an Apache2 proxy webserver with the number of proxies INFRA_NB_PROXIES=1 .

The Panoramax Node-based website serves at http://192.168.1.105:5173 (the default server port given in vite.config.js) and the API at http://192.168.1.105:5000 (the Flask default port). Fot this two virtual host arrangement, the following virtual host configuration was used for the Apache2 .conf file (in the "sites-available" directory for secure "https" connections. The configuration is based on Apache ProxyPass-ing Multiple Locations and is probably not the ideal single-host solution.

<IfModule mod_ssl.c>

<VirtualHost *:443>

ServerName pano.peterboswell.net

RequestHeader set X-Forwarded-Proto "https"

Header set Access-Control-Allow-Origin "*"

SSLEngine on

SSLCertificateFile /etc/letsencrypt/live/osm.peterboswell.net-0001/fullchain.pem

SSLCertificateKeyFile /etc/letsencrypt/live/osm.peterboswell.net-0001/privkey.pem

Include /etc/letsencrypt/options-ssl-apache.conf

<Location />

ProxyPass http://192.168.1.105:5173/ retry=0

</Location>

<Location /api>

ProxyPreserveHost On

ProxyPass http://localhost:8444/api retry=0

</Location>

</VirtualHost>

</IfModule mod>

Listen 8444

<VirtualHost *:8444>

ServerName localhost

RequestHeader set X-Forwarded-Proto "https"

Header set Access-Control-Allow-Origin "*"

<Location /api>

ProxyPreserveHost On

ProxyPass http://192.168.1.105:5000/api retry=0

</Location>

</VirtualHost>

For the API .env settings file, the API_WEBSITE_URL is set to "false" but as one might expect it can also be set to "same-host".

5. OSM Rails Port

The Ruby on Rails application that powers the OpenStreetMap (OSM) website and API is used for user authentication ("OAUTH_PROVIDER=osm" in the geovisio .env). For a OSM Rails port user at osm.peterboswell.net, the "My Account" -> "My Client Applications" -> "OAuth 2 Applications" setting is:

  • Name: "Panoramax"
  • Redirect URIs: "https://pano.peterboswell.net/api/auth/redirect"
  • Confidential application: not ticked
  • Permissions: "Read user preferences" ticked

The Rails port provides OAUTH_CLIENT_ID (the identity provider) and OAUTH_CLIENT_SECRET (the OAuth client secret), as decribed in the Panoramax API settings guidance.

6. Background Picture Worker

The Panoramax background Picture Worker is needed in order to process uploaded pictures in the background. It is installed in the API directory. To run, a new terminal is needed with:

  • cd /home/ser/geovisio
  • source bin/activate
  • run flask picture-worker

10 April 2025; updated 26 July 2025

PeterBoswell.com