{"id":37019515,"url":"https://github.com/ahdis/matchbox","last_synced_at":"2026-01-14T02:10:23.862Z","repository":{"id":35814467,"uuid":"288694718","full_name":"ahdis/matchbox","owner":"ahdis","description":"validation and mapping for FHIR","archived":false,"fork":true,"pushed_at":"2026-01-06T17:44:54.000Z","size":196812,"stargazers_count":32,"open_issues_count":25,"forks_count":25,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-01-07T04:49:35.371Z","etag":null,"topics":["cda","docker","fhir","hacktoberfest","java","mapping","rest","sdc","transformation","validation"],"latest_commit_sha":null,"homepage":"https://www.matchbox.health/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"hapifhir/hapi-fhir-jpaserver-starter","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahdis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-08-19T09:52:28.000Z","updated_at":"2026-01-05T16:51:54.000Z","dependencies_parsed_at":"2023-10-04T04:03:43.099Z","dependency_job_id":"70bd15bb-f820-4cd7-9480-9397c4745d0c","html_url":"https://github.com/ahdis/matchbox","commit_stats":null,"previous_names":[],"tags_count":85,"template":false,"template_full_name":null,"purl":"pkg:github/ahdis/matchbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahdis%2Fmatchbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahdis%2Fmatchbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahdis%2Fmatchbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahdis%2Fmatchbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahdis","download_url":"https://codeload.github.com/ahdis/matchbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahdis%2Fmatchbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28408711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T01:52:23.358Z","status":"online","status_checked_at":"2026-01-14T02:00:06.678Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cda","docker","fhir","hacktoberfest","java","mapping","rest","sdc","transformation","validation"],"created_at":"2026-01-14T02:10:23.102Z","updated_at":"2026-01-14T02:10:23.857Z","avatar_url":"https://github.com/ahdis.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matchbox\n\n[Matchbox](https://matchbox.health) is a FHIR server based on the [hapifhir/hapi-fhir-jpaserver-starter](https://github.com/hapifhir/hapi-fhir-jpaserver-starter)\n\n- (pre-)load FHIR implementation guides from the package server for conformance resources (StructureMap, Questionnaire, CodeSystem, ValueSet, ConceptMap, NamingSystem, StructureDefinition). The \"with-preload\" subfolder contains an example with the implementation guides provided for the [public test server](https://test.ahdis.ch/matchbox/fhir).\n- validation support: [server]/$validate for checking FHIR resources conforming to the loaded implementation guides\n- FHIR Mapping Language endpoints for creation of StructureMaps and support for the [StructureMap/$transform](https://www.hl7.org/fhir/operation-structuremap-transform.html) operation\n- SDC (Structured Data Capture) [extraction](https://build.fhir.org/ig/HL7/sdc/extraction.html#map-extract) support based on the FHIR Mapping language and [Questionnaire/$extract](http://build.fhir.org/ig/HL7/sdc/OperationDefinition-QuestionnaireResponse-extract.html)\n\nthe server can be run in two configurations, development (allowing updating resources, set flag in application.yaml in matchbox.fhir.context.onlyOneEngine to true) or deployment (default), see also additional [documentation](https://ahdis.github.io/matchbox)\n\na public development server is hosted at [https://test.ahdis.ch/matchbox/fhir](https://test.ahdis.ch/matchbox/fhir) with a corresponding gui [https://test.ahdis.ch/matchbox/](https://test.ahdis.ch/matchbox/#)\n\na public test server is hosted at [https://test.ahdis.ch/matchboxv3/fhir](https://test.ahdis.ch/matchboxv3/fhir) with a corresponding gui [https://test.ahdis.ch/matchboxv3/](https://test.ahdis.ch/matchboxv3/#)\n\n## containers\n\nThe docker file will create a docker image with no preloaded implementation guides. A list of implementation guides to load can be passed as config-map.\n\n## Prerequisites\n\n- [This project](https://github.com/ahdis/matchbox) checked out. You may wish to create a GitHub Fork of the project and check that out instead so that you can customize the project and save the results to GitHub. Check out the main branch (master is kept in sync with [hapi-fhir-jpaserver-starter](https://github.com/hapifhir/hapi-fhir-jpaserver-starter)\n- Oracle Java (JDK) installed: Minimum JDK11 or newer.\n- Apache Maven build tool (newest version)\n\n## Running locally\n\nThe easiest way to run this server entirely depends on your environment requirements. At least, the following 4 ways are supported:\n\n## using prebuilt image\n\n```\ndocker run -d --name matchbox -p 8080:8080  europe-west6-docker.pkg.dev/ahdis-ch/ahdis/matchbox:v3.9.10 -v /Users/oegger/Documents/github/matchbox/matchbox-server/with-settings:/config matchbox\n```\n\nnote replace /Users/oegger/Documents/github/matchbox/matchbox-server/with-settings with the folder where you have your application.yaml (and since v3.9.10) your [fhir-settings.json](https://confluence.hl7.org/display/FHIR/Using+fhir-settings.json).\n\n### Using spring-boot\n\nWith no implementation guide:\n\n```bash\nmvn clean install -DskipTests spring-boot:run\n```\n\nLoad example implementation guides (needs postgres):\n\n```bash\nmvn clean install -DskipTests spring-boot:run -Dspring-boot.run.arguments=--spring.config.additional-location=file:with-preload/application.yaml\n```\n\nor\n\n```\njava -Dspring.config.additional-location=file:with-preload/application.yaml -jar target/matchbox.jar\n```\n\n```\nmvn clean install -DskipTests spring-boot:run -Dspring-boot.run.jvmArguments=\"-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005\"\n```\n\nThen, browse to the following link to use the server:\n\n[http://localhost:8080/matchbox/fhir](http://localhost:8080/matchboxv3/fhir)\nor\n[http://localhost:8080/matchbox/#/](http://localhost:8080/matchboxv3/#/)\n\n\n## building with Docker\n\n### Configurable base image:\n\n```bash\nmvn package -DskipTests\ncd matchbox-server\ndocker build -t matchbox .\ndocker run -d --name matchbox -p 8080:8080 -v /Users/oegger/Documents/github/matchbox/matchbox-server/with-settings:/config matchbox\n```\n\nServer will then be accessible at http://localhost:8080/matchboxv3/fhir/metadata.\n\nTo dynamically configure run in a kubernetes environment and add a kubernetes config map that provides /config/application.yaml file with implementation guide list like in \"with-preload/application.yaml\"\n\n## Using docker-compose with a persistent postgreSQL database\n\nThe database will be stored in the \"data\" directory. The configuration can be found in the \"with-postgres\" directory or in the \"with-preload\" directory.\n\nChange to either with-posgres directory or the with-preload directory (contains a list of swiss ig's).\n\nFor the first time, you might need to do\n\n```\ndocker-compose up matchbox-db\n```\n\nthat the database gets initialized before matchbox is starting up (needs a fix)\n\n```\nmkdir data\nmvn clean package -DskipTests\ndocker build -t matchbox .\ndocker-compose up\n```\n\nMatchbox will be available at [http://localhost:8080/matchboxv3/fhir](http://localhost:8080/matchboxv3/fhir)\nMatchbox-gui will be available at [http://localhost:8080/matchboxv3/#/](http://localhost:8080/matchboxv3/#/)\n\nExport the DB data:\n\n```\ndocker-compose exec -T matchbox-test-db pg_dump -Fc -U matchbox matchbox \u003e mydump\n```\n\nReimport the DB data:\n\n```\ndocker-compose exec -T matchbox-test-db pg_restore -c -U matchbox -d matchbox \u003c mydump\n```\n\n### making container available\n\n```\ndocker tag matchbox eu.gcr.io/fhir-ch/matchbox:4.0.12\n\ndocker push eu.gcr.io/fhir-ch/matchbox:v4.0.12\n```\n\n### publish docs\n\ndocumentation is maintained in docs folder using [mkdocs-material](https://squidfunk.github.io/mkdocs-material/):\n\n- develop docs: mkdocs serve\n- publish docs: mkdocs gh-deploy --force\n\ndocs are then available at https://ahdis.github.io/matchbox/\n\n# Kubernetes\n\nkubectl cp matchbox-test-0:fhir.logdir_IS_UNDEFINED ./fhir.logdir/\n\nkubectl cp matchbox-test-app-d684cf865 ./fhir.logdir/\n\n# MVN run unit tests\n\nmvn -Dtest=CapabilityStatementTests test\n\n# Making a release\n\n1. Create a pull request that updates the version in the different files (pom.xml files, package.json, the docker pull\n   command in documentation, the changelog, etc.).\n2. Merge the pull request if all tests have succeeded.\n3. Wait for the [Angular workflow](https://github.com/ahdis/matchbox/blob/main/.github/workflows/angular_build.yml)\n   to complete. Since the package.json was modified, the Angular project is rebuilt, unless you also have built the \n   Angular project in your commit ; in that case, the Angular workflow won't commit anything.\n4. Create a [release](https://github.com/ahdis/matchbox/releases) with the changelog (e.g. \"matchbox v3.4.1\") and a\n   [tag](https://github.com/ahdis/matchbox/tags) (e.g. `v.3.4.1`) in GitHub.\n5. It will trigger two workflows:\n   1. The [Docker workflow](https://github.com/ahdis/matchbox/blob/main/.github/workflows/googleregistry.yml), that\n      builds a Docker container around `matchbox-server` and publishes it to the Google Artifact registry.\n   2. The [Maven workflow](https://github.com/ahdis/matchbox/blob/main/.github/workflows/central_repository.yml), that\n      builds the `matchbox-engine` JAR and publishes it to the Maven Central Repository. The version used is the one\n      specified in the POM.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahdis%2Fmatchbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahdis%2Fmatchbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahdis%2Fmatchbox/lists"}