Run Docker in a Celesto sandbox

You can run apps and test your projects with Docker inside a Celesto sandbox. Your tools and files stay in the sandbox, giving you a separate place to try changes. Docker packages an app and the software it needs into a Docker image. A container is a running copy of a Docker image. You install Docker inside the sandbox, then use its commands there.

Before you start

Install the Celesto command-line tool. For cloud computers, also sign in.
Use a fresh Ubuntu sandbox with the current Celesto software and image. Celesto starts Docker’s background service automatically after you install it.
Allow internet access to Ubuntu package servers and Docker Hub, the service that stores the example images.
Give Docker room for package downloads and images. For the local example, start with 2048 MiB of memory and 4096 MiB of disk space. MiB is a unit of memory and storage size. For cloud computers, use Standard size or larger.

Install Docker and run a container

Open your sandbox

Run the commands in the tab for your setup on your own machine.

Local sandbox
Cloud computer

Create an Ubuntu sandbox named docker-demo and open its terminal:

celesto sandbox create --name docker-demo --os ubuntu --memory 2048 --disk-size 4096
celesto sandbox shell docker-demo

The terminal runs inside your sandbox as root, the user with permission to install software.

Create a Standard computer, which includes a 30 GB disk with space for Docker images:

celesto computer create --template coding-agent --cpus 2 --memory 4096

Copy the computer name from the output. Run the following command, replacing einstein with that name:

celesto computer ssh einstein

Inside the computer, open a shell with permission to install software:

sudo -i

Run the remaining commands in this section inside the sandbox.

Install Docker

Download the package list, then install Docker and its network tools:

apt-get update -o APT::Update::Error-Mode=any && \
  DEBIAN_FRONTEND=noninteractive apt-get install -y docker.io iptables

Wait for the installation to finish successfully. Celesto detects Docker and starts its daemon, the background service that runs containers.

Wait for Docker to be ready

This check waits up to two minutes. If startup fails, it prints the Docker log to help you find the cause.

sh -eu <<'SH'
for attempt in $(seq 1 60); do
  if docker info >/dev/null 2>&1; then
    echo "Docker is ready"
    exit 0
  fi
  sleep 2
done
echo "Docker did not become ready. Check the log below." >&2
tail -n 80 /var/log/celesto-docker.log >&2 || true
exit 1
SH

Continue when you see Docker is ready.

Run your first container

Download and run Docker’s small verification image:

docker run --rm hello-world

The output includes Hello from Docker!. This confirms Docker can download an image and run a container inside your sandbox.

The --rm flag removes the container after it finishes. Docker keeps the downloaded image so you can reuse it. See Docker’s guide to running containers for more options.

Run Docker from Python

Use the Python SDK (software development kit) to create a local Ubuntu sandbox, install Docker, and run a container from your program. Run this script on your own machine after completing Celesto installation. Save it as docker_demo.py:

docker_demo.py

from celesto import Celesto


def run_checked(sandbox, command, timeout):
    result = sandbox.run(command, timeout=timeout)
    if result.exit_code != 0:
        raise RuntimeError(
            f"Command failed: {command}\n{result.stdout}\n{result.stderr}"
        )
    return result.stdout


with Celesto(os="ubuntu", memory=2048, disk_size=4096) as sandbox:
    run_checked(
        sandbox,
        "apt-get update -qq -o APT::Update::Error-Mode=any && "
        "DEBIAN_FRONTEND=noninteractive apt-get install -y -qq docker.io iptables",
        timeout=600,
    )
    run_checked(
        sandbox,
        "for attempt in $(seq 1 60); do "
        "if docker info >/dev/null 2>&1; then exit 0; fi; "
        "sleep 2; done; "
        "tail -n 80 /var/log/celesto-docker.log >&2 || true; exit 1",
        timeout=180,
    )
    print(run_checked(sandbox, "docker run --rm hello-world", timeout=180))

Run the script:

python docker_demo.py

The output includes Hello from Docker!. The script checks each command’s exit code and gives package installation and image downloads extra time to finish.

Troubleshoot Docker in a Celesto sandbox

Run these checks inside the sandbox with the same permissions you used during installation.

Docker cannot connect to its background service

Run the readiness check again, then read the startup log:

tail -n 80 /var/log/celesto-docker.log

Celesto manages the service through its guest agent, a small program inside the sandbox. Use a fresh Ubuntu sandbox with the current image if an older sandbox has no Docker startup log. The setup above uses Celesto’s service management rather than systemctl.

Package installation or image downloads fail

Check whether the sandbox can find the package server and Docker Hub:

getent ahostsv4 archive.ubuntu.com
getent ahostsv4 registry-1.docker.io

Each command should print IP addresses. If a lookup fails, check internet access and outbound network rules for your local sandbox or cloud computer. Then retry the failed installation or download command.

Docker runs out of disk space or memory

Check available disk space and Docker’s storage use:

df -h /
docker system df

Create a larger sandbox when your Docker images or builds need more space. For cloud computers, compare computer sizes. Increase memory when programs run out of memory. Docker images and containers use the sandbox’s own resources.

Next steps

Forward a local sandbox port to reach a container’s web app from your machine. Publish the container port to the sandbox with Docker’s -p flag first.
Publish a cloud computer port to give a container’s web app an HTTPS address.
Build custom sandbox images when you want to choose the tools available when a sandbox starts.
Build a Celesto Cloud custom template to start every cloud computer with your packages preinstalled.

Get Started

Features

Guides

Architecture

Operations

Run Docker in a Celesto sandbox

Before you start

Install Docker and run a container

Run Docker from Python

Troubleshoot Docker in a Celesto sandbox

Next steps

​Before you start

​Install Docker and run a container

​Run Docker from Python

​Troubleshoot Docker in a Celesto sandbox

​Next steps

Before you start

Install Docker and run a container

Run Docker from Python

Troubleshoot Docker in a Celesto sandbox

Next steps