docs: rework library getting started

[nominatim.git] / .github / workflows / ci-tests.yml

diff --git a/.github/workflows/ci-tests.yml b/.github/workflows/ci-tests.yml
index ff4594edaa3bdf43cc85269484e45ccf32e9c88c..1cfaf616818a8b3d3151d4f57199bf752c046c64 100644 (file)
--- a/.github/workflows/ci-tests.yml
+++ b/.github/workflows/ci-tests.yml
@@ -11,7 +11,7 @@ jobs:
               with:
                 submodules: true
 
               with:
                 submodules: true
 

-            - uses: actions/cache@v3
+            - uses: actions/cache@v4

               with:
                   path: |
                      data/country_osm_grid.sql.gz
               with:
                   path: |
                      data/country_osm_grid.sql.gz


@@ -27,7 +27,7 @@ jobs:
                   mv nominatim-src.tar.bz2 Nominatim
 
             - name: 'Upload Artifact'
                   mv nominatim-src.tar.bz2 Nominatim
 
             - name: 'Upload Artifact'

-              uses: actions/upload-artifact@v3
+              uses: actions/upload-artifact@v4

               with:
                   name: full-source
                   path: nominatim-src.tar.bz2
               with:
                   name: full-source
                   path: nominatim-src.tar.bz2


@@ -43,41 +43,29 @@ jobs:
                       ubuntu: 20
                       postgresql: '9.6'
                       postgis: '2.5'
                       ubuntu: 20
                       postgresql: '9.6'
                       postgis: '2.5'

-                      php: '7.3'

                       lua: '5.1'
                     - flavour: ubuntu-20
                       ubuntu: 20
                       postgresql: 13
                       postgis: 3
                       lua: '5.1'
                     - flavour: ubuntu-20
                       ubuntu: 20
                       postgresql: 13
                       postgis: 3

-                      php: '7.4'

                       lua: '5.3'
                     - flavour: ubuntu-22
                       ubuntu: 22
                       postgresql: 15
                       postgis: 3
                       lua: '5.3'
                     - flavour: ubuntu-22
                       ubuntu: 22
                       postgresql: 15
                       postgis: 3

-                      php: '8.1'

                       lua: '5.3'
 
         runs-on: ubuntu-${{ matrix.ubuntu }}.04
 
         steps:
                       lua: '5.3'
 
         runs-on: ubuntu-${{ matrix.ubuntu }}.04
 
         steps:

-            - uses: actions/download-artifact@v3
+            - uses: actions/download-artifact@v4

               with:
                   name: full-source
 
             - name: Unpack Nominatim
               run: tar xf nominatim-src.tar.bz2
 
               with:
                   name: full-source
 
             - name: Unpack Nominatim
               run: tar xf nominatim-src.tar.bz2
 

-            - name: Setup PHP
-              uses: shivammathur/setup-php@v2
-              with:
-                  php-version: ${{ matrix.php }}
-                  tools: phpunit:9, phpcs, composer
-                  ini-values: opcache.jit=disable
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-            - uses: actions/setup-python@v4
+            - uses: actions/setup-python@v5

               with:
                 python-version: 3.7
               if: matrix.flavour == 'oldstuff'
               with:
                 python-version: 3.7
               if: matrix.flavour == 'oldstuff'


@@ -92,23 +80,23 @@ jobs:
                   flavour: ${{ matrix.flavour }}
                   lua: ${{ matrix.lua }}
 
                   flavour: ${{ matrix.flavour }}
                   lua: ${{ matrix.lua }}
 

-            - name: Install test prerequsites (behave from apt)
+            - name: Install test prerequisites (behave from apt)

               run: sudo apt-get install -y -qq python3-behave
               if: matrix.flavour == 'ubuntu-20'
 
               run: sudo apt-get install -y -qq python3-behave
               if: matrix.flavour == 'ubuntu-20'
 

-            - name: Install test prerequsites (behave from pip)
+            - name: Install test prerequisites (behave from pip)

               run: pip3 install behave==1.2.6
               if: (matrix.flavour == 'oldstuff') || (matrix.flavour == 'ubuntu-22')
 
               run: pip3 install behave==1.2.6
               if: (matrix.flavour == 'oldstuff') || (matrix.flavour == 'ubuntu-22')
 

