Skip to content

Commit cc257e7

Browse files
dobracdobrac
committed
template sdk docs
1 parent f5da086 commit cc257e7

13 files changed

Lines changed: 1402 additions & 1 deletion

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.idea

‎docs.json‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,25 @@
3131
},
3232
{
3333
"group": "Custom sandbox",
34-
"pages": ["Quickstart", "Overview"]
34+
"pages": [
35+
"template/quickstart",
36+
"template/how-it-works",
37+
{
38+
"group": "Customization",
39+
"icon": "wand-magic-sparkles",
40+
"pages": [
41+
"template/customization/authentication",
42+
"template/customization/base-image",
43+
"template/customization/defining-template",
44+
"template/customization/start-ready-command",
45+
"template/customization/build",
46+
"template/customization/logging",
47+
"template/customization/error-handling"
48+
]
49+
},
50+
"template/examples",
51+
"template/migration"
52+
]
3553
},
3654
{
3755
"group": "Premade sandboxes",

‎template/customization/authentication.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: "Authentication"
3+
description: "How to login to the E2B Cloud"
4+
icon: "key"
5+
---
6+
7+
The SDK uses environment variables for authentication:
8+
9+
- `E2B_API_KEY`: Your E2B API key
10+
- `E2B_DOMAIN`: (Optional) E2B domain, defaults to 'e2b.dev'

‎template/customization/base-image.mdx‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: "Base Image"
3+
description: "How to define a base image for your template"
4+
icon: "1"
5+
---
6+
7+
### Creating template
8+
9+
When creating a template, you can specify options:
10+
11+
<CodeGroup dropdown>
12+
13+
```typescript
14+
const template = Template({
15+
fileContextPath: ".", // Custom file context path
16+
ignoreFilePaths: [".git", "node_modules"], // File patterns to ignore
17+
});
18+
```
19+
20+
```python
21+
template = Template(
22+
file_context_path=".", # Custom file context path
23+
ignore_file_paths=[".git", "node_modules"], # File patterns to ignore
24+
)
25+
```
26+
27+
</CodeGroup>
28+
29+
**File ignoring**: The SDK automatically reads `.dockerignore` files and combines them with your `ignoreFilePaths`. Files matching these patterns are excluded from uploads and hash calculations.
30+
31+
### Defining base image
32+
Choose from predefined base images or use custom ones:
33+
34+
<CodeGroup dropdown>
35+
36+
```typescript
37+
// Predefined base images
38+
template.fromUbuntuImage("lts"); // ubuntu:lts
39+
template.fromUbuntuImage("22.04"); // ubuntu:22.04
40+
template.fromDebianImage("slim"); // debian:slim
41+
template.fromDebianImage("bullseye"); // debian:bullseye
42+
template.fromPythonImage("3.13"); // python:3.13
43+
template.fromPythonImage("3.11"); // python:3.11
44+
template.fromNodeImage("lts"); // node:lts
45+
template.fromNodeImage("20"); // node:20
46+
47+
// Custom base image
48+
template.fromImage("custom-image:latest");
49+
50+
// Use default E2B base image
51+
template.fromBaseImage(); // e2bdev/base
52+
53+
// Parse existing Dockerfile
54+
const dockerfileContent = `
55+
FROM node:18-alpine
56+
WORKDIR /app
57+
COPY package*.json ./
58+
RUN npm ci --only=production
59+
COPY . .
60+
ENV NODE_ENV=production`;
61+
62+
template.fromDockerfile(dockerfileContent);
63+
```
64+
65+
```python
66+
# Predefined base images
67+
template.from_ubuntu_image("lts") # ubuntu:lts
68+
template.from_ubuntu_image("22.04") # ubuntu:22.04
69+
template.from_debian_image("slim") # debian:slim
70+
template.from_debian_image("bullseye") # debian:bullseye
71+
template.from_python_image("3.13") # python:3.13
72+
template.from_python_image("3.11") # python:3.11
73+
template.from_node_image("lts") # node:lts
74+
template.from_node_image("20") # node:20
75+
76+
# Custom base image
77+
template.from_image("custom-image:latest")
78+
79+
# Use default E2B base image
80+
template.from_base_image() # e2bdev/base
81+
82+
# Build from existing template
83+
template.from_template("existing-template-alias")
84+
85+
# Parse and build from Dockerfile
86+
template.from_dockerfile("Dockerfile")
87+
template.from_dockerfile("FROM ubuntu:22.04\nRUN apt-get update")
88+
```
89+
90+
</CodeGroup>
91+
92+
<Note>
93+
You can only call base image methods once per template. Subsequent calls will throw an error.
94+
</Note>
95+
96+
### Parsing existing Dockerfiles
97+
98+
Convert existing Dockerfiles to template format using `fromDockerfile()`:
99+
100+
<CodeGroup dropdown>
101+
102+
```typescript
103+
const dockerfileContent = `
104+
FROM ubuntu:22.04
105+
RUN apt-get update && apt-get install -y curl
106+
WORKDIR /app
107+
COPY . .
108+
ENV NODE_ENV=production
109+
ENV PORT=3000
110+
USER appuser`;
111+
112+
const template = Template()
113+
.fromDockerfile(dockerfileContent)
114+
.setStartCmd("npm start", waitForTimeout(5_000));
115+
```
116+
117+
```python
118+
dockerfile_content = """
119+
FROM ubuntu:22.04
120+
RUN apt-get update && apt-get install -y curl
121+
WORKDIR /app
122+
COPY . .
123+
ENV NODE_ENV=production
124+
ENV PORT=3000
125+
USER appuser
126+
"""
127+
128+
template = (
129+
Template()
130+
.from_dockerfile(dockerfile_content)
131+
.set_start_cmd("npm start", wait_for_timeout(5_000))
132+
)
133+
```
134+
135+
</CodeGroup>
136+
137+
#### Dockerfile instructions support
138+
139+
| Instruction | Supported | Behavior |
140+
| :--- | :----: | :--- |
141+
| `FROM` | <Icon icon="square-check" iconType="solid" /> | Sets base image |
142+
| `RUN` | <Icon icon="square-check" iconType="solid" /> | Converts to `runCmd()` / `run_cmd()` |
143+
| `COPY` / `ADD` | <Icon icon="square-check" iconType="solid" /> | Converts to `copy()` |
144+
| `WORKDIR` | <Icon icon="square-check" iconType="solid" /> | Converts to `setWorkdir()` / `set_workdir()` |
145+
| `USER` | <Icon icon="square-check" iconType="solid" /> | Converts to `setUser()` / `set_user()` |
146+
| `ENV` | <Icon icon="square-check" iconType="solid" /> | Converts to `setEnvs()` / `set_envs()`; supports both `ENV key=value` and `ENV key value` formats |
147+
| `CMD` / `ENTRYPOINT` | <Icon icon="square-check" iconType="solid" /> | Converts to `setStartCmd()` / `set_start_cmd()` with 20 seconds timeout as ready command |
148+
| `EXPOSE` | <Icon icon="xmark" iconType="solid" /> | Skipped (not supported) |
149+
| `VOLUME` | <Icon icon="xmark" iconType="solid" /> | Skipped (not supported) |
150+
151+
<Warning>
152+
Multi-stage Dockerfiles are not supported.
153+
</Warning>

‎template/customization/build.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: "Build"
3+
description: "How to build the template"
4+
icon: "hammer"
5+
---
6+
7+
Configure the build process:
8+
9+
<CodeGroup dropdown>
10+
11+
```typescript wrap
12+
Template.build(template, {
13+
alias: 'my-template', // Template alias (required)
14+
cpuCount: 2, // CPU cores
15+
memoryMB: 2048, // Memory in MB
16+
skipCache: false, // Configure cache skip (except for files)
17+
onBuildLogs: (logEntry) => console.log(logEntry.toString()), // Log callback receives LogEntry objects
18+
apiKey: 'your-api-key', // Override API key
19+
domain: 'your-domain', // Override domain
20+
})
21+
```
22+
23+
```python wrap
24+
Template.build(
25+
template,
26+
alias="my-template", # Template alias (required)
27+
cpu_count=2, # CPU cores
28+
memory_mb=2048, # Memory in MB
29+
skip_cache=False, # Configure cache skip (except for files)
30+
on_build_logs=lambda log_entry: print(log_entry), # Log callback receives LogEntry objects
31+
api_key="your-api-key", # Override API key
32+
domain="your-domain", # Override domain
33+
)
34+
```
35+
36+
</CodeGroup>

0 commit comments

Comments
 (0)