Fix: running Mesa in Docker with Schelling model

[AdamZh0u]

Summary

This pull request addresses issues with the existing Docker configuration, including missing dependencies and untested references to the mesa-examples repository. The updates ensure that the Mesa Schelling model runs correctly with Solara visualization in Docker on port 8765.

Bug / Issue

1. Missing Dependencies: The original Dockerfile did not install the mesa[all] package, which led to a solara not found error when attempting to run the docker compose.
2. Outdated Example Repository: The mesa-examples repository referenced in the original Dockerfile contains broken visualization modules and no longer includes the Schelling model.
3. Impact: Users were unable to run the Schelling model or any visualizations successfully using the provided Docker configuration.

Implementation

1. Dependencies Fix: Updated the Dockerfile to ensure mesa[all] is installed, which includes all necessary dependencies for Solara-based visualization.
2. Updated Model Reference:
   Replaced the mesa-examples repository reference with the mesa.examples module, specifically pointing to the built-in Schelling model:

ENV MODEL_DIR=/opt/mesa/mesa/examples/basic/schelling

Testing

1. Started the container using docker compose:

docker compose up -d

2. Verified that the Schelling model runs correctly with a working visualization.

[EwoutH]

Thanks for the PR. @projectmesa/maintainers or @AdamZh0u, can someone remind me what the use case for running Mesa in docker is exactly?

[wang-boyu]

Well, I guess the motivation is probably similar for many projects that use docker. You can get something up and running locally with one single docker run xxx or docker compose up, instead of having to 1) clone the repo, 2) set up a virtual environment, 3) install dependencies, and 4) finally run some models.

I do not have docker installed on my mac, because it's not as convenient as it is on ubuntu. There might be others who prefer to use docker.

[jackiekazil]

+1 to what @wang-boyu said.
Would love to hear from @AdamZh0u though as well.

[AdamZh0u]

Hi all,

Docker allows seamless deployment of Mesa applications across Windows, macOS, and Linux without any platform-specific differences. It ensures that all dependencies and environments are consistent, making it easier for users to get started quickly. And also, it provides a reproducible testing environment and an issue-reporting environment for troubleshooting.

In fact, on macOS, you can run an example model with just two simple commands:

brew install docker  
#cd mesa  
docker compose up -d  

This simplicity is particularly useful for users who want a hassle-free setup experience.

[wang-boyu]

In fact, on macOS, you can run an example model with just two simple commands:

brew install docker  
#cd mesa  
docker compose up -d  

Yes I know these commands. What I meant was that using docker on macOS involves Linux virtual machines, and I'm using an old Intel macbook that can be a bit slow. This was the case a few years ago and things could have changed. There may be new virtual tech on Apple Silicon macs that I'm not aware of.

Anyways this is just my own personal preference that do not apply to many others, and is not related to this PR. Sorry about the confusion.

[AdamZh0u]

No worries! I’ve actually started promoting Docker because I’m in a Python course with over 100 students, and their systems range from macOS 10 to Windows Home version. We’ve been using Docker, and it’s been working smoothly on almost all computers, making things easier for everyone.

[EwoutH]

I don’t see anything weird in the changeset, so no objections from my side. One small suggestion. I will leave final review and merge to a maintainer more familiar with (our) Docker.

[EwoutH]

I’ve actually started promoting Docker because I’m in a Python course with over 100 students

I would love to hear more about the course you’re teaching!

[tpike3]

Thanks @AdamZh0u I just asked for some comment updates

But like @EwoutH I would be curious to here about your class

[AdamZh0u]

Hi @EwoutH and @tpike3

Thanks for your interest! I’m involved in teaching a basic Python course this term, and Docker has been really helpful in making everything run smoothly across different systems. Next term, we’ll focus partly on ABM, so I’m exploring Mesa for this, trying to avoid the need to learn another language like NetLogo.

[wang-boyu]

LGTM. Merging now.

Thanks @AdamZh0u for your first contribution to Mesa!

[EwoutH]

@AdamZh0u Cool, thanks for sharing!

[SongshGeo]

No worries! I’ve actually started promoting Docker because I’m in a Python course with over 100 students, and their systems range from macOS 10 to Windows Home version. We’ve been using Docker, and it’s been working smoothly on almost all computers, making things easier for everyone.

Thanks for your contribution! @AdamZh0u

I just tested the docker, and it works well. One small comment on your message: I think it's also necessary to install docker-compose (maybe brew install docker-compose as well to run the demo.)

[wang-boyu]

Well, I guess the motivation is probably similar for many projects that use docker. You can get something up and running locally with one single docker run xxx or docker compose up, instead of having to 1) clone the repo, 2) set up a virtual environment, 3) install dependencies, and 4) finally run some models.

Just realized that I was wrong about this. Since the image is not released on docker hub, users still have to 1) clone the repo, 2) build the image, and 3) run docker compose

If our image is on docker hub, then it's possible to just do docker run xxx without having to clone the repo.

[SongshGeo]

Well, I guess the motivation is probably similar for many projects that use docker. You can get something up and running locally with one single docker run xxx or docker compose up, instead of having to 1) clone the repo, 2) set up a virtual environment, 3) install dependencies, and 4) finally run some models.

Just realized that I was wrong about this. Since the image is not released on docker hub, users still have to 1) clone the repo, 2) build the image, and 3) run docker compose

If our image is on docker hub, then it's possible to just do docker run xxx without having to clone the repo.

Yes. Fair enough. I vote to be involved in the docker hub in the future.

[AdamZh0u]

Hey! I think I need to make it clearer about two different workflows for using Mesa with Docker:

For Developers:
The current Docker workflow (as described in the README under Running Mesa in Docker) works great for someone who wants to contribute to the Mesa project. Just run docker compose up -d after cloning Mesa. Since we have build . pointing to the Dockerfile, you don't need to run docker build. The -e flag in pip3 install -e /opt/mesa[rec] means you can edit Mesa code and see changes immediately. You can also switch to your own models by changing MODEL_DIR in docker-compose.yml. This is really convenient for anyone interested in developing both ABM models and the Mesa project.

For Users:
If just using Mesa (not developing it) to build ABM models, a different approach might work better. We could publish Mesa images to DockerHub (though this would need maintenance), letting users develop their models in a pre-built Mesa environment. This would simplify the setup process significantly.

@SongshGeo Thanks for catching that! Just checked - actually this is already covered in the README where it lists Docker Compose installation as the first step.

[wang-boyu]

For Users: If just using Mesa (not developing it) to build ABM models, a different approach might work better. We could publish Mesa images to DockerHub (though this would need maintenance), letting users develop their models in a pre-built Mesa environment. This would simplify the setup process significantly.

@projectmesa/maintainers do we want this? Things needed from our end would be (feel free to add more if I miss any):

• update our documentation on how to use the image from docker hub directly
• update our release workflow to tag and release docker image with version number on each release, in addition to current pypi release
• future maintenance

This was previously discussed in #558 (comment). Interestinly there's an unmaintained Mesa image under CoMESE: https://hub.docker.com/r/comses/mesa.