Docker Integration

CodeSandbox has a native integration with Docker. This means that you can use Docker to install any package you want, including databases and new languages. Additionally, with the Docker integration you have root access within your terminals, so you can install packages from the terminal as well.

While we call this a Docker integration, we use rootless Podman (opens in a new tab) to run the containers.

You can find an example of a sandbox that uses Docker here (opens in a new tab).

Configuring Docker

To enable the Docker integration, you need to create a new file in .codesandbox/Dockerfile, this is the Dockerfile that will be used to build the container for the environment. Whenever you open a new terminal, you will be inside this container.

When this file exists, we will also make sure to automatically rebuild the container when the VM boots.

How it works

With CodeSandbox, we allow you to share your sandbox with others easily by sharing a link. Because of this, we make sure to create a new Linux user for every user that opens the sandbox.

This means that we also have to run containers on a per-user basis. For every user, we create a rootless container using Podman based on the Dockerfile configuration in the sandbox/repo. While the user outside of the container does not have root, inside the container they do have root access.

Whenever you open a terminal, we check if there is a container running for your user. If it's not running, we start it, and we then start an exec session inside the container.

Every container does share the network, files and processes between each-other. This allows you to run an HTTP server in one container, and connect to it from another container.

Configuring Docker Compose

To run additional services using the Docker Compose integration, you can create a file .codesandbox/docker-compose.yml. This file will be used to run docker compose up at a branch/sandbox startup. This feature can be used to run other services needed in the development environment like databases, proxies, etc.

For the Docker Compose integration to automatically start the compose command, the environment should be configured with .codesandbox/Dockerfile as explained above.

To access these services, you have to expose the ports in the docker-compose.yml file using the ports attribute of the service.

services:
    nginx:
        image: nginx
        ports:
            - 8080:80

You can use Docker commands in the terminal to exec into the containers started with this method. To manage the running containers with the docker compose command, either cd into the .codesandbox directory or specify the location of the docker-compose.yml file using docker compose -f .codesandbox/docker-compose.yml.

You do not have to run or configure a task to run docker compose. The .codesandbox/docker-compose.yml file will be automatically detected and docker-compose up will be run at branch/sandbox startup.

Configuring what to run

Normally, you would define in your Dockerfile what the container should run when it boots. Since CodeSandbox has its own task management system (opens in a new tab), we don't run commands defined in Dockerfile defined as CMD.

Instead, we recommend to create a .codesandbox/tasks.json, and define your starting process from there. You can automatically do this by opening the command palette (CMD/Ctrl + Shift + P) and selecting "Generate task configuration". You can learn more about task configuration in the Tasks (opens in a new tab) page.