-            - name: Install test prerequsites (from apt for Ununtu 2x)
+            - name: Install test prerequisites (from apt for Ununtu 2x)

               run: sudo apt-get install -y -qq python3-pytest python3-pytest-asyncio uvicorn
               if: matrix.flavour != 'oldstuff'
 
             - name: Install newer pytest-asyncio
               run: sudo apt-get install -y -qq python3-pytest python3-pytest-asyncio uvicorn
               if: matrix.flavour != 'oldstuff'
 
             - name: Install newer pytest-asyncio

-              run: pip3 install -U pytest-asyncio==0.21.1
+              run: pip3 install -U pytest-asyncio

               if: matrix.flavour == 'ubuntu-20'
 
               if: matrix.flavour == 'ubuntu-20'
 

-            - name: Install test prerequsites (from pip for Ubuntu 18)
+            - name: Install test prerequisites (from pip for Ubuntu 18)

               run: pip3 install pytest pytest-asyncio uvicorn
               if: matrix.flavour == 'oldstuff'
 
               run: pip3 install pytest pytest-asyncio uvicorn
               if: matrix.flavour == 'oldstuff'
 


@@ -117,21 +105,12 @@ jobs:
 
             - name: Install latest pylint
               run: pip3 install -U pylint
 
             - name: Install latest pylint
               run: pip3 install -U pylint

-              if: matrix.flavour != 'oldstuff'
-
-            - name: PHP linting
-              run: phpcs --report-width=120 .
-              working-directory: Nominatim
-              if: matrix.flavour != 'oldstuff'
+              if: matrix.flavour == 'ubuntu-22'

 
             - name: Python linting
 
             - name: Python linting

-              run: python3 -m pylint nominatim
+              run: python3 -m pylint src

               working-directory: Nominatim
               working-directory: Nominatim

-              if: matrix.flavour != 'oldstuff'
-
-            - name: PHP unit tests
-              run: phpunit ./
-              working-directory: Nominatim/test/php
+              if: matrix.flavour == 'ubuntu-22'

 
             - name: Python unit tests
               run: python3 -m pytest test/python
 
             - name: Python unit tests
               run: python3 -m pytest test/python


@@ -139,7 +118,8 @@ jobs:
 
             - name: BDD tests
               run: |
 
             - name: BDD tests
               run: |

-                  python3 -m behave -DREMOVE_TEMPLATE=1 -DBUILDDIR=$GITHUB_WORKSPACE/build --format=progress3
+                  export PATH=$GITHUB_WORKSPACE/build/osm2pgsql:$PATH
+                  python3 -m behave -DREMOVE_TEMPLATE=1 --format=progress3

               working-directory: Nominatim/test/bdd
 
             - name: Install mypy and typechecking info
               working-directory: Nominatim/test/bdd
 
             - name: Install mypy and typechecking info


@@ -147,7 +127,7 @@ jobs:
               if: matrix.flavour != 'oldstuff'
 
             - name: Python static typechecking
               if: matrix.flavour != 'oldstuff'
 
             - name: Python static typechecking

-              run: python3 -m mypy --strict nominatim
+              run: python3 -m mypy --strict src

               working-directory: Nominatim
               if: matrix.flavour != 'oldstuff'
 
               working-directory: Nominatim
               if: matrix.flavour != 'oldstuff'
 


@@ -155,8 +135,12 @@ jobs:
         needs: create-archive
         runs-on: ubuntu-20.04
 
         needs: create-archive
         runs-on: ubuntu-20.04
 

+        strategy:
+            matrix:
+                postgresql: ["13", "16"]
+

         steps:
         steps:

-            - uses: actions/download-artifact@v3
+            - uses: actions/download-artifact@v4

               with:
                   name: full-source
 
               with:
                   name: full-source
 


@@ -170,31 +154,34 @@ jobs:
 
             - uses: ./Nominatim/.github/actions/setup-postgresql
               with:
 
             - uses: ./Nominatim/.github/actions/setup-postgresql
               with:

