A complete Panoramax deployment with Keycloak authentication

Here is a simple example on how to host a Panoramax instance based on a simple docker compose, and using a custom keycloak as OAuth2 Identity Provider.

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.
maybe secure a bit more the keycloak, follow the production documentation, at least secure more the admin console (cf the documentation)
...

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, especially for running Keycloak so you'll also need a domain. You'll need a reverse proxy to handle tls, cf the Domain section.

Running docker compose

This tutorial uses the files in docker/full-keycloak-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-keycloak-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 used. This needs to be only the domain (like panoramax.my_domain.org).
OAUTH_CLIENT_SECRET: The secret key for the oauth client
FLASK_SECRET_KEY: A secret key to sign the cookies
KEYCLOAK_ADMIN_PASSWORD: The admin password to access the admin console (by default at https://your_domain/oauth)

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

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

You can use the same method to generate OAUTH_CLIENT_SECRET.

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-auth up -d

You can check the services state with the command:

docker compose -p geovisio-auth ps

And the logs with

docker compose -p geovisio-auth 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-auth up --pull=always -d

Administration of keycloak

You can log in keycloak admin console using the KEYCLOAK_ADMIN_PASSWORD credentials on https://your_domain/oauth/.

You can then edit the geovisio realm, edit/remove some users 👥, ...

Tip

On a production grade instance, you'll likely don't want to expose this admin console on the internet, and you can follow the reverse proxy documentation to hide it.

👑 Realm

A default keycloak realm named geovisio is defined in the keycloak-realm.json file. It only define:

Some basic configuration:

User-managed access: ui to manage the user configuration
User registration: users can freely create accounts
Forgot password: link for users that have forgotten their password
Remember me: cookie to remember the user
Edit username: users can edit their usernames

And a geovisio OpenID Connect client with the Direct Access Flow and Standard Flow Oauth2 flows.

Feel free to adjust all you need on this realm. You can refer to the keycloak realm documentation.

✨Themes

You can load themes on keycloak for better login/registering experience. You can see what is done for the IGN instance.

The themes will need to be mounted as volumes in the keycloak container and the path defined by KEYCLOAK_TEMPLATES_DIR.

Using Panoramax API

After all this, you should be able to go to your custom domain 🌐, create an 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.