Skip to content
Snowpack

Local Setup

This guide walks you through getting Snowpack running on your machine for development and testing.

Prerequisites

Before you begin, make sure you have the following installed:

  • Python 3.12+ — Snowpack targets Python 3.12 and uses modern language features (match/case, type statements, | union syntax).
  • uv — the project’s sole package manager. Never use pip, poetry, or pipenv.
  • Docker — required if you want to run the full API stack locally (Postgres + API server).

Install dependencies

Clone the repository and install all dependencies, including dev extras:

Terminal window
uv sync --extra dev

This creates a virtual environment and installs everything Snowpack needs. You never need to activate the venv manually — all commands are run through uv run.

Run the API with Docker Compose

The easiest way to get a fully working local environment is Docker Compose. It starts a Postgres database and the Snowpack API together:

Terminal window
docker compose up --build

Once the containers are healthy:

  • API is available at http://localhost:8000
  • Web UI is available at http://localhost:8000/ui
  • Swagger (OpenAPI) docs at http://localhost:8000/docs
  • ReDoc at http://localhost:8000/redoc

Run the API directly

If you prefer running outside Docker — for example, to use --reload during development — you can start the API with uvicorn:

Terminal window
SNOWPACK_SPARK_HOST=your-spark-host uv run uvicorn snowpack.api:app --reload

Replace your-spark-host with the hostname of an accessible Spark Thrift Server. You will also need a running Postgres instance; see the Configuration reference for the full set of SNOWPACK_POSTGRES_* variables.

Run the tests

Snowpack uses pytest for all testing. Common invocations:

CommandWhat it does
uv run pytestRun the full test suite.
uv run pytest -xStop on the first failure.
uv run pytest tests/unit/Run unit tests only.
uv run pytest --cov=snowpackRun all tests with coverage reporting.

Tests use moto for AWS Glue mocking and unittest.mock for Spark/Thrift mocking, so no external services are needed to run the unit suite.

Verify the UI and docs

After starting the API (via Docker or uvicorn), open these URLs in your browser:

  • Web UI — http://localhost:8000/ui — the Alpine.js dashboard for browsing tables, health reports, and job history.
  • Swagger UI — http://localhost:8000/docs — interactive OpenAPI documentation where you can try out every endpoint.
  • ReDoc — http://localhost:8000/redoc — an alternative, read-friendly rendering of the same OpenAPI spec.