-                  postgresql-version: 13
+                  postgresql-version: ${{ matrix.postgresql }}

                   postgis-version: 3
 
             - name: Install Postgresql server dev
                   postgis-version: 3
 
             - name: Install Postgresql server dev

-              run: sudo apt-get install postgresql-server-dev-13
+              run: sudo apt-get install postgresql-server-dev-$PGVER
+              env:
+                PGVER: ${{ matrix.postgresql }}

 
             - uses: ./Nominatim/.github/actions/build-nominatim
               with:
                   cmake-args: -DBUILD_MODULE=on
 
 
             - uses: ./Nominatim/.github/actions/build-nominatim
               with:
                   cmake-args: -DBUILD_MODULE=on
 

-            - name: Install test prerequsites
+            - name: Install test prerequisites

               run: sudo apt-get install -y -qq python3-behave
 
             - name: BDD tests (legacy tokenizer)
               run: |
               run: sudo apt-get install -y -qq python3-behave
 
             - name: BDD tests (legacy tokenizer)
               run: |

-                  python3 -m behave -DREMOVE_TEMPLATE=1 -DBUILDDIR=$GITHUB_WORKSPACE/build -DTOKENIZER=legacy --format=progress3
+                  export PATH=$GITHUB_WORKSPACE/build/osm2pgsql:$PATH
+                  python3 -m behave -DREMOVE_TEMPLATE=1 -DSERVER_MODULE_PATH=$GITHUB_WORKSPACE/build/module -DAPI_ENGINE=php -DTOKENIZER=legacy --format=progress3

               working-directory: Nominatim/test/bdd
 
 
               working-directory: Nominatim/test/bdd
 
 

-    python-api-test:
+    php-test:

         needs: create-archive
         runs-on: ubuntu-22.04
 
         steps:
         needs: create-archive
         runs-on: ubuntu-22.04
 
         steps:

-            - uses: actions/download-artifact@v3
+            - uses: actions/download-artifact@v4

               with:
                   name: full-source
 
               with:
                   name: full-source
 


@@ -206,19 +193,34 @@ jobs:
                   postgresql-version: 15
                   postgis-version: 3
 
                   postgresql-version: 15
                   postgis-version: 3
 

+            - name: Setup PHP
+              uses: shivammathur/setup-php@v2
+              with:
+                  php-version: 8.1
+                  tools: phpunit:9, phpcs, composer
+                  ini-values: opcache.jit=disable
+              env:
+                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: PHP linting
+              run: phpcs --report-width=120 .
+              working-directory: Nominatim
+
+            - name: PHP unit tests
+              run: phpunit ./
+              working-directory: Nominatim/test/php
+

             - uses: ./Nominatim/.github/actions/build-nominatim
               with:
                   flavour: 'ubuntu-22'
 
             - uses: ./Nominatim/.github/actions/build-nominatim
               with:
                   flavour: 'ubuntu-22'
 

-            - name: Install test prerequsites
+            - name: Install test prerequisites

               run: sudo apt-get install -y -qq python3-behave
 
               run: sudo apt-get install -y -qq python3-behave
 

-            - name: Install Python webservers
-              run: pip3 install starlette asgi_lifespan httpx
-
-            - name: BDD tests (starlette)
+            - name: BDD tests (php)

               run: |
               run: |

-                  python3 -m behave -DREMOVE_TEMPLATE=1 -DBUILDDIR=$GITHUB_WORKSPACE/build -DAPI_ENGINE=starlette --format=progress3
+                  export PATH=$GITHUB_WORKSPACE/build/osm2pgsql:$PATH
+                  python3 -m behave -DREMOVE_TEMPLATE=1 -DAPI_ENGINE=php --format=progress3

               working-directory: Nominatim/test/bdd
 
 
               working-directory: Nominatim/test/bdd
 
 


@@ -228,16 +230,16 @@ jobs:
 
         strategy:
             matrix:
 
         strategy:
             matrix:

-                name: [Ubuntu-20, Ubuntu-22]
+                name: [Ubuntu-22, Ubuntu-24]

                 include:
                 include:

