-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Create sdk page * basic structure * updates * lots of context * update * add download support * Updates from Christian * small fixes * small url fix * update links * fix faq --------- Co-authored-by: Danilo Woznica <danilowoz@gmail.com> Co-authored-by: Ives van Hoorne <Ives.v.h@gmail.com> Co-authored-by: Christian Alfoni <christianalfoni@gmail.com> Co-authored-by: Necoline <necoline@codesandbox.io>
- Loading branch information
5 people
authored
Dec 12, 2024
1 parent
04f1cf2
commit 5e9cf3a
Showing
31 changed files
with
1,726 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| /// <reference types="next" /> | ||
| /// <reference types="next/image-types/global" /> | ||
|
|
||
| // NOTE: This file should not be edited | ||
| // see https://nextjs.org/docs/basic-features/typescript for more information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,14 +1,20 @@ | ||
| { | ||
| "learn": { | ||
| "title": "Documentation", | ||
| "title": "Editor", | ||
| "type": "page" | ||
| }, | ||
| "sdk": { | ||
| "title": "SDK", | ||
| "type": "page" | ||
| }, | ||
| "tutorial": { | ||
| "title": "Tutorial", | ||
| "type": "page" | ||
| "type": "page", | ||
| "display": "hidden" | ||
| }, | ||
| "faq": { | ||
| "title": "FAQ", | ||
| "type": "page" | ||
| "type": "page", | ||
| "display": "hidden" | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| { | ||
| "index": "Introduction", | ||
| "use-cases": "Use Cases", | ||
| "pricing": "Pricing", | ||
| "contact": { | ||
| "title": "Contact Us", | ||
| "href": "https://codesandbox.io/support#form", | ||
| "newWindow": true | ||
| }, | ||
|
|
||
| "-- api-reference": { | ||
| "type": "separator", | ||
| "title": "API Reference" | ||
| }, | ||
| "sandboxes": "Sandboxes", | ||
| "filesystem": "File System", | ||
| "shells": "Shells", | ||
| "ports": "Ports & Previews", | ||
| "tasks": "Tasks & Setup", | ||
| "specs": "VM Specs", | ||
|
|
||
| "-- resources": { | ||
| "type": "separator", | ||
| "title": "Resources" | ||
| }, | ||
| "snapshot-library": "Snapshot Library", | ||
| "snapshot-builder": "Snapshot Builder", | ||
| "environment": "Environment", | ||
| "docker": "Docker & Docker Compose", | ||
| "persistence": "Persistence", | ||
| "fork": "Fork", | ||
| "faq": "FAQ" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,148 @@ | ||
| --- | ||
| title: Docker & Dev Containers | ||
| description: Learn how to configure your sandbox environment using Dev Containers. | ||
| --- | ||
|
|
||
| import { Callout } from 'nextra-theme-docs' | ||
|
|
||
| # Dev Containers | ||
|
|
||
| CodeSandbox natively supports the [Dev Containers specification](https://containers.dev/), allowing you to customize your sandbox, install system-level dependencies, and run additional services. | ||
|
|
||
| ## Configuration | ||
|
|
||
| To configure your sandbox environment, create a `.devcontainer/devcontainer.json` file inside the root of the sandbox: | ||
|
|
||
| ```json | ||
| { | ||
| "name": "Node.js", | ||
| "image": "mcr.microsoft.com/devcontainers/javascript-node:18", | ||
| "features": { | ||
| "ghcr.io/devcontainers/features/python:1": {} | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| In this example, we're installing Node v18 as base, with Python on top using Dev Container Features. | ||
|
|
||
| Alternatively, you can use a `Dockerfile` to build the Docker image when the sandbox boots: | ||
|
|
||
| ```json | ||
| { | ||
| "name": "Node.js", | ||
| "build": { | ||
| "dockerfile": "./Dockerfile" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Using Dev Containers in the SDK | ||
|
|
||
| When creating a sandbox, all shells will automatically run inside the Docker container specified in the Dev Container configuration. | ||
|
|
||
| ```ts | ||
| const sandbox = await sdk.sandbox.create({ | ||
| template: "node" // Template with Dev Container configuration | ||
| }); | ||
|
|
||
| await sandbox.shells.run("node --version"); | ||
| ``` | ||
|
|
||
| Since we use memory snapshots, the Docker container will already be running when you run your shell. | ||
|
|
||
| ## Docker Compose | ||
|
|
||
| You can run additional services using Docker Compose by adding a `docker-compose.yml` configuration to your Dev Container: | ||
|
|
||
| ```json | ||
| { | ||
| "name": "Full Stack App", | ||
| "dockerComposeFile": "docker-compose.yml", | ||
| "service": "app", | ||
| "workspaceFolder": "/workspace" | ||
| } | ||
| ``` | ||
|
|
||
| With a corresponding `docker-compose.yml`: | ||
|
|
||
| ```yaml | ||
| services: | ||
| app: | ||
| image: mcr.microsoft.com/devcontainers/javascript-node:18 | ||
| command: sleep infinity | ||
|
|
||
| db: | ||
| image: postgres:14 | ||
| ports: | ||
| - 5432:5432 | ||
| environment: | ||
| POSTGRES_PASSWORD: password | ||
| ``` | ||
| ### Using Docker Compose in the SDK | ||
| The SDK will automatically start all services defined in your Docker Compose configuration: | ||
| ```ts | ||
| const sandbox = await sdk.sandbox.create({ | ||
| template: "fullstack" // Template with Dev Container configuration | ||
| }); | ||
|
|
||
| // Wait for all services to be ready | ||
| await sandbox.setup.waitForFinish(); | ||
|
|
||
| // You can now connect to the services | ||
| const portInfo = await sandbox.ports.waitForPort(5432); | ||
| console.log(`Database available at: ${portInfo.hostname}:${portInfo.port}`); | ||
| ``` | ||
| ## Examples | ||
| ### Full-Stack Development Environment | ||
| Here's an example of setting up a full-stack development environment with Node.js and PostgreSQL: | ||
| ```ts | ||
| const sandbox = await sdk.sandbox.create({ | ||
| template: "fullstack" | ||
| }); | ||
|
|
||
| // Wait for environment setup | ||
| const progress = await sandbox.setup.waitForFinish(); | ||
| if (progress.state !== "FINISHED") { | ||
| throw new Error("Environment setup failed"); | ||
| } | ||
|
|
||
| // Start the development server | ||
| const devTask = await sandbox.tasks.runTask("dev"); | ||
|
|
||
| // Wait for both the app and database to be ready | ||
| const [appPort, dbPort] = await Promise.all([ | ||
| sandbox.ports.waitForPort(3000), | ||
| sandbox.ports.waitForPort(5432) | ||
| ]); | ||
|
|
||
| console.log(` | ||
| App running at: ${appPort.getPreviewUrl()} | ||
| Database available at: ${dbPort.hostname}:${dbPort.port} | ||
| `); | ||
| ``` | ||
|
|
||
| ### Custom Environment with System Dependencies | ||
|
|
||
| Example of a sandbox that needs specific system packages: | ||
|
|
||
| ```ts | ||
| const sandbox = await sdk.sandbox.create({ | ||
| template: "custom-env" | ||
| }); | ||
| // The Dev Container will install required packages during setup | ||
| await sandbox.setup.waitForFinish(); | ||
| // Run a command that uses the installed packages | ||
| const result = await sandbox.shells.run("ffmpeg -version"); | ||
| console.log(result.output); | ||
| ``` | ||
|
|
||
| For more information about Dev Container configuration options and features, visit the [Dev Container specification](https://containers.dev/). Also, take a look at our [snapshot builder](/sdk/snapshot-builder.mdx) to learn how to create efficient snapshots with preloaded Docker images. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| --- | ||
| title: Environment | ||
| description: Learn how the CodeSandbox SDK's environment works. | ||
| --- | ||
|
|
||
| import { Callout } from 'nextra-theme-docs' | ||
|
|
||
| # Environment | ||
|
|
||
| Sandboxes on CodeSandbox are backed by a [Firecracker](https://firecracker-microvm.github.io/) microVM, within the VM we run a rootless Docker container based on a [Dev Container](https://containers.dev/) configuration (specified in the `.devcontainer/devcontainer.json` file). | ||
|
|
||
| ## Booting a Sandbox | ||
|
|
||
| Whenever we boot a sandbox from scratch, we'll: | ||
|
|
||
| 1. Start the Firecracker VM | ||
| 2. Create a default user (called `pitcher-host`) | ||
| 3. (optional) Build the Docker image specified in the `.devcontainer/devcontainer.json` file | ||
| 4. Start the Docker container | ||
| 5. Mount the `/project/sandbox` directory as a volume inside the Docker container | ||
|
|
||
| We run an agent inside the VM that the SDK connects to. Via an RPC protocol you can then interact with the sandbox. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| --- | ||
| title: FAQs | ||
| description: Find answers to common questions about the CodeSandbox SDK. | ||
| --- | ||
|
|
||
| import { Callout } from 'nextra-theme-docs' | ||
|
|
||
| # FAQ | ||
|
|
||
| ## Do I need a CodeSandbox workspace to be able to use the SDK? | ||
|
|
||
| Yes. You need a CodeSandbox API key to use CodeSandbox SDK, which you can get by [creating a CodeSandbox account](https://codesandbox.io/signin). | ||
|
|
||
| ## How can I revoke my API key? | ||
|
|
||
| To revoke an API key, go to the "Permissions" tab of your [Workspace Settings](https://codesandbox.io/t/permissions) and click the respective token under "API Access". Then, click "Remove Token" from the bottom of that modal. | ||
|
|
||
| ## I have hit a rate limit - what should I do? | ||
|
|
||
| Please subscribe to a CodeSandbox plan that includes the most suitable rate limit for you. In case you're on our Builder plan already, please [contact us](https://webforms.pipedrive.com/f/72gS7iXoP8qjL8Ku9HZQcN5UKpUpZkgKRCjhbqREjCOYyBgzrCKCr7Mys5AyczOHBN) to discuss an Enterprise plan. | ||
|
|
||
| ## Can I change the specs of the VMs? | ||
|
|
||
| Currently, we only allow changing the default specs for all VMs created with the SDK. You can change | ||
|
|
||
| We are also SOC 2 Type II compliant. | ||
|
|
||
| ## Is it possible to self-host CodeSandbox SDK? | ||
|
|
||
| No, for now we don't provide a self-host option. | ||
|
|
||
| ## Are there any SDK rate limits? | ||
|
|
||
| Yes. The SDK has rate limits on concurrent VMs, number of requests per hour, and number of sandboxes created per hour. These limits vary depending on the CodeSandbox plan, as explained on our [Pricing page](https://codesandbox.io/pricing). | ||
|
|
||
| ## Can I use the same CodeSandbox plan for SDK and non-SDK usage? | ||
|
|
||
| Yes. Your CodeSandbox plan will allow you to use both, so you can leverage the SDK for programmatic sandbox creation, while still allowing your team to use CodeSandbox for their development. | ||
|
|
||
| ## Does the CodeSandbox SDK use CodeSandbox Sandboxes or Devboxes? | ||
|
|
||
| While the SDK code only mentions "sandbox", the actual environments that it uses are officially called "Devboxes" (which use VMs). So, if you need more details about these VMs, please always refer to "[Devbox](/learn/devboxes/overview)" section of the CodeSandbox documentation and pricing. |
Oops, something went wrong.