Local Setup

Prerequisites

Install system GIS dependencies (example for Ubuntu/Debian):

sudo apt update
sudo apt install gdal-bin libgdal-dev libproj-dev libgeos-dev libspatialite-dev spatialite-bin libsqlite3-mod-spatialite

For PostGIS workflows:

sudo apt install postgresql postgresql-contrib postgis

Python and App Setup

uv venv .venv
source .venv/bin/activate
uv pip install -r requirements.txt
cp .env.example .env
uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver

Optional sample data:

uv run python manage.py load_sample_data --count 25 --mix

Development Commands

make dev          # run Django dev server
make test         # node + django tests
make check        # format + lint
make docs-serve   # serve MkDocs locally (http://127.0.0.1:8001)
make docs-build   # build docs site into ./site

Notes on Database Selection in Tests

The app chooses test DBs in this order:

  1. TEST_DATABASE_URL (preferred for external disposable DB)
  2. TEST_USE_DATABASE_URL=True + DATABASE_URL
  3. fallback local SpatiaLite test DB (db.test.sqlite3)

TEST_DATABASE_URL uses Django's default create/drop test DB flow unless TEST_REUSE_EXISTING_DB=True is explicitly set.

Important: - Fresh PostGIS test DB creation runs CREATE EXTENSION postgis. - That commonly requires superuser privileges on the test connection. - For a local Docker-only test instance, either use postgres as test user or make your dedicated test role SUPERUSER.

Recommended local PostGIS test DB (isolated from dev DB):

# docker-compose.testdb.yml
services:
  postgis_test:
    image: postgis/postgis:16-3.4
    container_name: lmstool2-postgis-test
    ports:
      - "5436:5432"
    environment:
      POSTGRES_DB: postgres
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgis_test_data:/var/lib/postgresql/data

volumes:
  postgis_test_data:

docker compose -f docker-compose.testdb.yml up -d
docker exec -it lmstool2-postgis-test psql -U postgres -d postgres -c "CREATE ROLE landtooltestuser LOGIN PASSWORD '<TEST_PASS>' CREATEDB SUPERUSER;"
docker exec -it lmstool2-postgis-test psql -U postgres -d postgres -c "CREATE DATABASE landtool_test OWNER landtooltestuser;"
docker exec -it lmstool2-postgis-test psql -U postgres -d landtool_test -c "CREATE EXTENSION IF NOT EXISTS postgis;"

TEST_DATABASE_URL=postgresql://landtooltestuser:<TEST_PASS>@127.0.0.1:5436/landtool_test
TEST_USE_DATABASE_URL=False
TEST_REUSE_EXISTING_DB=False

Alternative local-only .env (use built-in superuser):

TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5436/postgres
TEST_USE_DATABASE_URL=False
TEST_REUSE_EXISTING_DB=False