#Basic image
<subtitle>How to define a base image for a template</subtitle>

## Create template

When creating a template, you can specify options:

```python
template = Template(
    file_context_path=".", # Customize file context path
    file_ignore_patterns=[".git", "node_modules"], # File patterns to ignore
)
```

**File Ignored**: The SDK automatically reads `.dockerignore` files and combines them with your `file_ignore_patterns`. Files matching these patterns will be excluded from uploading and hash calculations.

## Define base image

Each template starts with a base image that provides the foundation for your sandbox environment.

> UCloud Sandbox currently only supports Debian-based images. Your base image must be Debian or a Debian derivative (for example, `debian`, `ubuntu`, `python`, `node`). Alpine, RedHat-based and other non-Debian distributions are not supported.

### Predefined base image

Get common Ubuntu, Debian, Python, Node.js or Bun base images using convenience methods:

```python
template.from_ubuntu_image("22.04")  # ubuntu:22.04
template.from_debian_image("stable-slim")  # debian:stable-slim
template.from_python_image("3.13")  # python:3.13
template.from_node_image("lts")  # node:lts
template.from_bun_image("1.3")  # oven/bun:1.3
```

### Custom base image

Use any Docker image from Docker Hub or other registries:

```python
template.from_image("custom-image:latest")
```

### Default UCloud Sandbox base image

Use the default UCloud Sandbox base image, which is preconfigured for a sandbox environment:

```python
template.from_base_image() # Use the default base image
```

### Build from existing template

Extend your team or organization’s existing templates:

```python
template.from_template("my-template") # Your team's template
template.from_template("acme/other-template") # Complete namespace reference
```

> The base image method can only be called once per template. Subsequent calls will throw an error.

## Parse existing Dockerfile

Convert an existing Dockerfile to template format using `from_dockerfile()`:

```python
dockerfile_content = """
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl
WORKDIR /app
COPY . .
ENV NODE_ENV=production
ENV PORT=3000
USER appuser
"""

template = (
    Template()
    .from_dockerfile(dockerfile_content)
    .set_start_cmd("npm start", wait_for_timeout(5_000))
)
```

### Dockerfile command support

| Directives | Support | Behavior |
| :---                 |    :----:  | :---                                                                                              |
| `FROM` | ✓ | Set base image |
| `RUN` | ✓ | Convert to `run_cmd()` |
| `COPY` / `ADD` | ✓ | Convert to `copy()` |
| `WORKDIR` | ✓ | Convert to `set_workdir()` |
| `USER` | ✓ | Convert to `set_user()` |
| `ENV` | ✓ | Convert to `set_envs()`; support `ENV key=value` and `ENV key value` formats |
| `CMD` / `ENTRYPOINT` | ✓ | Convert to `set_start_cmd()`, ready command has a 20 second timeout |
| `EXPOSE` | ✗ | Skip (not supported) |
| `VOLUME` | ✗ | Skip (not supported) |

> Multi-stage Dockerfile is not supported.