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

git clone https://github.com/AstralProtocol/astral-location-services.git
cd astral-location-services
pnpm install

​
Start PostgreSQL + PostGIS

The repo includes a development Docker Compose file that runs PostgreSQL with PostGIS: 
docker compose -f docker-compose.dev.yml up -d
Verify the database is running: 
docker compose -f docker-compose.dev.yml ps

​
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: 
# docker-compose.override.yml
services:
  postgres:
    ports:
      - "5434:5432"
Then set DATABASE_URL=postgresql://postgres:postgres@localhost:5434/astral in your environment file.

​
Environment setup

cp packages/astral-service/.env.example packages/astral-service/.env.local
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:
VariableDescriptionExample
DATABASE_URLPostgreSQL connection stringpostgresql://postgres:postgres@localhost:5432/astral
PORTHTTP server port3004
SIGNER_PRIVATE_KEYEthereum private key for signing results0xac0974bec...
CHAIN_IDDefault chain ID84532 (Base Sepolia)

​
Start the service

The service does not use dotenv. You must pass the env file explicitly using Node’s --env-file flag.
node --env-file=packages/astral-service/.env.local --import tsx packages/astral-service/src/index.ts
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: 
curl http://localhost:3004/health
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: 
curl -X POST http://localhost:3004/compute/distance \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "type": "Point", "coordinates": [2.2945, 48.8584] },
    "to": { "type": "Point", "coordinates": [2.3522, 48.8566] },
    "chainId": 84532
  }'
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:
services:
  postgres:
    platform: linux/amd64
    image: postgis/postgis:16-3.4
This runs under Rosetta emulation, which is slower but functional.
These ports may collide with other local services:
PortUsed byCommon conflict
5432PostgreSQLOther Postgres instances, Homebrew Postgres
3004Astral serviceOther dev servers
3000-3003Other monorepo packagesNext.js, React dev servers
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