Merge branch 'main' into lporoli/ticket-770-docs-2

.github/workflows/push-docs.yml

@@ -29,6 +29,12 @@ jobs:
       - name: Append changelog
         run: cat CHANGELOG.md >> docs/docs/changelog.md
         if: github.ref == 'refs/heads/main' || steps.docs-diff.outputs.DOCS_CHANGED != 0
+      - name: Append Go README
+        run: cat api/golang/README.md >> docs/docs/sdk-examples/go-sdk-example.md
+        if: github.ref == 'refs/heads/main' || steps.docs-diff.outputs.DOCS_CHANGED != 0
+      - name: Append TS README
+        run: cat api/typescript/README.md >> docs/docs/sdk-examples/ts-sdk-example.md
+        if: github.ref == 'refs/heads/main' || steps.docs-diff.outputs.DOCS_CHANGED != 0
       - name: Yarn Install
         run: yarn --cwd ./docs --frozen-lockfile install
         if: github.ref == 'refs/heads/main' || steps.docs-diff.outputs.DOCS_CHANGED != 0

api/golang/README.md

@@ -0,0 +1,72 @@
+# Kurtosis Go SDK
+
+This guide provides instructions and code snippets to help you get started with the Kurtosis Go SDK. It enables you to create and manage enclaves programmatically, without having to rely on the Kurtosis Enclave Manager (UI) or the Kurtosis CLI.
+
+The main way to interact with objects from the Kurtosis ecosystem is by getting its *context*. There are three main contexts:
+1. **KurtosisContext**: contains methods for interacting with Kurtosis Engine, allowing manipulation of enclaves.
+2. **EnclaveContext**: contains methods for interacting with an enclave, allowing execution of Starlark scripts.
+3. **ServiceContext**: contains methods for interacting with a service, allowing inspecting its details.
+
+This guide will also help you create and get these contexts.
+
+## Setting Up
+
+To use the Kurtosis Go SDK, you need to add it as a dependency to your Go module. You can do this with the following `go get` command:
+
+```console
+$ go get github.com/kurtosis-tech/kurtosis/api/golang
+```
+
+Please ensure that you have a running Kurtosis Engine instance before executing your code. You can check the status of the Kurtosis Engine using the following command:
+
+```console
+$ kurtosis engine status
+```
+
+Make note of the Engine's version and status information.
+
+## Creating an Enclave
+
+The first step is to obtain a Kurtosis Context, which represents a Kurtosis instance in your Go code:
+
+```go
+kurtosisCtx, err := kurtosis_context.NewKurtosisContextFromLocalEngine()
+```
+
+Next, you can use the Kurtosis Context to create an enclave, which will provide an Enclave Context for managing the enclave:
+
+```go
+enclaveName := "my-enclave"
+enclaveCtx, err := kurtosisCtx.CreateEnclave(ctx, enclaveName)
+```
+
+## Configure for Starlark Runs
+
+Using the Enclave Context, you can perform actions like adding services using Starlark scripts:
+
+```go
+starlarkRunConfig := starlark_run_config.NewRunStarlarkConfig()
+starlarkScript := `
+def run(plan):
+    serviceConfig := ServiceConfig{
+        Image: "httpd",
+    }
+    plan.AddService(name: "my-service", config: serviceConfig)
+`
+starlarkRunResult, err := enclaveCtx.RunStarlarkScriptBlocking(ctx, starlarkScript, starlarkRunConfig)
+```
+## Interacting with services
+After adding a service, you can interact with it by obtaining a service context and running commands:
+
+```go
+serviceCtx, err := enclaveCtx.GetServiceContext("my-service")
+code, output, err := serviceCtx.ExecCommand([]string{"ls"})
+```
+
+For ephemeral enclaves, such as those used in end-to-end testing, you can destroy the created enclave:
+
+```go
+err := kurtosisCtx.DestroyEnclave(ctx, enclaveName)
+```
+
+These instructions should help you get started with using the Kurtosis Go SDK to create and manage enclaves for your projects. If you need further assistance or ahve questions, please open a [Github Discussion](https://github.com/kurtosis-tech/kurtosis/discussions/categories/q-a) or ping us in [Discord](https://discord.com/invite/HUapYX9RvV).

api/typescript/README.md

@@ -0,0 +1,90 @@
+# Kurtosis Typescript SDK
+
+This guide provides instructions and code snippets to help you get started with the Kurtosis Typescript SDK. It enables you to create and manage enclaves programmatically, without having to rely on the Kurtosis Enclave Manager (UI) or the Kurtosis CLI.
+
+The main way to interact with objects from the Kurtosis ecosystem is by getting its *context*. There are three main contexts:
+1. **KurtosisContext**: contains methods for interacting with Kurtosis Engine, allowing manipulation of enclaves.
+2. **EnclaveContext**: contains methods for interacting with an enclave, allowing execution of Starlark scripts.
+3. **ServiceContext**: contains methods for interacting with a service, allowing inspecting its details.
+
+This guide will also help you create and get these contexts.
+
+## Setting Up
+
+To use the Kurtosis Typescript SDK, you need to add it as a dependency to your NPM package. You can do this with the following `npm i` command:
+
+```console
+$ npm i kurtosis-sdk
+```
+
+Please ensure that you have a running Kurtosis Engine instance before executing your code. You can check the status of the Kurtosis Engine using the following command:
+
+```console
+$ kurtosis engine status
+```
+
+Make note of the Engine's version and status information.
+
+## Creating an Enclave
+
+The first step is to obtain a Kurtosis Context, which represents a Kurtosis instance in your Typescript code:
+
+```typescript
+const newKurtosisContextResult = await KurtosisContext.newKurtosisContextFromLocalEngine()
+if(newKurtosisContextResult.isErr()) {
+    // Check for error
+}
+const kurtosisContext = newKurtosisContextResult.value;
+```
+
+Next, you can use the Kurtosis Context to create an enclave, which will provide an Enclave Context for managing the enclave:
+
+```typescript
+const enclaveName = "my-enclave"
+const createEnclaveResult = await kurtosisContext.createEnclave();
+if(createEnclaveResult.isErr()) {
+    // Check for error
+}
+const enclaveContext = createEnclaveResult.value;
+```
+
+## Configure for Starlark Runs
+
+Using the Enclave Context, you can perform actions like adding services using Starlark scripts:
+
+```typescript
+const starlarkRunConfig = new StarlarkRunConfig(
+StarlarkRunConfig.WithSerializedParams(params)
+)
+const starlarkScript = `
+def run(plan):
+    serviceConfig := ServiceConfig{
+        Image: "httpd",
+    }
+    plan.AddService(name: "my-service", config: serviceConfig)
+`
+return enclaveContext.runStarlarkScriptBlocking(starlarkScript, starlarkRunConfig)
+```
+## Interacting with services
+After adding a service, you can interact with it by obtaining a service context and running commands:
+
+```typescript
+const getServiceCtxResult = await enclaveCtx.getServiceContext("my-service")
+if(getServiceCtxResult.isErr()) {
+    // Check for error
+}
+const serviceContext = getServiceCtxResult.value;
+const command = ["ls"]
+serviceContext.execCommand(command)
+```
+
+For ephemeral enclaves, such as those used in end-to-end testing, you can destroy the created enclave:
+
+```typescript
+const destroyEnclaveResponse = await kurtosisContext.destroyEnclave(enclaveName)
+if(destroyEnclaveResponse.isErr()) {
+    // Check for error
+}
+```
+
+These instructions should help you get started with using the Kurtosis Typescript SDK to create and manage enclaves for your projects. If you need further assistance or ahve questions, please open a [Github Discussion](https://github.com/kurtosis-tech/kurtosis/discussions/categories/q-a) or ping us in [Discord](https://discord.com/invite/HUapYX9RvV).

api/typescript/package.json

@@ -25,9 +25,9 @@
     "author": "Kurtosis Technologies Inc <[email protected]> (https://www.kurtosistech.com/)",
     "license": "Apache-2.0",
     "bugs": {
-        "url": "https://github.com/kurtosis-tech/kurtosis-sdk/issues"
+        "url": "https://github.com/kurtosis-tech/kurtosis/issues"
     },
-    "homepage": "https://github.com/kurtosis-tech/kurtosis-sdk#readme",
+    "homepage": "https://github.com/kurtosis-tech/kurtosis",
     "engines": {
         "node": ">=16.13.0"
     },

container-engine-lib/lib/backend_impls/docker/docker_manager/docker_manager.go

@@ -19,6 +19,7 @@ import (
 	"github.com/docker/docker/pkg/jsonmessage"
 	"github.com/docker/docker/pkg/stdcopy"
 	"github.com/docker/go-connections/nat"
+	kurtosis_sdk_version "github.com/kurtosis-tech/kurtosis/api/golang/kurtosis_version"
 	"github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_impls/docker/docker_kurtosis_backend/consts"
 	docker_manager_types "github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_impls/docker/docker_manager/types"
 	"github.com/kurtosis-tech/kurtosis/container-engine-lib/lib/backend_interface/objects/compute_resources"
@@ -304,7 +305,7 @@ func (manager *DockerManager) ListUnusedImages(ctx context.Context) ([]types.Ima
 			continue
 		}
 		for _, tag := range image.RepoTags {
-			if strings.Contains(tag, kurtosisTagPrefix) && containsSemVer(tag) {
+			if strings.Contains(tag, kurtosisTagPrefix) && containsSemVer(tag) && !strings.Contains(tag, kurtosis_sdk_version.KurtosisVersion) {
 				unusedImages = append(unusedImages, image)
 			}
 		}

docs/docs/sdk-examples/go-sdk-example.md

@@ -0,0 +1,5 @@
+---
+title: Go SDK Example
+sidebar_label: Go
+slug: /go-sdk-example
+---

docs/docs/sdk-examples/ts-sdk-example.md

@@ -0,0 +1,5 @@
+---
+title: TypeScript SDK Example
+sidebar_label: TypeScript
+slug: /ts-sdk-example
+---

docs/sidebars.js

@@ -35,6 +35,15 @@ const sidebars = {
                 {type: 'autogenerated', dirName: 'guides'}
             ]
         },
+        {
+            type: 'category',
+            label: 'SDK Examples',
+            collapsed: true,
+            items: [
+                'sdk-examples/go-sdk-example',
+                'sdk-examples/ts-sdk-example'
+            ]
+        },
         {
             type: 'category',
             label: 'API Reference',