Skip to main content
Version: 4.0.0

Installation

This page walks you through getting the Pyx Identity Resolver (IDR) running in a production-like environment using Docker. If you just want to explore the API locally, the Development Setup guide is a faster path.

New to the IDR?

If you haven't used the service before, start with Understanding the Service for a conceptual overview of what the IDR does and how identifiers, links, and resolution fit together.

Prerequisites​

RequirementMinimum version
Docker20.10+
Docker Compose2.0+ (included with Docker Desktop)

That's it --- the IDR ships as a container image, so you don't need Node.js or any other runtime on the host.

Quick start with Docker Compose​

The fastest way to stand up the IDR and its MinIO object store together is to use the docker-compose.yaml included in the repository:

git clone https://github.com/pyx-industries/pyx-identity-resolver.git
cd pyx-identity-resolver
docker compose up -d

This starts two services:

ServiceDescriptionDefault port
identity-resolverThe IDR REST API3000
minioS3-compatible object store9000 (API), 9090 (console)

Using pre-built images from GHCR​

If you'd rather skip building from source, grab a pre-built image from the GitHub Container Registry.

Two image variants are published for every release:

ImageTag exampleUse case
Standard4.0.0Docker, Docker Compose, Kubernetes
Serverless4.0.0-serverlessAWS Lambda container deployments

Both variants are built for linux/amd64 and linux/arm64, so they work on Intel/AMD servers and ARM-based hosts (Graviton, Apple Silicon under emulation, etc.).

Pulling an image​

# Standard image
docker pull ghcr.io/pyx-industries/pyx-identity-resolver:4.0.0

# Serverless image (AWS Lambda)
docker pull ghcr.io/pyx-industries/pyx-identity-resolver:4.0.0-serverless

Tag format​

Tag patternMeaning
X.Y.ZSpecific release (recommended for production)
X.Y.Z-serverlessServerless variant of a specific release
edgeLatest build from the master branch
sha-<commit>Build pinned to an exact commit
tip

Pin to a specific version tag (e.g. 4.0.0) in production rather than edge or latest to avoid unexpected changes.

Running the pre-built image​

Create an .env file with your configuration (see Configuration for the full variable reference):

OBJECT_STORAGE_ENDPOINT=your-minio-host
OBJECT_STORAGE_PORT=9000
OBJECT_STORAGE_USE_SSL=false
OBJECT_STORAGE_ACCESS_KEY=minioadmin
OBJECT_STORAGE_SECRET_KEY=minioadmin
OBJECT_STORAGE_BUCKET_NAME=idr-bucket
OBJECT_STORAGE_PATH_STYLE=true
IDENTIFIER_PATH=identifiers
API_KEY=your-secret-key
RESOLVER_DOMAIN=https://resolver.example.com
APP_NAME=IDR
PORT=3000

Then run the container with the env file:

docker run -d \
  -p 3000:3000 \
  --env-file .env \
  ghcr.io/pyx-industries/pyx-identity-resolver:4.0.0
NODE_ENV and the serverless code path

Do not set NODE_ENV=production for standard container deployments. When NODE_ENV is production, the IDR bootstraps in serverless mode (AWS Lambda handler) instead of starting a standard HTTP server. Omit NODE_ENV entirely or set it to any other value (e.g. development, test) for Docker-based deployments. See Serverless for details.

You'll still need an S3-compatible object store accessible to the container. See Storage Providers for setup options.

Verify it's running​

Once the container is up, open the Swagger UI at the /api-docs path on your configured host and port. For example, if you mapped port 3000 locally:

http://<your-host>:3000/api-docs

You should see the interactive API documentation. Click Authorize and enter your API_KEY value to start making authenticated requests.

You can also do a quick health check from the command line:

curl -s http://<your-host>:3000/api-docs | head -c 100

If you see HTML content, the service is up and serving requests.

Next steps​