# Docker Integration

⚠️

We are in the process of deprecating this integration and shifting towards the Dev Containers specification. For more information about Dev Containers, see the [Dev Containers](/content/docs/learn/environment/devcontainers/index.html) page.

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)](https://podman.io/) to run the containers.

You can find an example of a sandbox that uses Docker [here (opens in a new tab)](/content/p/sandbox/docker-example-hsd8ke/index.html).

## Configuring Docker [Permalink for this section](/content/docs/learn/environment/docker#configuring-docker/index.html)

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.

⭑

For a step-by-step guide, check out our tutorial [Getting started with Docker](/content/docs/tutorial/getting-started-with-docker/index.html)

## How it works [Permalink for this section](/content/docs/learn/environment/docker#how-it-works/index.html)

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 [Permalink for this section](/content/docs/learn/environment/docker#configuring-docker-compose/index.html)

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.

.codesandbox/docker-compose.yml

```
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 [Permalink for this section](/content/docs/learn/environment/docker#configuring-what-to-run/index.html)

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)](/content/docs/learn/repositories/task/index.html), 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)](/content/docs/learn/repositories/tasks/index.html) page.

[Dev Containers](/content/docs/learn/environment/devcontainers "Dev Containers"/index.html) [Branch Protection](/content/docs/learn/environment/branch-protection "Branch Protection"/index.html)