FHIR environment setup guide

I know that people who are completely new to VS Code, Git, Docker, FHIR, and other tools can sometimes struggle with setting up the environment. So I decided to write an article that walks through the entire setup process step by step to make it easier to get started.

I’d really appreciate it if you could leave a comment at the end - let me know if the instructions were clear, if anything was missing, or if there’s anything else you'd find helpful.

The setup includes:

✅ VS Code – Code editor
✅ Git – Version control system
✅ Docker – Runs an instance of IRIS for Health Community
✅ VS Code REST Client Extension – For running FHIR API queries
✅ Python – For writing FHIR-based scripts
✅ Jupyter Notebooks – For AI and FHIR assignments

Before you begin: Ensure you have administrator privileges on your system.

In addition to reading the guide, you can also follow the steps in the videos:

For Windows

For macOS

There's a poll at the end of the article, please share your progress. Your feedback is highly appreciated.

So, let's begin!

1. Install Visual Studio Code (VS Code)

VS Code will be the primary editor for development.

Windows & macOS

1. Go to the VS Code download page: https://code.visualstudio.com/
2. Download the installer for your OS:
   • Windows: .exe file
   • macOS: .dmg file
3. Run the installer and follow the prompts.
4. (Windows only): During installation, check the box for "Add to PATH".
5. Verify installation:

• Open a terminal (Command Prompt, PowerShell, or macOS Terminal)
• Run:

code --version

• You should see the version number.

2. Install Git

Git is required for version control, cloning, and managing code repositories.

Windows

1. Download the latest version from: https://git-scm.com/downloads
2. Run the installer:
   • Choose "Use Git from the Windows Command Prompt".
   • Keep the default settings and finish the installation.
3. Verify installation:

git --version

macOS

1. Open Terminal and run:

git --version

If Git is not installed, macOS will prompt you to install Command Line Tools. Follow the instructions.

3. Install Docker

Docker is required to run InterSystems IRIS for Health Community.

Windows

1.    Download Docker Desktop from: https://www.docker.com/products/docker-desktop
2.    Run the installer and follow the setup.
3.    Restart your computer after installation.
4.    Enable WSL 2 Backend (if prompted).
5.    Verify installation

Note well: Installing Docker requires admin privileges on your machine and at least one restart.

macOS

1.    Download Docker Desktop for Mac from: https://www.docker.com/products/docker-desktop
2.    Install it by dragging the Docker.app to the Applications folder.
3.    Open Docker from the Applications menu.

To ensure the Docker Desktop engine is running on Windows or macOS, follow these steps:

Start Docker Desktop

Windows: Open Docker Desktop from the Start menu. The Docker whale icon should appear in your system tray.

Mac: Launch Docker Desktop from the Applications folder. You’ll see the Docker whale icon in the menu bar once it’s running.

Wait for Initialization

Once you launch Docker Desktop, the engine may take a moment to start. Look for a status message indicating that Docker is “running” or “started.”

Verify via Terminal/Command Prompt:

Open a terminal (or Command Prompt/PowerShell on Windows) and run:

docker --version

or

docker info

Troubleshooting

If the engine isn’t running, try restarting Docker Desktop or check for any error messages in the Docker Desktop UI. Also, ensure your system meets Docker Desktop’s requirements. You may see confusing error messages that reference pipes in you try to build a Docker image without Docker desktop running.

4. Building the IRIS for Health image and Running It using Docker

Before we can start a Docker container running IRIS for Health Community (which includes our FHIR server), we must build it.

1. Clone the FHIR repository to a convenient directory on your file system. Open a terminal in VS code and clone this repository with the following command:

   git clone https://github.com/pjamiesointersystems/Dockerfhir.git

    
2. Navigate to that directory and open the folder in VS Code. Follow the directions in the readme file to build and run the container. One critical step is ensuring the base repository is available in your Docker store. You can do this through the command at the VS Code terminal:

   docker pull containers.intersystems.com/intersystems/irishealth-community:latest-em

   You should see confirmation after a few minutes.
3. Navigate to the directory in VS Code where you see the file docker-compose.yaml and then issue the command:

   docker-compose build 

   This will launch the build process, which may take as long as 10 minutes, during which time a complete FHIR repository is built and loaded with sample patients. 
4. After the build process is complete, launch the container with the command

   docker-compose up -d

   followed by

   docker ps

   You should see a container named **iris-fhir** running. If the container fails to start, check the logs:

   docker logs iris-fhir

    

5. Install VS Code REST Client Extension

This extension allows you to send FHIR API requests from VS Code.

1. Open VS Code.
2. Go to Extensions (Ctrl + Shift + X or Cmd + Shift + X on macOS).
3. Search for "REST Client". There are several REST Clients, please install this one:
4. Click Install.

6. Install Python

Python is required for FHIR-related programming tasks.

Windows

1.    Download Python from: https://www.python.org/downloads/
2.    Run the installer and check the box for "Add Python to PATH". You will need administrative credentials to make modifications to the Path
3.    Complete the installation.
4.    Verify installation:

python --version

macOS

1. Open Terminal and install Python via Homebrew:

   Brew install python

   If you don't have Homebrew, install it first:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    
2. Verify installation:

python3 --version

7. Install Jupyter Notebooks

Jupyter Notebooks are used for AI and FHIR, and FHIR SQL  assignments.

Windows & macOS

1. Open a terminal (Command Prompt, PowerShell, or macOS Terminal).
2. Install Jupyter using pip:

   pip install jupyter
   jupyter --version

    
3. Run Jupyter Notebook:

jupyter notebook

This will open Jupyter in your web browser.

8.  Validation

Run your container by navigating to your docker compose file in the shell. Execute the command 

docker compose up -d
docker ps

Access the IRIS Management Portal:

• Open your browser and go to: http://localhost:8080/csp/sys/UtilHome.csp
• Default credentials:

Username: _SYSTEM
Password: ISCDEMO

Access the FHIR API:

• Open your browser and go to: http://localhost:8080/csp/healthshare/demo/fhir/r4/metadata

Final Checks

Run these commands to verify all installations:

code --version       # VS Code
git --version        # Git
docker --version     # Docker
python --version     # Python
jupyter --version    # Jupyter

If everything works, you've successfully installed all the software above.

Troubleshooting

Thank you for your time. I look forward to reading your comments!