Skip to content

A complete Panoramax deployment with OpenStreetMap authentication

Here is a simple example on how to host a Panoramax instance based on a simple docker compose, and using OSM OAuth2 so the users only need an OSM account to be able to upload pictures.

Tip

For a production grade deployment, you might need to adapt some things:

  • Tune PostgreSQL configuration to suit your needs, and at the very least backup it 💾.
  • Think about the storage of the pictures, see what disks you'll need, you'll likely need a lot of storage. And as the very least backup them 💾.
  • Maybe split the services between several hosts (pictures workers separate from HTTP API).
  • Add cache in Nginx to speed up some responses.
  • ...

Info

Some documentation on how to fine tune Panoramax API is available here.

As a requirement for this example, you'll need a Linux server (this should also work with other OS, but not tested here), with docker and docker compose installed.

Note

If you have the legacy docker-compose installed, you might need to replace the docker compose commands with docker-compose. Also note that, depending on you docker installation, you might need sudo rights to run docker commands.

Having nice https urls is mandatory to use the OAuth2 on OpenStreetMap, you'll also need a domain. You'll need a reverse proxy to handle tls, cf the Domain section.

Creating our OSM OAuth2 client

First, we'll configure our OSM OAuth2 client.

You can follow the documentation for this, here is a simple walkthrough.

Go to "My settings" > "OAuth 2 applications"

And register a new client, giving it a nice name, a redirect uri with https://{your_domain}/api/auth/redirect (like https://your.panoramax.org/api/auth/redirect) and the permission "Read user preferences". OSM OAuth2 client configration.

Make sure to save the client ID/secret given when registering the client, you'll need both of them in the configuration of the next section.

Running ⚙ docker compose

This tutorial uses the files in docker/full-osm-auth/docker-compose.yml, if it's not already done, you need to clone the git repository and go in the directory.

git clone https://gitlab.com/panoramax/server/api.git geovisio-api
cd geovisio-api/docker/full-osm-auth/

Configuration

Some key variables can be changed by providing a .env file or environment variables to docker compose. Feel free to also adapt the docker-compose.yml file if more changes are needed.

The easiest way is to copy the env.example file:

cp env.example .env

And change all the required configuration in the file.

At least you'll need to fill:

  • DOMAIN: The domain name you plan to expose the service on (the same you used in the redirect of the OAuth2 client).
  • OAUTH_CLIENT_SECRET: The OSM OAuth2 client secret.
  • FLASK_SECRET_KEY: A secret key to sign the cookies.
  • KEYCLOAK_ADMIN_PASSWORD: Not specified in the original text.
  • PG_PASSWORD: The password for the main PostgreSQL database account.

Following the Flask documentation, you can generate the secret key with:

python -c 'import secrets; print(secrets.token_hex())'

Running the ⚙ docker compose

We'll run the docker compose in detached mode, giving it a nice name (it will use our .env by default).

docker compose --project-name geovisio-osm up -d

You can check the services state with the command:

docker compose -p geovisio-osm ps

And the logs with

docker compose -p geovisio-osm logs -f

You can check that the API is working by querying on the host:

curl --fail http://localhost:8080/api

Note

Everything will not be working using http://localhost:8080, as we set some configuration telling the API it will be served on a custom domain.

Domain configuration

You need to set up your domain and must use https as it is mandatory for OAuth2. There are many ways to do this, maybe the easiest way for this is to use a reverse proxy, and let it handle TLS for you.

You can use nginx + letsencrypt (maybe using certbot), caddy or anything you want.

Caddy

Here is a simple Caddy configuration for this:

my.domain.org {
    reverse_proxy :8080
}

🔄 Updating the instance

If at one point you want to update your API version (and you should, we try to add nice functionalities often!), you can run:

docker compose -p geovisio-osm up --pull=always -d

Using Panoramax

After all this, you should be able to go to your custom domain 🌐, log in using your osm account 🔎, upload some pictures 📸 and enjoy Panoramax 🎉

If everything does not work as intended, feel free to open an issue on the gitlab repository, contact us in the Matrix room or on community.openstreetmap.org, with the panoramax tag.