.. _install:

Install
=======

pygeoapi, by default, is natively run as a Flask app (the code struct is an API and Flask is used as a wrapper). Optionally it can be run as a Starlette app.

pygeoapi uses two configuration files: **pygeoapi-config.yml** and **openapi.yml**. First configuration contains all the information and setup to run pygeoapi while the second is exclusivally for the openapi.

pygeoapi requires setting ``PYGEOAPI_CONFIG`` and  ``PYGEOAPI_OPENAPI`` env variable.   ``PYGEOAPI_CONFIG`` points to the yaml file containing the configuration, in the example
below we copy the ``local.config.yml`` default configuration to ``pygeoapi-config.yml`` and use this configuration file.

``PYGEOAPI_OPENAPI`` variable is the path to openapi file configuration, this file **needs to be autogenerated** using the  ``pygeoapi generate-openapi-document`` command and 
the pygeoapi config files e.g.:  ``pygeoapi generate-openapi-document -c local.config.yml > openapi.yml``. And then setting the env variable to the path:
``export PYGEOAPI_OPENAPI=/path/to/openapi.yml``

For production environments it is recommended to use :ref:`docker` or specialized servers like WSGI HTTP server :ref:`wsgi` or ASGI HTTP server :ref:`asgi`

Copy/paste install
------------------

It is advisable to run pygeoapi inside an isolated enviroment either *virtualenv* or *docker*, mainly to avoid python package conflicts.

.. code-block:: console

	# create virtualenv
	virtualenv -p python pygeoapi
	cd pygeoapi
	. bin/activate
	git clone https://github.com/geopython/pygeoapi.git
	cd pygeoapi

	# install requirements
	pip install -r requirements.txt
	pip install -r requirements-dev.txt

	# optionally install requirements for starlette
	pip install -r requirements-starlette.txt

	# install source in current directory
	pip install -e .
	cp pygeoapi-config.yml local.config.yml
	# edit configuration file
	nano  local.config.yml

	export PYGEOAPI_CONFIG=/path/to/local.config.yml
	# generate OpenAPI Document
	pygeoapi generate-openapi-document -c local.config.yml > openapi.yml
	export PYGEOAPI_OPENAPI=/path/to/openapi.yml

	# run pygeoapi
	pygeoapi serve

	# optionally run pygeoapi with starlette
	pygeoapi serve --starlette

If the default configuration was used then we should have pygeoapi running on

.. image:: /_static/openapi_intro_page.png