Skip to content

Running Panoramax API

Panoramax is mainly an API and some pictures background workers. The pictures workers are technically optional, if they are not spawned the pictures will be processed by the API, but if they are not run, pictures process cannot be retried, are lost on restart...

Information

Apart in development, you should run both API and picture workers.

Important

All Panoramax commands will require some configuration. Be sure to check the documentation before running the commands.

Start API

This command starts the HTTP API to serve pictures & sequences to users.

For production context, you want a more robust WSGI server than the Flask's embedded one. Flask team recommend several servers, check the documentation to understand the different tradeoff.

You can use Waitress.

pip install waitress
python3 -m waitress --port 5000 --url-scheme=https --call 'geovisio:create_app'

You can pass more parameters to waitress, like --threads to define the number of worker threads run, check the documentation for fine tuning if needed.

You can use Gunicorn.

pip install gunicorn
gunicorn -b :5000 'geovisio:create_app()'

You can pass more parameters to gunicorn, like --workers to define the number of processes and --threads to define the number of threads by process, check the documentation for fine tuning if needed.

docker run \
    -e DB_URL=<database connection string> \
    -p 5000:5000 \
    --name geovisio \
    -v <path where to persist pictures>:/data/geovisio \
    panoramax/api:develop \
    api

docker run \
    -e DB_URL=<database connection string> \
    -p 5000:5000 \
    --name geovisio \
    -v <path where to persist pictures>:/data/geovisio \
    panoramax/api:develop \
    ssl-api

Docker compose is handy to run several services at once, you can spawn the API and the pictures workers with:

docker compose -f <you_compose_file> up --detach (1)
  1. This will run all the services in detached mode

With this you can have hot reload for better development experience.

flask --debug run

Note that you can also run with another env file if you test over many setups:

FLASK_SKIP_DOTENV=1 flask --env-file myconf.env run

In that case, your env file may contain the FLASK_APP=geovisio variable to properly start.

Background worker

This command starts the 1 picture worker, used to process uploaded pictures in the background.

Several workers can run in parallel, you just adjust the number of times you spawn them to the number of CPUs you want to use.

flask picture-worker

Spawning more workers requires running this command several times.

docker run \
    -e DB_URL=<database connection string> \
    -p 5000:5000 \
    --name geovisio-worker \
    -v <path where to persist pictures>:/data/geovisio \
    panoramax/api:develop \
    picture-worker

Note

This docker container should have access to the same file system used by the API. So you'll likely want to share the volumes between the API containers and the pictures background worker containers

As seen below, you can spawn the API and the pictures workers with one command.

Docker compose also have a way to scale the number of containers of one service.

docker compose -F <you_compose_file> up background-worker -d --scale background-worker=<VALUE>