mirror of
https://github.com/OpenHands/OpenHands.git
synced 2026-03-22 13:47:19 +08:00
update custom sandbox guide with nikolaik image consideration (#3197)
This commit is contained in:
@@ -4,22 +4,35 @@ sidebar_position: 6
|
||||
|
||||
# 💿 How to Create and Use a Custom Docker Sandbox
|
||||
|
||||
The default OpenDevin sandbox comes with a [minimal ubuntu configuration](https://github.com/OpenDevin/OpenDevin/blob/main/containers/sandbox/Dockerfile).
|
||||
The default OpenDevin sandbox comes with a [minimal ubuntu configuration](https://github.com/OpenDevin/OpenDevin/blob/main/containers/sandbox/Dockerfile).
|
||||
|
||||
Your use case may need additional software installed by default.
|
||||
|
||||
There are two ways you can do so:
|
||||
|
||||
1. Use an existing image from docker hub. For instance, if you want to have `nodejs` installed, you can do so by using the `node:20` image
|
||||
2. Creating your own custom docker image and using it
|
||||
|
||||
If you want to take the first approach, you can skip the `Create Your Docker Image` section.
|
||||
|
||||
For a more feature-rich environment, you might consider using pre-built images like **[nikolaik/python-nodejs](https://hub.docker.com/r/nikolaik/python-nodejs)**, which comes with both Python and Node.js pre-installed, along with many other useful tools and libraries, like:
|
||||
|
||||
- Node.js: 22.x
|
||||
- npm: 10.x
|
||||
- yarn: stable
|
||||
- Python: latest
|
||||
- pip: latest
|
||||
- pipenv: latest
|
||||
- poetry: latest
|
||||
- uv: latest
|
||||
|
||||
## Setup
|
||||
|
||||
Make sure you are able to run OpenDevin using the [Development.md](https://github.com/OpenDevin/OpenDevin/blob/main/Development.md) first.
|
||||
|
||||
## Create Your Docker Image
|
||||
To create a custom docker image, it must be debian/ubuntu based.
|
||||
|
||||
To create a custom docker image, it must be debian/ubuntu based.
|
||||
|
||||
For example, if we want OpenDevin to have access to the `node` binary, we would use the following Dockerfile:
|
||||
|
||||
@@ -34,7 +47,7 @@ RUN apt-get update && apt-get install -y
|
||||
RUN apt-get install -y nodejs
|
||||
```
|
||||
|
||||
Next build your docker image with the name of your choice, for example `custom_image`.
|
||||
Next build your docker image with the name of your choice, for example `custom_image`.
|
||||
|
||||
To do this you can create a directory and put your file inside it with the name `Dockerfile`, and inside the directory run the following command:
|
||||
|
||||
@@ -50,7 +63,7 @@ This will produce a new image called ```custom_image``` that will be available i
|
||||
|
||||
## Specify your sandbox image in config.toml file
|
||||
|
||||
OpenDevin configuration occurs via the top-level `config.toml` file.
|
||||
OpenDevin configuration occurs via the top-level `config.toml` file.
|
||||
|
||||
Create a `config.toml` file in the OpenDevin directory and enter these contents:
|
||||
|
||||
@@ -63,6 +76,7 @@ sandbox_container_image="custom_image"
|
||||
```
|
||||
|
||||
For `sandbox_container_image`, you can specify either:
|
||||
|
||||
1. The name of your custom image that you built in the previous step (e.g., `”custom_image”`)
|
||||
2. A pre-existing image from Docker Hub (e.g., `”node:20”` if you want a sandbox with Node.js pre-installed)
|
||||
|
||||
@@ -79,7 +93,7 @@ Congratulations!
|
||||
|
||||
The relevant code is defined in [ssh_box.py](https://github.com/OpenDevin/OpenDevin/blob/main/opendevin/runtime/docker/ssh_box.py) and [image_agnostic_util.py](https://github.com/OpenDevin/OpenDevin/blob/main/opendevin/runtime/docker/image_agnostic_util.py).
|
||||
|
||||
In particular, ssh_box.py checks the config object for ```config.sandbox_container_image``` and then attempts to retrieve the image using [get_od_sandbox_image](https://github.com/OpenDevin/OpenDevin/blob/main/opendevin/runtime/docker/image_agnostic_util.py#L72) which is defined in image_agnostic_util.py.
|
||||
In particular, `ssh_box.py` checks the config object for ```config.sandbox_container_image``` and then attempts to retrieve the image using [get_od_sandbox_image](https://github.com/OpenDevin/OpenDevin/blob/main/opendevin/runtime/docker/image_agnostic_util.py#L72) which is defined in image_agnostic_util.py.
|
||||
|
||||
When first using a custom image, it will not be found and thus it will be built (on subsequent runs the built image will be found and returned).
|
||||
|
||||
@@ -109,6 +123,7 @@ dockerfile_content = (
|
||||
## Troubleshooting / Errors
|
||||
|
||||
### Error: ```useradd: UID 1000 is not unique```
|
||||
|
||||
If you see this error in the console output it is because OpenDevin is trying to create the opendevin user in the sandbox with a UID of 1000, however this UID is already being used in the image (for some reason). To fix this change the sandbox_user_id field in the config.toml file to a different value:
|
||||
|
||||
```toml
|
||||
@@ -122,7 +137,7 @@ sandbox_user_id="1001"
|
||||
|
||||
### Port use errors
|
||||
|
||||
If you see an error about a port being in use or unavailable, try deleting all running Docker Containers (run `docker ps` and `docker rm` relevant containers) and then re-running ```make run```
|
||||
If you see an error about a port being in use or unavailable, try deleting all running Docker Containers (run `docker ps` and `docker rm` relevant containers) and then re-running ```make run``` .
|
||||
|
||||
## Discuss
|
||||
|
||||
|
||||
Reference in New Issue
Block a user