diff --git a/docs/docs/explanations/architecture.md b/docs/docs/explanations/architecture.md index 769abd5a19..5d93d1afa2 100644 --- a/docs/docs/explanations/architecture.md +++ b/docs/docs/explanations/architecture.md @@ -111,5 +111,5 @@ For day-to-day operation, we also provide [a CLI][cli-reference]. This is simply [enclave-ls-reference]: ../cli-reference/enclave-ls.md [enclave-inspect-reference]: ../cli-reference/enclave-inspect.md [enclave-rm-reference]: ../cli-reference/enclave-rm.md -[quickstart]: ../get-started/quickstart-consumer.md +[quickstart]: ../get-started/quickstart.md [sdk-reference]: ../runtime-sdk-reference.md diff --git a/docs/docs/explanations/why-kurtosis-starlark.md b/docs/docs/explanations/why-kurtosis-starlark.md index 10d36c9c2b..8674e0d92f 100644 --- a/docs/docs/explanations/why-kurtosis-starlark.md +++ b/docs/docs/explanations/why-kurtosis-starlark.md @@ -53,4 +53,4 @@ So far, both our users and our team have been very happy with our decision to go [reusable-environment-definitions]: ./reusable-environment-definitions.md [starlark-differences-with-python]: https://bazel.build/rules/language#differences_with_python -[quickstart]: ../get-started/quickstart-consumer.md +[quickstart]: ../get-started/quickstart.md diff --git a/docs/docs/explanations/why-we-built-kurtosis.md b/docs/docs/explanations/why-we-built-kurtosis.md index 41bcfa4829..c88fcafb03 100644 --- a/docs/docs/explanations/why-we-built-kurtosis.md +++ b/docs/docs/explanations/why-we-built-kurtosis.md @@ -23,4 +23,4 @@ In our vision, a developer should have a single platform for prototyping, testin To read more about our beliefs on reusable environments, [go here][reusable-environment-definitions]. To get started using Kurtosis, see [the quickstart][quickstart]. [reusable-environment-definitions]: ./reusable-environment-definitions.md -[quickstart]: ../get-started/quickstart-consumer.md +[quickstart]: ../get-started/quickstart.md diff --git a/docs/docs/get-started/home.md b/docs/docs/get-started/home.md index e6c1f07928..51bb62eee2 100644 --- a/docs/docs/get-started/home.md +++ b/docs/docs/get-started/home.md @@ -6,7 +6,7 @@ sidebar_position: 1 hide_table_of_contents: true --- ## What is Kurtosis? -[Kurtosis](https://www.kurtosis.com) is a composable build system for multi-container environments. Kurtosis makes it easier for developers to set up environments that require dynamic setup logic (e.g. passing IPs or runtime-generated data between services) or programmatic data seeding. +[Kurtosis](https://www.kurtosis.com) is a composable build system for multi-container test environments. Kurtosis makes it easier for developers to set up test environments that require dynamic setup logic (e.g. passing IPs or runtime-generated data between services) or programmatic data seeding. Go [here](../explanations/why-we-built-kurtosis.md) to learn more about what inspired us to build Kurtosis. @@ -14,7 +14,7 @@ Go [here](../explanations/why-we-built-kurtosis.md) to learn more about what ins Developers usually set up these types of dynamic environments with a free-form scripting language like bash or Python, interacting with the Docker CLI or Docker Compose. Kurtosis is designed to make these setups easier to maintain and reuse in different test scenarios. -In Kurtosis, containerized environments have these properties: +In Kurtosis, test environments have these properties: - Environment-level portability: the entire test environment always runs the same way, regardless of the host machine - Composability: environments can be composed and connected together without needing to know the inner details of each setup - Parameterizability: environments can be parameterized, so that they're easy to modify for use across different test scenarios @@ -37,7 +37,7 @@ In Kurtosis, containerized environments have these properties: ## Try out Kurtosis now -Try Kurtosis now with our [quickstart](./quickstart-consumer.md). +Try Kurtosis now with our [quickstart](./quickstart.md). :::info If you have questions, need help, or simply want to learn more, schedule a live session with us, go [here](https://calendly.com/d/zgt-f2c-66p/kurtosis-onboarding). diff --git a/docs/docs/get-started/quickstart-consumer.md b/docs/docs/get-started/quickstart-consumer.md deleted file mode 100644 index c10f3c59f5..0000000000 --- a/docs/docs/get-started/quickstart-consumer.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: Quickstart - Run a Package -sidebar_label: Quickstart - Run a Package -slug: /quickstart-run-a-package -toc_max_heading_level: 2 -sidebar_position: 1 ---- - -Introduction ------------- - -Welcome to the [Kurtosis][homepage] quickstart! This guide takes ~5 minutes and will walk you through how to use a Kurtosis package to spin up a distributed system over Docker. Specifically, you will use the [eth2-package][eth2-package] to bootstrap and start-up a private Ethereum testnet. - -Kurtosis is a composable build system for reproducible test environments and serve two types of users: the author of an environment definition, referred to as a [Kurtosis package][packages-reference], and the consumer or user of the environment definition. This quickstart is intended to put you in the shoes of the consumer - someone who needs a quick and easy way to get a production-like test environment to develop and test changes quicker for your distributed system. A separate guide is [available here][how-to-set-up-postgres-guide] to introduce you to the world of Kurtosis package authoring and how one might define and build an environment with Kurtosis for themselves or for their team. - -Our mission is to make building distributed systems as easy as building a single server application. The first problem we aim to solve on our journey to achieve this mission is to bridge the author-consumer divide for environment definitions. For this reason, we built Kurtosis. Further reading about what Kurtosis is and what problems Kurtosis aims to solve, is available on our [introduction page][homepage]. To learn more about our motivations behind starting Kurtosis, go [here][why-we-built-kurtosis-explanation]. - -This guide is in a "code along" format, which means you are expected to follow the code examples and run the Kurtosis CLI commands on your local machine. Everything you run in this guide is free, public, and does not contain any sensitive data. - -:::tip What You'll Do -1. Install Kurtosis and Docker, if you haven't already. -2. Configure how you want your distributed system to be spun up, using parameters that are passed in at runtime. -3. Run a single command to spin up your network. -::: - -
TL;DR Version - -This quickstart is in a "code along" format. You can also dive straight into running the end results and exploring the code too. - -**Open the Playground: [Start](https://gitpod.io/?autoStart=true&editor=code#https://github.com/kurtosis-tech/eth2-package)** - -Click on the "New Workspace" button! You don't have to worry about the Context URL, Editor or Class. It's all pre-configured for you. - -
- -If you ever get stuck, every Kurtosis command accepts a `-h` flag to print helptext. If that doesn't help, you can get in touch with us in our [Discord server](https://discord.gg/jJFG7XBqcY) or on [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose)! - -Install dependencies --------------------- -Before you get started, make sure you have: -* [Installed Docker](https://docs.docker.com/get-docker/) and ensure the Docker Daemon is running on your machine (e.g. open Docker Desktop). You can quickly check if Docker is running by running: `docker image ls` from your terminal to see all your Docker images. -* [Installed Kurtosis](https://docs.kurtosis.com/install/#ii-install-the-cli) or [upgrade Kurtosis to the latest version](https://docs.kurtosis.com/upgrade). You can check if Kurtosis is running using the command: `kurtosis version`, which will print your current Kurtosis engine version and CLI version. - -Define how your system should look like ---------------------------------------- - -Kurtosis environment definitions, referred to here on as [Kurtosis packages][packages-reference], support parameterization out of the box. This means your teams or your communities can leverage the same package with different configurations for their specific use-case, eliminating the need to maintain different Bash scripts or `docker-compose.yml` files per use of the environment definition. - -You're now going to create a file to house the parameters that you will pass in at runtime when your system starts up. Check out the README for the [eth2-package][eth2-package] to see the full list of configuration options and flags available for use. - -Create a file titled: `network_params.json` in your home directory, populate it with the below contents, and save your file: -```json -{ - "participants": [{ - "el_client_type": "geth", - "el_client_image": "ethereum/client-go:latest", - "el_client_log_level": "", - "el_extra_params": [], - "cl_client_type": "lighthouse", - "cl_client_image": "sigp/lighthouse:latest", - "cl_client_log_level": "", - "beacon_extra_params": [], - "validator_extra_params": [], - "builder_network_params": null, - "count": 2 - }], - "network_params": { - "network_id": "3151908", - "deposit_contract_address": "0x4242424242424242424242424242424242424242", - "seconds_per_slot": 12, - "slots_per_epoch": 32, - "num_validator_keys_per_node": 64, - "preregistered_validator_keys_mnemonic": "giant issue aisle success illegal bike spike question tent bar rely arctic volcano long crawl hungry vocal artwork sniff fantasy very lucky have athlete", - "deneb_for_epoch": 500 - }, - "verifications_epoch_limit": 5, - "global_client_log_level": "info", - "mev_type": "none", - // When set to true, Kurtosis will bootstrap and start a Grafana and Prometheus instance alongside other network monitoring tools. - "launch_additional_services": false, -} -``` -The arrays in the `participant` object enables you to define the specific Ethereum client types and respective image tags you want to use in your network, alongside any extra parameters for the validator, beacon, or builder as well as some useful flags for the verbosity of log lines. In this example you'll be using the `latest` image tags for the Geth and Lighthouse clients and have specified `2` nodes to be spun up. - -Meanwhile, the `network_params` object defines the specific parameters for the network, including traits like the `network_id`, `seconds_per_slot`, and `slots_per_epoch`. - -Lastly, there are a few fields that let you, as a consumer, define the log verbosity level and whether or not you'd like additional services and infrastructure to be spun up with your distributed system. In this example, you will not spin up extra monitoring tools (via the `launch_additional_service` field) or Proposer-Builder Seperation (PBS) infrastructure (via the `mev_type` field). - -Spin up your system! --------------------- -Great! You're now ready to bring up your own network. Simply run: -```console -kurtosis run --enclave eth-network github.com/kurtosis-tech/eth2-package "$(cat ~/network_params.json)" -``` - -Kurtosis will then begin to spin up your private Ethereum testnet by interpreting the instructions in the Kurtosis package, validating the plan to ensure there are no conflicts or obvious errors, and then finally executes the plan (read more about multi-phase runs [here][multi-phase-runs-reference]). Kurtosis first spins up an isolated, ephemeral environment on your machine called an [enclave][enclaves-reference] where all the services and [files artifacts][files-artifacts-reference] for your system will reside in. Then, those services will be bootstrapped and required files generated to start up the system. - -You will see a stream of text get printed in your terminal as Kurtosis begins to generate genesis files, configure the Ethereum nodes, launch a Grafana and Prometheus instance, and bootstrap the network together. In ~2 minutes, you should see the following output at the end: - -```console -INFO[2023-08-28T13:05:31-04:00] ==================================================== -INFO[2023-08-28T13:05:31-04:00] || Created enclave: eth-network || -INFO[2023-08-28T13:05:31-04:00] ==================================================== -Name: eth-network -UUID: e1a41707ee8e -Status: RUNNING -Creation Time: Mon, 28 Aug 2023 13:04:53 EDT - -========================================= Files Artifacts ========================================= -UUID Name -a662c7c74685 1-lighthouse-geth-0-63 -6421d80946ce 2-lighthouse-geth-64-127 -a1ad3962f148 cl-genesis-data -730d585d5ec5 el-genesis-data -c1e452ad7e53 genesis-generation-config-cl -284cde692102 genesis-generation-config-el -b03a5b7b9340 geth-prefunded-keys -013f5d8708fa prysm-password - -========================================== User Services ========================================== -UUID Name Ports Status -202516f0ff8f cl-1-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:65191 RUNNING - metrics: 5054/tcp -> http://127.0.0.1:65192 - tcp-discovery: 9000/tcp -> 127.0.0.1:65193 - udp-discovery: 9000/udp -> 127.0.0.1:64174 -66bdfbd6c066 cl-1-lighthouse-geth-validator http: 5042/tcp -> 127.0.0.1:65236 RUNNING - metrics: 5064/tcp -> http://127.0.0.1:65237 -b636913d4d03 cl-2-lighthouse-geth http: 4000/tcp -> http://127.0.0.1:65311 RUNNING - metrics: 5054/tcp -> http://127.0.0.1:65312 - tcp-discovery: 9000/tcp -> 127.0.0.1:65310 - udp-discovery: 9000/udp -> 127.0.0.1:51807 -e296eefa1710 cl-2-lighthouse-geth-validator http: 5042/tcp -> 127.0.0.1:65427 RUNNING - metrics: 5064/tcp -> http://127.0.0.1:65428 -4df1beb0203d el-1-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:65081 RUNNING - rpc: 8545/tcp -> 127.0.0.1:65079 - tcp-discovery: 30303/tcp -> 127.0.0.1:65078 - udp-discovery: 30303/udp -> 127.0.0.1:55146 - ws: 8546/tcp -> 127.0.0.1:65080 -581a0fe5de77 el-2-geth-lighthouse engine-rpc: 8551/tcp -> 127.0.0.1:65130 RUNNING - rpc: 8545/tcp -> 127.0.0.1:65132 - tcp-discovery: 30303/tcp -> 127.0.0.1:65131 - udp-discovery: 30303/udp -> 127.0.0.1:49475 - ws: 8546/tcp -> 127.0.0.1:65129 -4980884d9bb0 prelaunch-data-generator-cl-genesis-data RUNNING -3174baf6a6ff prelaunch-data-generator-el-genesis-data RUNNING -``` - -Thats it! You now have a full, private Ethereum blockchain on your local machine. - -The first section that gets printed contains some basic metadata about the enclave that was spun up. This includes the name of the enclave `eth-network`, its [Resource Idenfitier](https://docs.kurtosis.com/concepts-reference/resource-identifier/), your enclave's status, and the time it was created. - -Next, you'll see a section dedicated to [Files Artifacts](https://docs.kurtosis.com/concepts-reference/files-artifacts/), which are Kurtosis' first-class representation of data inside your enclave, stored as compressed TGZ files. You'll notice there are configuration files for the nodes, grafana, and prometheus as well as private keys for pre-funded accounts and genesis-related data. These files artifacts were generated and used by Kurtosis to start the network and abstracts away the complexities and overhead that come with generating validator keys and getting genesis and node config files produced and mounted to the right containers yourself. - -Lastly, there is a section called `User Services` which display the number of services (running in Docker containers) that make up your network. You will notice that there are 2 Ethereum nodes comprised of 3 services each (an EL client, a CL beacon client, and a CL validator client) and 2 genesis data generators for each the CL and EL. Each of these services are running in Docker containers inside your local enclave & Kurtosis has automatically mapped each container port to your machine's ephemeral ports for seamless interaction with the services running in your enclave. - -Why Kurtosis packages - from a consumer's perspective ------------------------------------------------------ -Kurtosis was built to make building distributed systems as easy as building a single server app. Kurtosis aims to achieve this by bridging the environment definition author-consumer divide. Tactically, this means making it dead simple for a consumer (like yourself) to pick up an environment definition, spin it up, and deploy it the way you want, where you want - all without needing to know specialized knowledge about how the system works or how to use Kubernetes or Docker. - -Specifically, this guide showed you: -- ***The power of parameterizability***: as a consumer of the environment definition, having both the knowledge and means to configure the system to spin up the way you need it is incredibly valuable - a big reason why Kurtosis packages are meant to be parameterized. In this guide, you created the `network_params.json` file which contained your preferences for how the network should look and passed them in to Kurtosis with relative ease. The author of the package need only define the arguments and flags available for a consumer, and Kurtosis handles the rest once those are passed in at runtime. -- ***Portable and easy to wield***: a major contributor to the author-consumer divide comes from the knowledge gap between the author and consumer regarding the infrastruture and tools needed to instantiate a system. Understanding how Kubernetes works, what Bash script to use at which step, and working with Docker primitivies are all pain points we believe Kurtosis alleviates. In this guide, you installed Kurtosis and ran a single command to get your system up and running. This same command will work anywhere, over Docker or on Kubernetes, locally or on remote infrastructure. We believe this portability and ease of use are requirements for bridging the author-consumer divide. - -There are many other reasons why we believe Kurtosis is the right tool for bridging the author-consumer divide. Check out the [next guide][how-to-set-up-postgres-guide] to experience the workflow for a package author and how Kurtosis improves the developer experience for an environment definition author. - -Conclusion ----------- -And that's it - you've successfully used Kurtosis to instantiate a full, private Ethereum testnet - one of the most complex distributed systems in todays time. - -Let's review. In this tutorial you have: - -1. Installed Kurtosis and Docker. -2. Configure how your system should look like, using parameters that are passed in at runtime. -3. Run a single command to spin up your network. -4. Reviewed how package consumers benefit from using environment definitions written for Kurtosis. - -:::tip -In this short guide, you went through the workflow that a Kurtosis package consumer would experience. It is strongly encouraged that you check out the [next guide][how-to-set-up-postgres-guide] where you will set up a Postgres database and an API server to as a package author. -::: - -This was still just an introduction to Kurtosis. To dig deeper, visit other sections of our docs where you can read about [what Kurtosis is][homepage], understand the [architecture][architecture-explanation], and hear our [inspiration for starting Kurtosis][why-we-built-kurtosis-explanation]. - -To learn more about how Kurtosis is used, we encourage you to check out our [`awesome-kurtosis` repository][awesome-kurtosis-repo], where you will find real-world examples of Kurtosis in action, including: -- How to run a simple [Go test][go-test-example] or [Typescript test][ts-test-example] against the app we just built -- The [Ethereum package][ethereum-package], used by the Ethereum Foundation, which can be used to set up local testnets -- A parameterized package for standing up an [n-node Cassandra cluster with Grafana and Prometheus][cassandra-package-example] out-of-the-box -- The [NEAR package][near-package] for local dApp development in the NEAR ecosystem - -Finally, we'd love to hear from you. Please don't hesitate to share with us what went well, and what didn't, using `kurtosis feedback` to file an issue in our [Github](https://github.com/kurtosis-tech/kurtosis/issues/new/choose) or to [chat with our cofounder, Kevin](https://calendly.com/d/zgt-f2c-66p/kurtosis-onboarding). - -Lastly, feel free to [star us on Github](https://github.com/kurtosis-tech/kurtosis), [join the community in our Discord](https://discord.com/channels/783719264308953108/783719264308953111), and [follow us on Twitter](https://twitter.com/KurtosisTech)! - -Thank you for trying our quickstart. We hope you enjoyed it. - - - - -[installing-kurtosis-guide]: ../guides/installing-the-cli.md -[installing-docker-guide]: ../guides/installing-the-cli.md#i-install--start-docker -[upgrading-kurtosis-guide]: ../guides/upgrading-the-cli.md -[how-to-set-up-postgres-guide]: quickstart-author.md - - -[architecture-explanation]: ../explanations/architecture.md -[enclaves-reference]: ../concepts-reference/enclaves.md -[services-explanation]: ../explanations/architecture.md#services -[reusable-environment-definitions-explanation]: ../explanations/reusable-environment-definitions.md -[why-we-built-kurtosis-explanation]: ../explanations/why-we-built-kurtosis.md -[how-do-imports-work-explanation]: ../explanations/how-do-kurtosis-imports-work.md -[why-multi-phase-runs-explanation]: ../explanations/why-multi-phase-runs.md - - - -[cli-reference]: /cli/ -[kurtosis-run-reference]: ../cli-reference/run.md -[kurtosis-clean-reference]: ../cli-reference/clean.md -[kurtosis-enclave-inspect-reference]: ../cli-reference/enclave-inspect.md -[kurtosis-files-upload-reference]: ../cli-reference/files-upload.md -[kurtosis-feedback-reference]: ../cli-reference/feedback.md -[kurtosis-twitter]: ../cli-reference/twitter.md -[starlark-reference]: ../concepts-reference/starlark.md - - -[request-reference]: ../starlark-reference/plan.md#request -[exec-reference]: ../starlark-reference/plan.md#exec - - -[multi-phase-runs-reference]: ../concepts-reference/multi-phase-runs.md -[kurtosis-yml-reference]: ../concepts-reference/kurtosis-yml.md -[packages-reference]: ../concepts-reference/packages.md -[runnable-packages-reference]: ../concepts-reference/packages.md#runnable-packages -[locators-reference]: ../concepts-reference/locators.md -[plan-reference]: ../concepts-reference/plan.md -[future-references-reference]: ../concepts-reference/future-references.md -[files-artifacts-reference]: ../concepts-reference/files-artifacts.md - - - -[awesome-kurtosis-repo]: https://github.com/kurtosis-tech/awesome-kurtosis -[data-package-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/data-package -[data-package-example-main.star]: https://github.com/kurtosis-tech/awesome-kurtosis/blob/main/data-package/main.star -[data-package-example-seed-tar]: https://github.com/kurtosis-tech/awesome-kurtosis/blob/main/data-package/dvd-rental-data.tar -[cassandra-package-example]: https://github.com/kurtosis-tech/cassandra-package -[go-test-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/quickstart/go-test -[ts-test-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/quickstart/ts-test -[eth2-package]: https://github.com/kurtosis-tech/eth2-package/ - - -[homepage]: home.md -[kurtosis-managed-packages]: https://github.com/kurtosis-tech?q=in%3Aname+package&type=all&language=&sort= -[wild-kurtosis-packages]: https://github.com/search?q=filename%3Akurtosis.yml&type=code -[bazel-github]: https://github.com/bazelbuild/bazel/ -[starlark-github-repo]: https://github.com/bazelbuild/starlark -[postgrest]: https://postgrest.org/en/stable/ -[ethereum-package]: https://github.com/kurtosis-tech/eth2-package -[waku-package]: https://github.com/logos-co/wakurtosis -[near-package]: https://github.com/kurtosis-tech/near-package -[iterm]: https://iterm2.com/ -[vscode-plugin]: https://marketplace.visualstudio.com/items?itemName=Kurtosis.kurtosis-extension diff --git a/docs/docs/get-started/quickstart-author.md b/docs/docs/get-started/quickstart.md similarity index 89% rename from docs/docs/get-started/quickstart-author.md rename to docs/docs/get-started/quickstart.md index da1543334f..af4e6a9026 100644 --- a/docs/docs/get-started/quickstart-author.md +++ b/docs/docs/get-started/quickstart.md @@ -1,17 +1,16 @@ --- -title: Quickstart - Write a Package -sidebar_label: Quickstart - Write a Package -slug: /quickstart-write-a-package +title: Quickstart +sidebar_label: Quickstart +slug: /quickstart toc_max_heading_level: 2 -sidebar_position: 2 --- Introduction ------------ -Welcome! This guide will walk you through how a [Kurtosis package][packages-reference] author would define their environment definition using Kurtosis. This guide takes ~15 minutes and will walk you through setting up a basic Postgres database and an API server to automate the loading of data. This guide is in a "code along" format, meaning we assume the user will be following the code examples and running Kurtosis CLI commands on your local machine. Everything you run in this guide is free, public, and does not contain any sensitive data. +Welcome to the [Kurtosis][homepage] quickstart! This guide takes ~15 minutes and will walk you through building a basic Kurtosis package. This guide is in a "code along" format, meaning we assume the user will be following the code examples and running Kurtosis CLI commands on your local machine. Everything you run in this guide is free, public, and does not contain any sensitive data. -This quickstart is meant for authors of environment definitions and is a continuation of the [quickstart for package consumers][quickstart-consumers]. While you may choose to do the quickstarts in any order, it is recommended that you start with the [quickstart for package consumers][quickstart-consumers] before this one. Doing both is highly recommended to understand how Kurtosis aims to solve the environment definition author-consumer divide to make building distributed systems as easy as building single server applications. +For a quick read on what Kurtosis is and what problems Kurtosis aims to solve, our [introduction page][homepage] will be a great starting point, alongside our [motivations behind starting Kurtosis][why-we-built-kurtosis-explanation]. :::tip What You'll Do @@ -19,7 +18,6 @@ This quickstart is meant for authors of environment definitions and is a continu - Seed your database with test data using task sequencing - Connect an API server to your database using dynamic service dependencies - Parameterize your application setup in order to automate loading data into your API -- Make your Kurtosis package consumable by any user :::
TL;DR Version @@ -47,7 +45,7 @@ Hello, World First, create and `cd` into a directory to hold the project you'll be working on: ```bash -mkdir kurtosis-postgres && cd kurtosis-postgres +mkdir kurtosis-quickstart && cd kurtosis-quickstart ``` Next, create a Starlark file called `main.star` inside your new directory with the following contents (more on Starlark in the "Review" section coming up soon): @@ -71,23 +69,23 @@ autocmd FileType *.star setlocal filetype=python Finally, [run][kurtosis-run-reference] the script (we'll explain enclaves in the "Review" section): ```bash -kurtosis run --enclave kurtosis-postgres main.star +kurtosis run --enclave quickstart main.star ``` Kurtosis will work for a bit, and then deliver you the following result: ```text INFO[2023-03-15T04:27:01-03:00] Creating a new enclave for Starlark to run inside... -INFO[2023-03-15T04:27:05-03:00] Enclave 'kurtosis-postgres' created successfully +INFO[2023-03-15T04:27:05-03:00] Enclave 'quickstart' created successfully > print msg="Hello, world" Hello, world Starlark code successfully run. No output was returned. INFO[2023-03-15T04:27:05-03:00] =================================================== -INFO[2023-03-15T04:27:05-03:00] || Created enclave: kurtosis-postgres || +INFO[2023-03-15T04:27:05-03:00] || Created enclave: quickstart || INFO[2023-03-15T04:27:05-03:00] =================================================== -Name: kurtosis-postgres +Name: quickstart UUID: a78f2ce1ca68 Status: RUNNING Creation Time: Wed, 15 Mar 2023 04:27:01 -03 @@ -142,22 +140,22 @@ def run(plan, args): ) ``` -Before you run the above command, remember that you still have the `kurtosis-postgres` enclave hanging around from the previous section. To [clean up the previous enclave][kurtosis-clean-reference] and execute our new `main.star` file above, run: +Before you run the above command, remember that you still have the `quickstart` enclave hanging around from the previous section. To [clean up the previous enclave][kurtosis-clean-reference] and execute our new `main.star` file above, run: ```bash -kurtosis clean -a && kurtosis run --enclave kurtosis-postgres main.star +kurtosis clean -a && kurtosis run --enclave quickstart main.star ``` :::info The `--enclave` flag is used to specify the enclave to use for that particular run. If one doesn't exist, Kurtosis will create an enclave with that name - which is what is happening here. Read more about `kurtosis run` [here][kurtosis-run-reference]. -This entire "clean-and-run" process will be your dev loop for the rest of the kurtosis-postgres as you add more services and operations to our distributed application. +This entire "clean-and-run" process will be your dev loop for the rest of the quickstart as you add more services and operations to our distributed application. ::: -You'll see in the result that the `kurtosis-postgres` enclave now contains a Postgres instance: +You'll see in the result that the `quickstart` enclave now contains a Postgres instance: ```text -Name: kurtosis-postgres +Name: quickstart UUID: a30106a0bb87 Status: RUNNING Creation Time: Tue, 14 Mar 2023 20:23:54 -03 @@ -204,10 +202,10 @@ By contrast, Kurtosis Starlark scripts can use data as a first-class primitive a Let's see it in action, and we'll explain what's happening afterwards. -First, create a file called `kurtosis.yml` next to your `main.star file` (in your working directory, `kurtosis-postgres`) with the following contents: +First, create a file called `kurtosis.yml` next to your `main.star file` (in your working directory, `kurtosis-quickstart`) with the following contents: ```bash -name: "github.com/john-snow/kurtosis-postgres" +name: "github.com/john-snow/kurtosis-quickstart" ``` Then update your `main.star` with the following: @@ -260,7 +258,7 @@ def run(plan, args): Now, run the following to see what happens: ```bash -kurtosis clean -a && kurtosis run --enclave kurtosis-postgres . +kurtosis clean -a && kurtosis run --enclave quickstart . ``` (Notice you are using `.` instead of `main.star`) @@ -270,15 +268,15 @@ The output should also look more interesting as your plan has grown bigger: ```text INFO[2023-03-15T04:34:06-03:00] Cleaning enclaves... INFO[2023-03-15T04:34:06-03:00] Successfully removed the following enclaves: -60601dd9906e40d6af5f16b233a56ae7 kurtosis-postgres +60601dd9906e40d6af5f16b233a56ae7 quickstart INFO[2023-03-15T04:34:06-03:00] Successfully cleaned enclaves INFO[2023-03-15T04:34:06-03:00] Cleaning old Kurtosis engine containers... INFO[2023-03-15T04:34:06-03:00] Successfully cleaned old Kurtosis engine containers INFO[2023-03-15T04:34:06-03:00] Creating a new enclave for Starlark to run inside... -INFO[2023-03-15T04:34:10-03:00] Enclave 'kurtosis-postgres' created successfully -INFO[2023-03-15T04:34:10-03:00] Executing Starlark package at '/tmp/kurtosis-postgres' as the passed argument '.' looks like a directory -INFO[2023-03-15T04:34:10-03:00] Compressing package 'github.com/john-snow/kurtosis-postgres' at '.' for upload -INFO[2023-03-15T04:34:10-03:00] Uploading and executing package 'github.com/john-snow/kurtosis-postgres' +INFO[2023-03-15T04:34:10-03:00] Enclave 'quickstart' created successfully +INFO[2023-03-15T04:34:10-03:00] Executing Starlark package at '/tmp/kurtosis-quickstart' as the passed argument '.' looks like a directory +INFO[2023-03-15T04:34:10-03:00] Compressing package 'github.com/john-snow/kurtosis-quickstart' at '.' for upload +INFO[2023-03-15T04:34:10-03:00] Uploading and executing package 'github.com/john-snow/kurtosis-quickstart' > upload_files src="github.com/kurtosis-tech/awesome-kurtosis/data-package/dvd-rental-data.tar" Files with artifact name 'howling-thunder' uploaded with artifact UUID '32810fc8c131414882c52b044318b2fd' @@ -291,9 +289,9 @@ Command returned with exit code '0' with no output Starlark code successfully run. No output was returned. INFO[2023-03-15T04:34:21-03:00] =================================================== -INFO[2023-03-15T04:34:21-03:00] || Created enclave: kurtosis-postgres || +INFO[2023-03-15T04:34:21-03:00] || Created enclave: quickstart || INFO[2023-03-15T04:34:21-03:00] =================================================== -Name: kurtosis-postgres +Name: quickstart UUID: 995fe0ca69fe Status: RUNNING Creation Time: Wed, 15 Mar 2023 04:34:06 -03 @@ -310,7 +308,7 @@ f1d9cab2ca34 postgres postgres: 5432/tcp -> postgresql://127.0.0.1:62914 R Does your Postgres have data now? Let's find out by opening a shell on the Postgres container and logging into the database: ```bash -kurtosis service shell kurtosis-postgres postgres +kurtosis service shell quickstart postgres ``` From there, listing the tables in the Postgres can be done with: @@ -491,7 +489,7 @@ def run(plan, args): Now, run the same dev loop command as before (and don't worry about the result, we'll explain that later): ```bash -kurtosis clean -a && kurtosis run --enclave kurtosis-postgres . +kurtosis clean -a && kurtosis run --enclave quickstart . ``` We just got a failure, just like we might when building a real system! @@ -533,7 +531,7 @@ The enclave state is usually a good place to find mor clues. If you look at the ```text -Name: kurtosis-postgres +Name: quickstart UUID: 5b360f940bcc Status: RUNNING Creation Time: Tue, 14 Mar 2023 22:15:19 -03 @@ -552,7 +550,7 @@ From the above, we can see that the PostgREST service (named: `api`) is not in t You can also grab the PostgREST logs... ```bash -kurtosis service logs kurtosis-postgres api +kurtosis service logs quickstart api ``` ...we can see that the PostgREST is dying: @@ -603,13 +601,13 @@ def run(plan, args): In the line declaring the `postgres_url` variable in your `main.star` file, replace the `"postgres",` string with `POSTGRES_USER,` to use the correct username we specified at the beginning of our file. Then re-run your dev loop: ```bash -kurtosis clean -a && kurtosis run --enclave kurtosis-postgres . +kurtosis clean -a && kurtosis run --enclave quickstart . ``` Now at the bottom of the output we can see that the PostgREST service is `RUNNING` correctly: ```text -Name: kurtosis-postgres +Name: quickstart UUID: 11c0ac047299 Status: RUNNING Creation Time: Tue, 14 Mar 2023 22:30:02 -03 @@ -668,7 +666,7 @@ Now that you have an API, you should be able to interact with the data. [Inspect][kurtosis-enclave-inspect-reference] your enclave: ```bash -kurtosis enclave inspect kurtosis-postgres +kurtosis enclave inspect quickstart ``` Notice how Kurtosis automatically exposed the PostgREST container's `http` port to your machine: @@ -681,7 +679,7 @@ Notice how Kurtosis automatically exposed the PostgREST container's `http` port In this output the `http` port is exposed as URL `http://127.0.0.1:59992`, but your port number will be different. ::: -You can paste the URL from your output into your browser (or Cmd+click if you're using [iTerm][iterm]) to verify that you are indeed talking to the PostgREST inside your `kurtosis-postgres` enclave: +You can paste the URL from your output into your browser (or Cmd+click if you're using [iTerm][iterm]) to verify that you are indeed talking to the PostgREST inside your `quickstart` enclave: ```json {"swagger":"2.0","info":{"description":"","title":"standard public schema","version":"10.2.0.20230209 (pre-release) (a1e2fe3)"},"host":"0.0.0.0:3000","basePath":"/","schemes":["http"],"consumes":["application/json","application/vnd.pgrst.object+json","text/csv"],"produces":["application/json","application/vnd.pgrst.object+json","text/csv"],"paths":{"/":{"get":{"tags":["Introspection"],"summary":"OpenAPI description (this document)","produces":["application/openapi+json","application/json"],"responses":{"200":{"description":"OK"}}}},"/actor":{"get":{"tags":["actor"],"parameters":[{"$ref":"#/parameters/rowFilter.actor.actor_id"},{"$ref":"#/parameters/rowFilter.actor.first_name"},{"$ref":"#/parameters/rowFilter.actor.last_name"},{"$ref":"#/parameters/rowFilter.actor.last_update"},{"$ref":"#/parameters/select"},{"$ref":"#/parameters/order"},{"$ref":"#/parameters/range"},{"$ref":"#/parameters/rangeUnit"},{"$ref":"#/parameters/offset"},{"$ref":"#/parameters/limit"},{"$ref":"#/parameters/preferCount"}], ... @@ -833,22 +831,7 @@ def run(plan, args): **This section showed how to interact with your test environment, and also how to parametrize it for others to easily modify and re-use.** -Publishing your Kurtosis Package for others to use --------------------------------------------------- -At this point, you should have 2 files: -1. `main.star` -2. `kurtosis.yml` - -Publishing these 2 files to a Github repository will enable anyone with Kurtosis and an internet connection to instantiate the environment you described in your `main.star` file. These files, alongside a directory that you will create on Github, form the basis for a [Kurtosis package][packages-reference] - -Once you've uploaded it to a Github repository, anyone can spin up the same system - in any way they want (using your parameters) and anywhere they want (e.g. Docker, Kubernetes, local, remote, etc). - -As an example, a consumer of the Kurtosis package need only run the following command to reproduce the system and add another row to the database of actors: -```bash -kurtosis run github.com/YOUR_GITHUB_USERNAME/REPOSITORY_NAME '{"actors": [{"first_name":"Harrison", "last_name": "Ford"} -``` -Where `YOUR_GITHUB_USERNAME` is your Github username, and `REPOSITORY_NAME` is the name of your Github repository that houses your `kurtosis.yml` and `main.star` files. @@ -966,7 +959,6 @@ Lastly, feel free to [star us on Github](https://github.com/kurtosis-tech/kurtos [cassandra-package-example]: https://github.com/kurtosis-tech/cassandra-package [go-test-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/quickstart/go-test [ts-test-example]: https://github.com/kurtosis-tech/awesome-kurtosis/tree/main/quickstart/ts-test -[quickstart-consumers]: quickstart-consumer.md [homepage]: home.md diff --git a/docs/docs/guides/adding-command-line-completion.md b/docs/docs/guides/adding-command-line-completion.md index 318b116f8d..4a28979888 100644 --- a/docs/docs/guides/adding-command-line-completion.md +++ b/docs/docs/guides/adding-command-line-completion.md @@ -1,7 +1,7 @@ --- title: Adding Command-Line Completion sidebar_label: Adding Command-Line Completion -sidebar_position: 3 +sidebar_position: 4 --- -[quickstart]: ../get-started/quickstart-consumer.md +[quickstart]: ../get-started/quickstart.md [awesome-kurtosis]: https://github.com/kurtosis-tech/awesome-kurtosis [multi-phase-runs]: ../concepts-reference/multi-phase-runs.md [github-cass-package]: https://github.com/kurtosis-tech/cassandra-package/blob/main/main.star diff --git a/docs/docs/guides/installing-historical-versions.md b/docs/docs/guides/installing-historical-versions.md index b67f23180c..cad90a5ff3 100644 --- a/docs/docs/guides/installing-historical-versions.md +++ b/docs/docs/guides/installing-historical-versions.md @@ -2,7 +2,7 @@ title: Installing Historical Versions sidebar_label: Installing Historical Versions slug: /install-historical -sidebar_position: 4 +sidebar_position: 3 --- diff --git a/docs/docs/guides/installing-the-cli.md b/docs/docs/guides/installing-the-cli.md index 3ce6f10189..96732f1471 100644 --- a/docs/docs/guides/installing-the-cli.md +++ b/docs/docs/guides/installing-the-cli.md @@ -110,7 +110,7 @@ If you're new to Kurtosis, you might like the [quickstart][quickstart] as a good [cli-changelog]: ../changelog.md [metrics-philosophy]: ../explanations/metrics-philosophy.md [analytics-disable]: ../cli-reference/analytics-disable.md -[quickstart]: ../get-started/quickstart-consumer.md +[quickstart]: ../get-started/quickstart.md [installing-command-line-completion]: ./adding-command-line-completion.md [install-historical-guide]: ./installing-historical-versions.md [upgrade-guide]: ./upgrading-the-cli.md diff --git a/docs/docs/guides/running-in-ci.md b/docs/docs/guides/running-in-ci.md index b45c27a288..35a11bcc97 100644 --- a/docs/docs/guides/running-in-ci.md +++ b/docs/docs/guides/running-in-ci.md @@ -2,7 +2,6 @@ title: Running Kurtosis in CI sidebar_label: Running in CI slug: /ci -sidebar_position: 5 --- Running Kurtosis on your local machine is nice, but executing it as part of CI is even better. This guide will walk you through modifying your CI config file to use Kurtosis in your CI environment: diff --git a/docs/docs/guides/running-in-k8s.md b/docs/docs/guides/running-in-k8s.md index d4e924c063..25582bebf0 100644 --- a/docs/docs/guides/running-in-k8s.md +++ b/docs/docs/guides/running-in-k8s.md @@ -2,7 +2,6 @@ title: Running Kurtosis in Kubernetes sidebar_label: Running in Kubernetes slug: /k8s -sidebar_position: 6 --- This guide assumes that you have [Kurtosis installed](./installing-the-cli.md). diff --git a/docs/docs/guides/running-in-kurtosis-cloud.md b/docs/docs/guides/running-in-kurtosis-cloud.md index 05c49205dd..5485abfe73 100644 --- a/docs/docs/guides/running-in-kurtosis-cloud.md +++ b/docs/docs/guides/running-in-kurtosis-cloud.md @@ -2,7 +2,6 @@ title: Running Kurtosis in Kurtosis Cloud sidebar_label: Running in Kurtosis Cloud slug: /cloud -sidebar_position: 7 --- Kurtosis Cloud is a fully managed cloud offering and accompanying self-service workflows for a stress-free, easy way to deploy test and dev environments, that live as long as you need them to, directly onto remote infrastructure. By logging into our [cloud portal](https://cloud.kurtosis.com), a cloud instance will be provisioned to run your test and dev enclaves. diff --git a/docs/docs/guides/upgrading-the-cli.md b/docs/docs/guides/upgrading-the-cli.md index 7844cefd25..fc6cc4c579 100644 --- a/docs/docs/guides/upgrading-the-cli.md +++ b/docs/docs/guides/upgrading-the-cli.md @@ -86,7 +86,7 @@ In order to upgrade Kurtosis to another version *after you've performed a downgr [install-guide]: ./installing-the-cli.md [cli-changelog]: ../changelog.md [metrics-philosophy]: ../explanations/metrics-philosophy.md -[quickstart]: ../get-started/quickstart-consumer.md +[quickstart]: ../get-started/quickstart.md [installing-command-line-completion]: ./adding-command-line-completion.md [release-artifacts]: https://github.com/kurtosis-tech/kurtosis-cli-release-artifacts/releases