-                    - name: Ubuntu-20
-                      image: "ubuntu:20.04"
-                      ubuntu: 20
-                      install_mode: install-apache

                     - name: Ubuntu-22
                       image: "ubuntu:22.04"
                       ubuntu: 22
                       install_mode: install-apache
                     - name: Ubuntu-22
                       image: "ubuntu:22.04"
                       ubuntu: 22
                       install_mode: install-apache

+                    - name: Ubuntu-24
+                      image: "ubuntu:24.04"
+                      ubuntu: 24
+                      install_mode: install-apache

 
         container:
             image: ${{ matrix.image }}
 
         container:
             image: ${{ matrix.image }}


@@ -268,7 +270,7 @@ jobs:
                 OS: ${{ matrix.name }}
                 INSTALL_MODE: ${{ matrix.install_mode }}
 
                 OS: ${{ matrix.name }}
                 INSTALL_MODE: ${{ matrix.install_mode }}
 

-            - uses: actions/download-artifact@v3
+            - uses: actions/download-artifact@v4

               with:
                   name: full-source
                   path: /home/nominatim
               with:
                   name: full-source
                   path: /home/nominatim


@@ -293,6 +295,16 @@ jobs:
                   mkdir data-env-reverse
               working-directory: /home/nominatim
 
                   mkdir data-env-reverse
               working-directory: /home/nominatim
 

+            - name: Add nominatim to path
+              run: |
+                sudo ln -s /home/nominatim/nominatim-venv/bin/nominatim /usr/local/bin/nominatim
+              if: matrix.ubuntu == 24
+
+            - name: Need lua binary
+              run: |
+                sudo apt-get install -y lua5.4 lua-dkjson
+              if: matrix.ubuntu == 24
+

             - name: Print version
               run: nominatim --version
               working-directory: /home/nominatim/nominatim-project
             - name: Print version
               run: nominatim --version
               working-directory: /home/nominatim/nominatim-project


@@ -325,9 +337,18 @@ jobs:
               run: apt-get install -y python3-pip
               shell: bash
 
               run: apt-get install -y python3-pip
               shell: bash
 

-            - name: Run update
+            - name: Install osmium (Ubuntu 22)

               run: |
                   pip3 install --user osmium
               run: |
                   pip3 install --user osmium

+              if: matrix.ubuntu == 22
+
+            - name: Install osmium (Ubuntu 24)
+              run: |
+                  /home/nominatim/nominatim-venv/bin/pip install osmium
+              if: matrix.ubuntu == 24
+
+            - name: Run update
+              run: |

                   nominatim replication --init
                   NOMINATIM_REPLICATION_MAX_DIFF=1 nominatim replication --once
               working-directory: /home/nominatim/nominatim-project
                   nominatim replication --init
                   NOMINATIM_REPLICATION_MAX_DIFF=1 nominatim replication --once
               working-directory: /home/nominatim/nominatim-project


@@ -354,97 +375,49 @@ jobs:
       runs-on: ubuntu-latest
       needs: create-archive
 
       runs-on: ubuntu-latest
       needs: create-archive
 

-      strategy:
-          matrix:
-              name: [Ubuntu-22]
-              include:
-                  - name: Ubuntu-22
-                    image: "ubuntu:22.04"
-                    ubuntu: 22
-                    install_mode: install-apache
-
-      container:
-          image: ${{ matrix.image }}
-          env:
-              LANG: en_US.UTF-8
-
-      defaults:
-          run:
-              shell: sudo -Hu nominatim bash --noprofile --norc -eo pipefail {0}
-

       steps:
       steps:

-          - name: Prepare container (Ubuntu)
-            run: |
-                export APT_LISTCHANGES_FRONTEND=none
-                export DEBIAN_FRONTEND=noninteractive
-                apt-get update -qq
-                apt-get install -y git sudo wget
-                ln -snf /usr/share/zoneinfo/$CONTAINER_TIMEZONE /etc/localtime && echo $CONTAINER_TIMEZONE > /etc/timezone
-            shell: bash
-
-          - name: Setup database users
-            run: |
-                useradd -m nominatim
-                useradd -m osm-import
-                echo 'nominatim   ALL=(ALL:ALL) NOPASSWD: ALL' > /etc/sudoers.d/nominatim
-                echo "/home/nominatim/Nominatim/vagrant/Install-on-${OS}.sh no $INSTALL_MODE" > /home/nominatim/vagrant.sh
-            shell: bash
-            env:
-              OS: ${{ matrix.name }}
-              INSTALL_MODE: ${{ matrix.install_mode }}
-
-          - uses: actions/download-artifact@v3
+          - uses: actions/download-artifact@v4

             with:
                 name: full-source
             with:
                 name: full-source

