Full Setup Guide - Openwater Community

What This Guide Covers

A complete setup from zero → validated contributor environment

✔ System requirements & prerequisites

✔ Docker & local Python environments

✔ Repo structure & workflows

✔ Testing, validation, and linting

✔ Hardware + firmware setup (optional)

✔ Common issues & recovery steps

1. System Requirements

macOS, Linux, or Windows 10+
Python 3.10+
Git (latest)
Docker Desktop (recommended)
8GB RAM minimum (16GB preferred)

2. Clone the Repository

git clone https://github.com/OpenwaterHealth/OpenLIFU-python.git
cd OpenLIFU-python
git remote add upstream https://github.com/OpenwaterHealth/OpenLIFU-python.git
        

3. Environment Setup

Option A — Docker (Recommended)

docker pull openwaterhealth/dev-env:latest
docker run -it -v $(pwd):/workspace openwaterhealth/dev-env
        

Option B — Local Python

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
        

4. Verify Installation

pytest tests/
python examples/hello_world.py
        

All tests should pass. If not, see troubleshooting below.

5. Optional: Hardware & Firmware Setup

Install KiCad (PCB design)
FreeCAD or Fusion 360 (mechanical)
Clone relevant hardware repos

6. Troubleshooting

Dependency conflicts: Recreate venv or Docker image
Test failures: Ensure Python version matches repo
Docker permission issues: Restart Docker Desktop

Still stuck? Ask in #help on Discord.