From 63e87881b2dbf0dc5f3359297854f0eab32efb0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Pedro=20Sousa?= Date: Fri, 10 May 2024 11:28:34 +0100 Subject: [PATCH] feat: replacing mentions to aztec-starter with codespace methods (#6177) Refactoring the quickstart page with the new install methods. Removing references to aztec-starter, as that repo will likely be deprecated. Closes AztecProtocol/dev-rel#192 --------- Co-authored-by: Cat McGee Co-authored-by: James Zaki --- boxes/README.md | 31 +++----- boxes/boxes/react/README.md | 29 +++++++ boxes/boxes/vanilla/README.md | 30 +++++++ boxes/contract-only/README.md | 31 +++++++- boxes/package.json | 3 +- boxes/scripts/steps/sandbox/run.js | 6 +- .../contracts/testing_contracts/main.md | 2 +- .../developers/getting_started/quickstart.md | 79 +++++-------------- .../sandbox/references/sandbox-reference.md | 53 +++++++------ docs/docs/welcome.md | 2 - docs/docusaurus.config.js | 2 +- docs/package.json | 4 +- .../img/codespaces_badges/react_cta_badge.svg | 19 +++++ .../img/codespaces_badges/token_cta_badge.svg | 19 +++++ .../codespaces_badges/vanilla_cta_badge.svg | 19 +++++ 15 files changed, 212 insertions(+), 117 deletions(-) create mode 100644 docs/static/img/codespaces_badges/react_cta_badge.svg create mode 100644 docs/static/img/codespaces_badges/token_cta_badge.svg create mode 100644 docs/static/img/codespaces_badges/vanilla_cta_badge.svg diff --git a/boxes/README.md b/boxes/README.md index 67cf195e9ed..f7adc35ecb1 100644 --- a/boxes/README.md +++ b/boxes/README.md @@ -8,36 +8,27 @@ Aztec Boxes are the one-stop-shop for developing on Aztec. They often include a Boxes include the sandbox installation script and its start command. By choosing the appropriate box, you can get started working on Aztec in a minimal amount of time. -## Getting started +## Contributing -If you have [node](https://nodejs.org/en/download) installed, you can open a terminal in any folder and run: +Because of the CI/CD nature of the monorepo, every box is tested against every merge on master. This drastically reduces their maintenance cost. Thus, some scripting is needed to make sure the user gets a working repository after "unboxing". -`npx create-aztec-app` +Most of the logic is in the `bin.js` file, where `commander` commands stuff. The script does the following: -or +- Prompts the user for options and commands +- Inits some global variables such as a logger, a getter for the github repositories, the latest stable versions and tags, etc +- Prompts the user to choose the project and clone it. It then rewrites the `Nargo.toml` and `package.json` files to point to the repos instead of the local dependencies. +- Queries the local docker daemon for any existing sandbox images, prompting the user to install or update it if needed +- Asks the user if they want to run the sandbox right away -`npx create-aztec-app` - -The script will install the sandbox, run it, and clone the boilerplate you chose. You can pass some options: - -| Option | Description | -| --- | --- | -| -d, --debug | Displays some more information for debug reasons. | -| -gh, --github_token | You can pass a github_token in case you hit API rate limit | -| -v, --version | You can specify a semver version, or "MASTER" | -| -h, --help | Shows up this help menu | - - If at any time you encounter problems, refer to the guides at [docs.aztec.network](https://docs.aztec.network) for more information. ## Templates -Currently there are two boxes: +As noted above, every box is tested at every merge to master. Any breaking changes need to happen in every box, so we try to keep the number of templates strategically low. For that reason, we ask contributors to reach directly to the [devrel team](https://github.com/orgs/AztecProtocol/teams/devrel) before adding another template. + +Currently there are two "app" boxes and one "contract-only" box: - React - A React boilerplate with a minimal UI. - Vanilla JS and HTML - Some say if you get something working in vanilla JS and HTML, you can make it work on any framework. If you can't find the box you need, this could be a good starting point. - -And one contract-only box: - - Token - An example token contract on Aztec ## Support diff --git a/boxes/boxes/react/README.md b/boxes/boxes/react/README.md index 40fdeed5b6f..03f03cde8c0 100644 --- a/boxes/boxes/react/README.md +++ b/boxes/boxes/react/README.md @@ -2,6 +2,35 @@ This box is a one-stop-shop for Aztec that will deploy a minimal React page. You can use it as a boilerplate to start developing your own Aztec app in seconds! +## Getting Started + +The easiest way to start is with a Github Codespaces, which has a generous free tier. Just click on this button: + +[![One-Click React Starter](.devcontainer/assets/react_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Freact%2Fdevcontainer.json) + +## Using the `npx` command + +The above method just uses the `npx` command, AKA "unboxing the box". This is a CLI command to quickly start developing on your own machine. + +### Prerequisites + +- Node >v18 +- Docker + +### Usage + +Just open a terminal and write: + +```bash +npx create-aztec-app +``` + +It should ask you some questions about your project, install and run the Sandbox (local developer network). You can also start, stop, update, and do other things on the sandbox through this script. Just run: + +```bash +npx create-aztec-app sandbox --help +``` + ## More information Visit the [Aztec Docs](https://docs.aztec.network) for more information on how Aztec works, and the [Awesome Aztec Repository](https://github.com/AztecProtocol/awesome-aztec) for more cool projects, boilerplates and tooling. diff --git a/boxes/boxes/vanilla/README.md b/boxes/boxes/vanilla/README.md index 92b9db74c58..8190eb5d4cd 100644 --- a/boxes/boxes/vanilla/README.md +++ b/boxes/boxes/vanilla/README.md @@ -2,6 +2,36 @@ This box is a one-stop-shop for Aztec that will deploy a minimal barebones HTML+JS page. You can use it as a boilerplate to start developing your own Aztec app in seconds! + +## Getting Started + +The easiest way to start is with a Github Codespaces, which has a generous free tier. Just click on this button: + +[![One-Click HTML/TS Starter](.devcontainer/assets/vanilla_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Fvanilla%2Fdevcontainer.json) + +## Using the `npx` command + +The above method just uses the `npx` command, AKA "unboxing the box". This is a CLI command to quickly start developing on your own machine. + +### Prerequisites + +- Node >v18 +- Docker + +### Usage + +Just open a terminal and write: + +```bash +npx create-aztec-app +``` + +It should ask you some questions about your project, install and run the Sandbox (local developer network). You can also start, stop, update, and do other things on the sandbox through this script. Just run: + +```bash +npx create-aztec-app sandbox --help +``` + ## More information Visit the [Aztec Docs](https://docs.aztec.network) for more information on how Aztec works, and the [Awesome Aztec Repository](https://github.com/AztecProtocol/awesome-aztec) for more cool projects, boilerplates and tooling. diff --git a/boxes/contract-only/README.md b/boxes/contract-only/README.md index 9ab9f68660d..452b7a4b213 100644 --- a/boxes/contract-only/README.md +++ b/boxes/contract-only/README.md @@ -2,7 +2,36 @@ This box is a one-stop-shop for Aztec with the %%contract_name%% example contract. You can use it as a boilerplate to start developing your own Aztec app in seconds! -## How to start +## Getting Started + +The easiest way to start is with a Github Codespaces, which has a generous free tier. Just click on this button: + +[![One-Click Token Starter](.devcontainer/assets/token_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Ftoken%2Fdevcontainer.json) + +## Using the `npx` command + +The above method just uses the `npx` command, AKA "unboxing the box". This is a CLI command to quickly start developing on your own machine. + +### Prerequisites + +- Node >v18 +- Docker + +### Usage + +Just open a terminal and write: + +```bash +npx create-aztec-app +``` + +It should ask you some questions about your project, install and run the Sandbox (local developer network). You can also start, stop, update, and do other things on the sandbox through this script. Just run: + +```bash +npx create-aztec-app sandbox --help +``` + +## What's in the box The script copied one of the example contracts and put it into a one-size-fits-all "box". With it, you can run commands such as: diff --git a/boxes/package.json b/boxes/package.json index c0c3cda556f..ad941bc6c07 100644 --- a/boxes/package.json +++ b/boxes/package.json @@ -1,9 +1,8 @@ { "name": "create-aztec-app", "packageManager": "yarn@4.0.2", - "version": "0.4.2", + "version": "0.4.4", "type": "module", - "private": true, "scripts": { "compile": "yarn workspaces foreach -A -v run compile", "build": "yarn workspaces foreach -A -v run build", diff --git a/boxes/scripts/steps/sandbox/run.js b/boxes/scripts/steps/sandbox/run.js index 77238e289b7..65206dd785a 100644 --- a/boxes/scripts/steps/sandbox/run.js +++ b/boxes/scripts/steps/sandbox/run.js @@ -4,8 +4,8 @@ import axios from "axios"; const sandbox = (command) => execSync( - `docker-compose -f $HOME/.aztec/docker-compose.yml -p sandbox ${command}`, - { stdio: "inherit" }, + `docker compose -f $HOME/.aztec/docker-compose.yml -p sandbox ${command}`, + { stdio: "inherit" } ); export const start = () => sandbox("up -d"); @@ -29,7 +29,7 @@ export async function sandboxRunStep() { Accept: "*/*", "Content-Type": "application/json", }, - }, + } ); spinner.succeed(); success("The Sandbox is already running!"); diff --git a/docs/docs/developers/contracts/testing_contracts/main.md b/docs/docs/developers/contracts/testing_contracts/main.md index e0d217adbef..f00e567bc0a 100644 --- a/docs/docs/developers/contracts/testing_contracts/main.md +++ b/docs/docs/developers/contracts/testing_contracts/main.md @@ -10,4 +10,4 @@ To make testing easier, the sandbox is shipped with cheat codes to easily test i ## Examples -You can find example tests in the [aztec-starter](https://github.com/AztecProtocol/aztec-starter/tree/main) repo as well as the [Aztec Boxes](https://github.com/AztecProtocol/aztec-packages/tree/master/boxes). +You can find example tests in the [Aztec Boxes](https://github.com/AztecProtocol/aztec-packages/tree/master/boxes). You can also have a look at the [end-to-end tests](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/end-to-end). diff --git a/docs/docs/developers/getting_started/quickstart.md b/docs/docs/developers/getting_started/quickstart.md index a05f8abc675..8ad154578a9 100644 --- a/docs/docs/developers/getting_started/quickstart.md +++ b/docs/docs/developers/getting_started/quickstart.md @@ -2,82 +2,38 @@ title: Quickstart --- -In this guide, you will +The easiest way to start developing on Aztec is simply to click on one of these buttons: -1. Set up the Aztec sandbox (local development environment) locally -2. Install the Aztec development kit -3. Use Aztec.js to deploy an example contract that comes with the sandbox -4. Use Aztec.js to interact with the contract you just deployed +[![One-Click React Starter](/img/codespaces_badges/react_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Freact%2Fdevcontainer.json) [![One-Click HTML/TS Starter](/img/codespaces_badges/vanilla_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Fvanilla%2Fdevcontainer.json) [![One-Click Token Starter](/img/codespaces_badges/token_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Ftoken%2Fdevcontainer.json) -... in less than 10 minutes. +That's it! -## Prerequisites +This creates a codespace with a prebuilt image containing one of the "Aztec Boxes" and a development network (sandbox). +- You can develop directly on the codespace, push it to a repo, make yourself at home. +- You can also just use the sandbox that comes with it. The URL will be logged, you just need to use it as your `PXE_URL`. -- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm)) - -## Install Docker - -Aztec tooling requires the Docker daemon to be running, and this is easily achieved via Docker Desktop. See [this page of the Docker docs](https://docs.docker.com/get-docker/) for instructions on how to install Docker Desktop for your operating system. -Note: if installing via Docker Desktop, you do NOT need to keep the application open at all times (just Docker daemon). - -Installing and running the Docker daemon can also be achieved by installing Docker Engine, see [these instructions](https://docs.docker.com/engine/install/). - -However installed, ensure Docker daemon is running. See [start Docker daemon](https://docs.docker.com/config/daemon/start/). - -### Note on Linux - -If you are running Linux, you will need to set the context (because Docker Desktop runs in a VM by default). See [this page](https://docs.docker.com/desktop/faqs/linuxfaqs/#what-is-the-difference-between-docker-desktop-for-linux-and-docker-engine) for more information. You can do this by running: - -```bash -docker context use default -``` - -## Install the Sandbox +## Develop Locally -You can run the Sandbox using Docker. +The above method uses Aztec boxes to install the sandbox and clone the repo. You can use it too to get started on your own machine and use your own IDE. -To install the latest Sandbox version, run: +You can also [install the sandbox manually](../sandbox/references/sandbox-reference.md). -```bash -bash -i <(curl -s install.aztec.network) -``` - -> If Docker has been installed on your linux server but you encounter the error "Docker is not running. Please start Docker and try again". If you're encountering this issue, it's likely because Docker is running with root user privileges. In such cases, consider [managing Docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) to resolve the problem. +### Prerequisites +- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm)) +- Docker (visit [this page of the Docker docs](https://docs.docker.com/get-docker/) on how to install it) -This will install the following: - -- **aztec** - launches various infrastructure subsystems (sequencer, prover, pxe, etc). -- **aztec-nargo** - aztec's build of nargo, the noir compiler toolchain. -- **aztec-sandbox** - a wrapper around docker-compose that launches services needed for sandbox testing. -- **aztec-up** - a tool to upgrade the aztec toolchain to the latest, or specific versions. -- **aztec-builder** - A useful tool for projects to generate ABIs and update their dependencies. - +### Run the `npx` script -Once these have been installed, to start the sandbox, run: +With the node installation, you now should have `npm` and be able to run `npx` scripts. You can do that by running: ```bash -aztec-sandbox +npx create-aztec-app ``` -This will attempt to run the Sandbox on ` localhost:8080`, so you will have to make sure nothing else is running on that port or change the port defined in `./.aztec/docker-compose.yml`. Running the installation again will overwrite any changes made to the `docker-compose.yml`. +And follow the instructions. If all goes well, you should now have a development environment running locally on your machine. -**Congratulations, you have just installed and run the Aztec Sandbox!** - -```bash - /\ | | - / \ ___| |_ ___ ___ - / /\ \ |_ / __/ _ \/ __| - / ____ \ / /| || __/ (__ - /_/___ \_\/___|\__\___|\___| - -``` - -In the terminal, you will see some logs: -1. Sandbox version -2. Contract addresses of rollup contracts -3. PXE (private execution environment) setup logs -4. Initial accounts that are shipped with the sandbox and can be used in tests +You can run `npx create-aztec-app sandbox -h` to start, stop, update and output logs from the sandbox. ## What's next? @@ -85,3 +41,4 @@ To deploy a smart contract to your sandbox and interact with it using Aztec.js, To skip this and write your first smart contract, go to the [Aztec.nr getting started page](aztecnr-getting-started.md). + diff --git a/docs/docs/developers/sandbox/references/sandbox-reference.md b/docs/docs/developers/sandbox/references/sandbox-reference.md index 99e7850fb04..fc401a57336 100644 --- a/docs/docs/developers/sandbox/references/sandbox-reference.md +++ b/docs/docs/developers/sandbox/references/sandbox-reference.md @@ -2,19 +2,30 @@ title: Sandbox Reference --- -Here you will find a reference to everything available within the Sandbox. +:::tip -## Installation +For a quick start, follow the [guide](../../getting_started/quickstart.md) to install the sandbox. -You can run the Sandbox using Docker. See the [Quickstart](../../getting_started/quickstart.md#install-docker) for instructions on installing Docker. +::: -### With Docker +## Manual Install + +You can manually install the sandbox via the underlying script used in the [Aztec Boxes](../../getting_started/quickstart.md#run-the-npx-script). + +### Prerequisites + +- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm)) +- Docker (visit [this page of the Docker docs](https://docs.docker.com/get-docker/) on how to install it) + +### Install the sandbox + +To install the latest Sandbox version, run: ```bash bash -i <(curl -s install.aztec.network) ``` -This will install the following: +This will install the following tools: - **aztec** - launches various infrastructure subsystems (sequencer, prover, pxe, etc). - **aztec-nargo** - aztec's build of nargo, the noir compiler toolchain. @@ -28,31 +39,25 @@ Once these have been installed, to start the sandbox, run: aztec-sandbox ``` -This will attempt to run the Sandbox with the PXE listening on ` localhost:8080`. You can change the port defined in `./.aztec/docker-compose.yml` or by setting the `PXE_PORT` environment variable. Running the install command again will overwrite any changes made to the `docker-compose.yml`. - -See the full list of configurable environment variables [here](#environment-variables). +### Have fun! -If you have previously installed the CLI via a node package manager, you will need to uninstall it and remove it from your project dependencies and install it via Docker. +**Congratulations, you have just installed and run the Aztec Sandbox!** -To install a specific version of the sandbox, you can set the environment variable `SANDBOX_VERSION` +```bash + /\ | | + / \ ___| |_ ___ ___ + / /\ \ |_ / __/ _ \/ __| + / ____ \ / /| || __/ (__ + /_/___ \_\/___|\__\___|\___| -```bash -VERSION= bash -i <(curl -s install.aztec.network) ``` -## Running - -Once the installed, you can run the sandbox with: +In the terminal, you will see some logs: +1. Sandbox version +2. Contract addresses of rollup contracts +3. PXE (private execution environment) setup logs +4. Initial accounts that are shipped with the sandbox and can be used in tests -```bash -aztec-sandbox -``` - -Alternatively, you can run like so: - -```bash -cd ~/.aztec && docker-compose up -``` ## Running Aztec PXE / Node / P2P-Bootstrap node diff --git a/docs/docs/welcome.md b/docs/docs/welcome.md index 6be66998211..c579ef9d130 100644 --- a/docs/docs/welcome.md +++ b/docs/docs/welcome.md @@ -23,6 +23,4 @@ Go to the [Getting Started section](./developers/getting_started/main.md) of the Check out the [Awesome Aztec repo](https://github.com/AztecProtocol/awesome-aztec) for a curated list of learning resources and tools to help you learn more about Aztec. -Clone the [Aztec Starter repo](https://github.com/AztecProtocol/aztec-starter) to get a minimal project set up with Sandbox (local developer network), a simple contract and a test suite. - Jump into one of the [tutorials](./developers/tutorials/main.md) to learn how to build more complex applications on Aztec. diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index b0a158adaf4..ddfc137fc7c 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -43,7 +43,7 @@ const config = { /** @type {import('@docusaurus/preset-classic').Options} */ ({ docs: { - path: "processed-docs", + path: process.env.ENV === "dev" ? "docs" : "processed-docs", sidebarPath: require.resolve("./sidebars.js"), editUrl: (params) => { return ( diff --git a/docs/package.json b/docs/package.json index a6cd883a4e2..c4aaac29040 100644 --- a/docs/package.json +++ b/docs/package.json @@ -4,8 +4,8 @@ "private": true, "scripts": { "docusaurus": "docusaurus", - "start": "yarn preprocess && yarn typedoc && docusaurus start --host 0.0.0.0", - "start:dev": "yarn start", + "start": "yarn preprocess && yarn typedoc && docusaurus start --host 0.0.0.0 ", + "start:dev": "ENV=dev yarn start", "start:dev:local": "yarn preprocess && yarn typedoc && docusaurus start", "build": "./scripts/build.sh", "swizzle": "docusaurus swizzle", diff --git a/docs/static/img/codespaces_badges/react_cta_badge.svg b/docs/static/img/codespaces_badges/react_cta_badge.svg new file mode 100644 index 00000000000..c8c3d1738d4 --- /dev/null +++ b/docs/static/img/codespaces_badges/react_cta_badge.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/codespaces_badges/token_cta_badge.svg b/docs/static/img/codespaces_badges/token_cta_badge.svg new file mode 100644 index 00000000000..9d536be120b --- /dev/null +++ b/docs/static/img/codespaces_badges/token_cta_badge.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/static/img/codespaces_badges/vanilla_cta_badge.svg b/docs/static/img/codespaces_badges/vanilla_cta_badge.svg new file mode 100644 index 00000000000..a717e72561a --- /dev/null +++ b/docs/static/img/codespaces_badges/vanilla_cta_badge.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + +