intersystems-community/fhir-ai-hackathon-kit/iris-environment

IRIS for Health dev environment (FHIR AI Hackathon Kit)

Source tutorials: Tutorials/1-setup/1.1-setup-iris-and-fhir.md, Tutorials/6-extras/CreateAFHIRServerIn5Minutes.md.

Facts (check docker-iris-fhir/docker-compose.yml if anything looks off)

Default IRIS ports 1972/52773 are mapped straight through to the host. The standalone container from CreateAFHIRServerIn5Minutes.md publishes the same ports, so stop one before starting the other.

Lifecycle

./docker-iris-fhir/start.sh            # PowerShell: .\docker-iris-fhir\start.ps1
./docker-iris-fhir/stop_and_remove.sh  # PowerShell: .\docker-iris-fhir\stop_and_remove.ps1
docker compose -f docker-iris-fhir/docker-compose.yml down -v   # full wipe incl. data volume

• start.sh builds the image, waits for IRIS, then runs fhir_server_setup.py inside the container (creates FHIR server, bulk-loads Synthea bundles from docker-iris-fhir/data/fhir). First start is slow (minutes).
• Data lives in named volume iris-data, so it survives restarts. Re-running start.sh on an existing volume re-POSTs the bundles and duplicates patients. Wipe with down -v for a clean state.
• Readiness check: docker ps shows (healthy); curl -u SuperUser:SYS http://localhost:52773/fhir/r4/metadata returns 200.

Shells inside the container

docker exec -it iris-fhir iris session iris     # IRIS terminal (ObjectScript), exit with: halt
docker exec -it iris-fhir bash                  # OS shell
docker cp ./local/file iris-fhir:/path/in/container

Use docker exec / docker cp with the container name. docker compose exec expects the service name (iris), not iris-fhir.

Python env

python -m venv .venv
source .venv/Scripts/activate      # Git Bash on Windows; PowerShell: .\.venv\Scripts\Activate.ps1; mac/linux: source .venv/bin/activate
pip install -r requirements.txt    # run from repo root
cp .env.example .env               # then set OPENAI_API_KEY (needed for vector search and agents)

.env lives only at repo root. Code calls bare load_dotenv(), which walks up from cwd. Do not add per-folder .env files.

Skip-setup scripts (recreate state that earlier tutorials build)

python Tutorials/setup-scripts/setup_csv_data.py      # Sample.Person, Sample.HealthCareData (drop + recreate)
python Tutorials/setup-scripts/setup_vector_store.py  # Diabetes.VectorStore from Tutorials/data/papers (needs OPENAI_API_KEY, paid API calls)

Troubleshooting

When an MCP server for IRIS is configured (.iris-agentic-dev.toml), prefer it for inspecting live state over guessing.