diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 76299bf9..4342cb7a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,4 +14,7 @@ we can discuss its feasibility.
 Search is essentially a fractal of interesting
 problems, so even if you don't have an idea,
 just a skillset (really any), odds are there's
-something interesting I could point you to.
\ No newline at end of file
+something interesting I could point you to.
+
+Make sure you check out the [ide-configuration guide](doc/ide-configuration.md)
+to get your IDE set up quickly and easily.
\ No newline at end of file
diff --git a/README.md b/README.md
index 6a53f817..253eb6c9 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ Before compiling, it's necessary to run [⚙️ run/setup.sh](run/setup.sh).
 This will download supplementary model data that is necessary to run the code. 
 These are also necessary to run the tests. 
 
+If you wish to hack on the code, check out [📄 doc/ide-configuration.md](doc/ide-configuration.md).
 
 ## Hardware Requirements
 
diff --git a/doc/ide-configuration.md b/doc/ide-configuration.md
new file mode 100644
index 00000000..d900a323
--- /dev/null
+++ b/doc/ide-configuration.md
@@ -0,0 +1,39 @@
+It is strongly recommended you use [IntelliJ IDEA](https://www.jetbrains.com/idea/download), as it's the IDE the 
+project is developed in. Use the free Community Edition if you don't have (or want) a commercial license.  It is 
+more than capable. 
+
+It may be possible to use other IDEs, but the code uses a relatively advanced build system and some IDEs get very 
+confused by this.
+
+## JDK 21 (+preview)
+The codebase uses Java 21 preview features.  You may need to configure your IDE to use Java 21, or set the language version to 21 (preview).  Usually it's 
+smart enough to figure it out, but sometimes it's not.
+
+Go to `File > Project Structure > Project`, ensure it's set to use a JDK21 SDK, and set the Project SDK to 21 (preview).
+
+![Project Structure](ide_docs/java21.png)
+
+## Lombok, other plugins
+
+The codebase uses Lombok. To prevent the IDE from finding fault with the code, you need to install the Lombok plugin.
+
+You may also want protobuf and docker plugins, although this is optional.
+
+## Running
+
+It makes life a lot easier to set up a docker-compose run configuration in IntelliJ.  Configure it like this:
+
+![Docker Compose Run Configuration](ide_docs/runconfig.png)
+
+Select the docker-compose file from your install directory, and then add a 'Before Launch' gradle task
+to build the project.  It should run 'assemble docker'.  Then you can just run the configuration and
+it will build and run the project (e.g. Shift+F10).
+
+## Optional: Use Scopes
+
+Since the project is sprawling with submodules, it can help sanity to use IDE scopes. 
+In IntelliJ, you can click the little cog in the top of the side-bar (1), then select `Edit Scopes` (2).
+Create a scope with the components you want to work with, and then it shows up in the drop-down (3).
+
+![IDE Scopes](ide_docs/scopes.png)
+