Skip to content

Getting Started.md

Jump to bottom
Kelsey Smuczynski edited this page Mar 24, 2026 · 1 revision

Getting Started

This guide covers what OcotilloAPI is, how to get it running locally, and the most important setup traps to avoid.

Read This First

  • Use Python 3.13 or newer — that is what pyproject.toml enforces (not 3.11+ as the README still says).
  • Use the repo virtualenv: source .venv/bin/activate.
  • Expect PostgreSQL with PostGIS — most local work, tests, and import flows assume it.
  • Treat .env.example as a starting point, not a complete source of truth.

What OcotilloAPI Is

OcotilloAPI is a FastAPI backend for geospatial sample and monitoring data. It also includes:

  • A Starlette Admin interface at /admin
  • An OGC API via pygeoapi at /ogcapi
  • A Typer CLI exposed as oco
  • Legacy-to-target data transfer tooling in transfers/
  • Post-Alembic data migrations in data_migrations/

Prerequisites

  • Python 3.13+
  • uv (Astral's Python package manager)
  • PostgreSQL with PostGIS, or Docker Desktop if using Compose
  • psql if you plan to restore local dumps

Setup

1. Clone the repository

git clone https://github.com/DataIntegrationGroup/OcotilloAPI.git
cd OcotilloAPI

2. Install dependencies

uv venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
uv sync --locked --all-groups
pre-commit install

3. Configure environment variables

cp .env.example .env

At minimum, set these in .env:

POSTGRES_USER=
POSTGRES_PASSWORD=
POSTGRES_DB=
POSTGRES_HOST=
POSTGRES_PORT=
MODE=development
AUTHENTIK_DISABLE_AUTHENTICATION=1

To enable /admin, also set:

SESSION_SECRET_KEY=

To enable real authentication (instead of dev bypass):

AUTHENTIK_DISABLE_AUTHENTICATION=0
AUTHENTIK_URL=
AUTHENTIK_CLIENT_ID=
AUTHENTIK_AUTHORIZE_URL=
AUTHENTIK_TOKEN_URL=

To mount pygeoapi successfully:

PYGEOAPI_POSTGRES_HOST=
PYGEOAPI_POSTGRES_PORT=
PYGEOAPI_POSTGRES_DB=
PYGEOAPI_POSTGRES_USER=
PYGEOAPI_POSTGRES_PASSWORD=

Optional operational variables (present in source but not in .env.example):

APITALLY_CLIENT_ID=
ENVIRONMENT=
SENTRY_DSN=
DB_POOL_SIZE=
DB_MAX_OVERFLOW=

4. Run the application

Option A — Docker Compose (recommended)

Spins up PostGIS and the API together:

docker compose up --build
  • API: http://localhost:8000
  • Swagger Docs: http://localhost:8000/docs

The Compose DB initializes both ocotilloapi_dev and ocotilloapi_test.

Option B — Native development

Requires a local PostgreSQL/PostGIS instance:

source .venv/bin/activate
set -a; source .env; set +a
alembic upgrade head
uvicorn main:app --reload

The current repo entrypoint is main:app, not app.main:app as the README still says.

In MODE=development, the app seeds sample data on startup via transfers/seed.py unless a contact already exists.

5. Verify the install

uv run pytest

Tests automatically target ocotilloapi_test. Ensure this database exists in your local Postgres before running.

Local Restore Workflow

The CLI supports restoring from a local .sql / .sql.gz file or from GCS:

source .venv/bin/activate
set -a; source .env; set +a

python -m cli.cli restore-local-db path/to/dump.sql
python -m cli.cli restore-local-db gs://bucket/path.sql.gz

Safety characteristics of the restore flow:

  • Refuses DB_DRIVER=cloudsql
  • Refuses non-local DB hosts
  • Recreates the public schema before restore
  • Strips role-dependent SQL from the dump before loading

Restoring from GCS requires gcs_credentials.json in the root directory.

Common Setup Traps

Trap Detail
Wrong Python version README.md says 3.11+, but pyproject.toml requires 3.13+.
Wrong env var name .env.example lists TRANSFER_PARALLEL, but the code checks TRANSFER_PARALLEL_WELLS.
/admin returns 503 Session middleware is only added when SESSION_SECRET_KEY is present.
pygeoapi fails to mount Mount fails if PYGEOAPI_POSTGRES_PASSWORD is missing.
Missing GCS credentials gcs_credentials.json is required for GCS restores and some transfer flows, but it is not documented when every developer needs it. Confirm with the team if you are doing API-only local work.

Local Modes

Mode Description
API-only Run FastAPI against a local or containerized Postgres/PostGIS database
Full local stack docker compose up --build starts both app and database
Data migration work Use the CLI and transfer scripts — always confirm which database .env points to before running

What To Read Next

Clone this wiki locally