-                path: /home/nominatim

 
 

-          - name: Install Nominatim
-            run: |
-              export USERNAME=nominatim
-              export USERHOME=/home/nominatim
-              export NOSYSTEMD=yes
-              export HAVE_SELINUX=no
-              tar xf nominatim-src.tar.bz2
-              . vagrant.sh
-            working-directory: /home/nominatim
+          - name: Unpack Nominatim
+            run: tar xf nominatim-src.tar.bz2
+
+          - uses: ./Nominatim/.github/actions/setup-postgresql
+            with:
+                postgresql-version: 16
+                postgis-version: 3
+
+          - uses: ./Nominatim/.github/actions/build-nominatim
+            with:
+                flavour: ubuntu-22
+                lua: 5.3

 
           - name: Prepare import environment
             run: |
                 mv Nominatim/test/testdb/apidb-test-data.pbf test.pbf
 
           - name: Prepare import environment
             run: |
                 mv Nominatim/test/testdb/apidb-test-data.pbf test.pbf

-                mv Nominatim/settings/flex-base.lua flex-base.lua
-                mv Nominatim/settings/import-extratags.lua import-extratags.lua
-                mv Nominatim/settings/taginfo.lua taginfo.lua

                 rm -rf Nominatim
                 rm -rf Nominatim

-                mkdir data-env-reverse
-            working-directory: /home/nominatim

 
           - name: Prepare Database
             run: |
                 nominatim import --prepare-database
 
           - name: Prepare Database
             run: |
                 nominatim import --prepare-database

-            working-directory: /home/nominatim/nominatim-project

 
           - name: Create import user
             run: |
 
           - name: Create import user
             run: |

-                sudo -u postgres createuser -S osm-import
-                sudo -u postgres psql -c "ALTER USER \"osm-import\" WITH PASSWORD 'osm-import';"
-            working-directory: /home/nominatim/nominatim-project
-
-          - name: Grant import user rights
-            run: |
-                sudo -u postgres psql -c "GRANT INSERT, UPDATE ON ALL TABLES IN SCHEMA public TO \"osm-import\";"
-            working-directory: /home/nominatim/nominatim-project
-
-          - name: Change nominatim directory ownership
-            run: |
-                sudo chown -R osm-import /home/nominatim/nominatim-project
+                sudo -u postgres createuser osm-import
+                psql -d nominatim -c "ALTER USER \"osm-import\" WITH PASSWORD 'osm-import'"
+                psql -d nominatim -c 'GRANT CREATE ON SCHEMA public TO "osm-import"'

 
           - name: Run import
             run: |
 
           - name: Run import
             run: |

-                NOMINATIM_DATABASE_DSN="pgsql:dbname=nominatim;user=osm-import;password=osm-import" nominatim import --continue import-from-file --osm-file ../test.pbf
-            working-directory: /home/nominatim/nominatim-project
-            shell: sudo -Hu osm-import bash --noprofile --norc -eo pipefail {0}
+                NOMINATIM_DATABASE_DSN="pgsql:host=127.0.0.1;dbname=nominatim;user=osm-import;password=osm-import" nominatim import --continue import-from-file --osm-file test.pbf

 
           - name: Check full import
             run: nominatim admin --check-database
 
           - name: Check full import
             run: nominatim admin --check-database

-            working-directory: /home/nominatim/nominatim-project
-            shell: sudo -Hu osm-import bash --noprofile --norc -eo pipefail {0}
\ No newline at end of file
+
+    codespell:
+      runs-on: ubuntu-latest
+      steps:
+          - uses: codespell-project/actions-codespell@v2
+            with:
+                only_warn: 1