Skip to main content
Research Preview — APIs may change. GitHub

​
Local development

This guide walks you through running Astral on your machine. By the end, you will have a working local instance that responds to geocomputation requests.

​
Prerequisites

  • Node.js 20+ — the service uses the --env-file flag, which requires Node 20
  • Docker — for PostgreSQL with PostGIS
  • pnpm — the monorepo uses pnpm workspaces

​
Clone and install

​
Start PostgreSQL + PostGIS

The repo includes a development Docker Compose file that runs PostgreSQL with PostGIS:
Verify the database is running:

​
Port conflicts

If port 5432 is already in use by another PostgreSQL instance, create a docker-compose.override.yml that maps to a different port (e.g., 5434:5432) and update your DATABASE_URL accordingly:
Then set DATABASE_URL=postgresql://postgres:postgres@localhost:5434/astral in your environment file.

​
Environment setup

Edit .env.local with your configuration. You will need a SIGNER_PRIVATE_KEY — any Ethereum private key works for development. You can generate one with openssl rand -hex 32. The important fields:

​
Start the service

The service does not use dotenv. You must pass the env file explicitly using Node’s --env-file flag.
The npm run dev script may not work reliably. The command above is the most reliable way to start the service. You should see output indicating the server is listening on the configured port.

​
Health check

Confirm the service is running:
A successful response means the service is up and connected to the database.

​
Smoke test

Run a distance computation between the Eiffel Tower and a point across the Seine:
The response includes the distance in meters, a cryptographic signature, and input references. If you see a result field with a numeric value, everything is working.

​
Platform notes

PostGIS Docker images may need an explicit platform flag. If the container fails to start, add platform: linux/amd64 to the postgres service in your compose file:
This runs under Rosetta emulation, which is slower but functional.
These ports may collide with other local services:Use the docker-compose.override.yml approach for database port conflicts, and change PORT in .env.local for service port conflicts.

​
Next steps

Calling the API

Learn the request format and response structure

Quickstart

Your first verified spatial computation