The resolver service generates new Ensembl website urls for different features based on their stable ids, as well as other optional parameters.
git clone https://github.com/Ensembl/ensembl-web-resolver.git
cd ensembl-web-resolver
mv sample-env .env
docker-compose -f docker-compose.yml up
Some urls that are available after deployment on your local machine:
From the project root directory run:
mv sample-env .env
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python3 -m uvicorn app.main:app --port 8001 --reload
APP_PREFIX defaults to /. Set it only when the app should be served under a path prefix, for example /api/resolver.
ENSEMBL_URL is the public website base URL used for redirects. Keep it set to https://www.ensembl.org in production.
METADATA_API_URL independently sets the metadata API base URL, defaulting to
http://metadata-api-svc:8014/api/metadata when omitted.
For local development outside the cluster, override it with
https://www.ensembl.org/api/metadata.
SEARCH_API_URL sets the variant search API base URL, defaulting to
http://ensembl-search-hub-svc:8083/api. Variant requests append
/search/variants.
For a Kubernetes ConfigMap:
data:
ENSEMBL_URL: "https://www.ensembl.org"
METADATA_API_URL: "http://metadata-api-svc:8014/api/metadata"
SEARCH_API_URL: "http://ensembl-search-hub-svc:8083/api"Include the path prefix served by the internal service. If it serves
/genome/... directly, use http://metadata-api-svc:8014 instead.
Deploy the resolver version supporting this setting before applying the ConfigMap.
In addition to HTTP metrics, /metrics exposes resolver_requests_total.
Its endpoint and outcome labels record the resolver result independently
of the HTTP status. Endpoints are legacy_url, stable_id, rapid, and
rapid_stable_id:
| Outcome | Meaning |
|---|---|
resolved |
A new Ensembl URL was returned or redirected to. |
archive_fallback |
The request was redirected to an Ensembl archive. |
interstitial |
A browser was shown the expected HTML interstitial (HTTP 404). |
not_found |
No suitable destination was found. |
invalid_request |
The submitted URL was invalid. |
internal_error |
An unexpected resolver or configuration failure occurred. |
We can use outcome="internal_error" for the resolver failure alert and track
outcome="interstitial" separately, rather than treating its expected HTTP
404 response as a service failure.
/id/{stable_id} and /rapid/id/{stable_id} can use a local fast-match Redb
index. Set FAST_MATCH_ENABLED=true and configure FAST_MATCH_DB_PATH to use
it; set FAST_MATCH_ENABLED=false to retain the search-hub API lookup. The
index is expected to have stable and unversioned stable IDs as keys and values
in the genome_id|doc_type|parent_transcript_id format, with multiple values
delimited by +. The final field is empty for genes and transcripts; for a
protein, it contains the parent transcript stable ID.
The fm_py dependency is published to the private GitLab package registry.
Install the resolver dependencies with a GitLab token that has
read_package_registry access:
export GITLAB_USER="your-gitlab-username"
export GITLAB_TOKEN="your-read-package-registry-token"
python -m pip install \
--extra-index-url "https://${GITLAB_USER}:${GITLAB_TOKEN}@gitlab.ebi.ac.uk/api/v4/projects/6228/packages/pypi/simple" \
-r requirements.txt
Do not store the GitLab token in .env or commit it to source control.
The test workflow installs fm_py from the private GitLab package registry.
Configure these GitHub repository secrets for CI:
GITLAB_USER # GitLab username or token username
GITLAB_TOKEN # GitLab token with read_api scope and access to project 6228
The GitHub Actions runner is Linux x86_64, so the registry must also contain a
compatible Linux x86_64 abi3 wheel, for example
fm_py-0.1.1-cp38-abi3-manylinux_2_28_x86_64.whl.
If the legacy URL mapping tables need to be created or refreshed in the local DuckDB file, run:
duckdb resolver_mappings.db < sql/legacy_url_path_mappings.sql
python -m pip install -r requirements-dev.txt
pytest