From b067148ad53966bfffa8d7c29a53c0aac6dffba0 Mon Sep 17 00:00:00 2001 From: Al Date: Wed, 3 Apr 2024 12:52:47 +0200 Subject: [PATCH] docs: minor rewrite in quick start guide (#64) * docs: minor rewrite in quick start guide * chore: addressing pr comments --- ...ction-beaker-smart-contract-python-cd.yaml | 2 +- ...ction-beaker-smart-contract-python-ci.yaml | 2 +- .../README.md | 80 +++++++++++-------- ...n-beaker-smart-contract-typescript-cd.yaml | 2 +- ...n-beaker-smart-contract-typescript-ci.yaml | 2 +- .../README.md | 80 +++++++++++-------- .../README.md | 80 +++++++++++-------- .../README.md | 80 +++++++++++-------- .../workflows/production-beaker-cd.yaml | 2 +- .../workflows/production-beaker-ci.yaml | 2 +- examples/production_beaker/README.md | 80 +++++++++++-------- examples/starter_beaker/README.md | 80 +++++++++++-------- template_content/README.md.jinja | 80 +++++++++++-------- ...roject_name_kebab.jinja') %}-cd.yaml.jinja | 2 +- ...roject_name_kebab.jinja') %}-ci.yaml.jinja | 2 +- 15 files changed, 330 insertions(+), 246 deletions(-) diff --git a/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-cd.yaml b/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-cd.yaml index 9186691..88e884a 100644 --- a/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-cd.yaml +++ b/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-cd.yaml @@ -31,7 +31,7 @@ jobs: run: pipx install algokit - name: Bootstrap dependencies - run: algokit bootstrap all --project-name 'production_beaker_smart_contract_python' + run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_python' - name: Configure git shell: bash diff --git a/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-ci.yaml b/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-ci.yaml index 671d1c2..6abe293 100644 --- a/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-ci.yaml +++ b/examples/generators/production_beaker_smart_contract_python/.github/workflows/production-beaker-smart-contract-python-ci.yaml @@ -27,7 +27,7 @@ jobs: run: algokit localnet start - name: Bootstrap dependencies - run: algokit bootstrap all --project-name 'production_beaker_smart_contract_python' + run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_python' - name: Configure git shell: bash diff --git a/examples/generators/production_beaker_smart_contract_python/README.md b/examples/generators/production_beaker_smart_contract_python/README.md index 849cee4..bcac42c 100644 --- a/examples/generators/production_beaker_smart_contract_python/README.md +++ b/examples/generators/production_beaker_smart_contract_python/README.md @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder.### Continuous Integration / Continuous Deployment (CI/CD) diff --git a/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-cd.yaml b/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-cd.yaml index ecd2db4..dc41541 100644 --- a/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-cd.yaml +++ b/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-cd.yaml @@ -31,7 +31,7 @@ jobs: run: pipx install algokit - name: Bootstrap dependencies - run: algokit bootstrap all --project-name 'production_beaker_smart_contract_typescript' + run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_typescript' - name: Configure git shell: bash diff --git a/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-ci.yaml b/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-ci.yaml index 6763a51..e829eb2 100644 --- a/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-ci.yaml +++ b/examples/generators/production_beaker_smart_contract_typescript/.github/workflows/production-beaker-smart-contract-typescript-ci.yaml @@ -27,7 +27,7 @@ jobs: run: algokit localnet start - name: Bootstrap dependencies - run: algokit bootstrap all --project-name 'production_beaker_smart_contract_typescript' + run: algokit project bootstrap all --project-name 'production_beaker_smart_contract_typescript' - name: Configure git shell: bash diff --git a/examples/generators/production_beaker_smart_contract_typescript/README.md b/examples/generators/production_beaker_smart_contract_typescript/README.md index b7be891..72bd2e3 100644 --- a/examples/generators/production_beaker_smart_contract_typescript/README.md +++ b/examples/generators/production_beaker_smart_contract_typescript/README.md @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder.### Continuous Integration / Continuous Deployment (CI/CD) diff --git a/examples/generators/starter_beaker_smart_contract_python/README.md b/examples/generators/starter_beaker_smart_contract_python/README.md index cebc952..d07951d 100644 --- a/examples/generators/starter_beaker_smart_contract_python/README.md +++ b/examples/generators/starter_beaker_smart_contract_python/README.md @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder. diff --git a/examples/generators/starter_beaker_smart_contract_typescript/README.md b/examples/generators/starter_beaker_smart_contract_typescript/README.md index 8abe6a3..8132d76 100644 --- a/examples/generators/starter_beaker_smart_contract_typescript/README.md +++ b/examples/generators/starter_beaker_smart_contract_typescript/README.md @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder. diff --git a/examples/production_beaker/.github/workflows/production-beaker-cd.yaml b/examples/production_beaker/.github/workflows/production-beaker-cd.yaml index a5b2f8c..e503f53 100644 --- a/examples/production_beaker/.github/workflows/production-beaker-cd.yaml +++ b/examples/production_beaker/.github/workflows/production-beaker-cd.yaml @@ -31,7 +31,7 @@ jobs: run: pipx install algokit - name: Bootstrap dependencies - run: algokit bootstrap all --project-name 'production_beaker' + run: algokit project bootstrap all --project-name 'production_beaker' - name: Configure git shell: bash diff --git a/examples/production_beaker/.github/workflows/production-beaker-ci.yaml b/examples/production_beaker/.github/workflows/production-beaker-ci.yaml index f5011eb..daa34ab 100644 --- a/examples/production_beaker/.github/workflows/production-beaker-ci.yaml +++ b/examples/production_beaker/.github/workflows/production-beaker-ci.yaml @@ -27,7 +27,7 @@ jobs: run: algokit localnet start - name: Bootstrap dependencies - run: algokit bootstrap all --project-name 'production_beaker' + run: algokit project bootstrap all --project-name 'production_beaker' - name: Configure git shell: bash diff --git a/examples/production_beaker/README.md b/examples/production_beaker/README.md index 11a3815..cc59ed9 100644 --- a/examples/production_beaker/README.md +++ b/examples/production_beaker/README.md @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder.### Continuous Integration / Continuous Deployment (CI/CD) diff --git a/examples/starter_beaker/README.md b/examples/starter_beaker/README.md index db2720e..b238c87 100644 --- a/examples/starter_beaker/README.md +++ b/examples/starter_beaker/README.md @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder. diff --git a/template_content/README.md.jinja b/template_content/README.md.jinja index 394ef36..89f78ce 100644 --- a/template_content/README.md.jinja +++ b/template_content/README.md.jinja @@ -11,40 +11,52 @@ This project has been generated using AlgoKit. See below for default getting sta > For interactive tour over the codebase, download [vsls-contrib.codetour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) extension for VS Code, then open the [`.codetour.json`](./.tours/getting-started-with-your-algokit-project.tour) file in code tour extension. -### Initial setup - -1. Clone this repository locally -2. Install pre-requisites: - - Make sure to have [Docker](https://www.docker.com/) installed and running on your machine. - - Install `AlgoKit` - [Link](https://github.com/algorandfoundation/algokit-cli#install): The recommended version is the latest available. Ensure you can execute `algokit --version` and get `2.0.0` or later. - - Bootstrap your local environment; run `algokit bootstrap all` within this folder, which will: - - Install `Poetry` - [Link](https://python-poetry.org/docs/#installation): The minimum required version is `^1.7`. Ensure you can execute `poetry -V` and get `1.2`+ - - Run `poetry install` in the root directory, which will set up a `.venv` folder with a Python virtual environment and also install all Python dependencies - - Copy `.env.template` to `.env` - - Run `algokit localnet start` to start a local Algorand network in Docker. If you are using VS Code launch configurations provided by the template, this will be done automatically for you. - - Run `algokit project bootstrap all` to install all project dependencies (unless executed during `algokit init`). -3. Open the project and start debugging / developing via: - - Terminal - 1. Run `algokit project run build` to build all contracts in the project - 2. Run `algokit project deploy localnet` to deploy all contracts to the local Algorand network. - - VS Code (Launch Configurations) - 1. Open the repository root in VS Code - 2. Install recommended extensions - 3. Hit F5 (or whatever you have debug mapped to) and it should start running with breakpoint debugging. - > **Note** - > If using Windows: Before running for the first time you will need to select the Python Interpreter. - 1. Open the command palette (Ctrl/Cmd + Shift + P) - 2. Search for `Python: Select Interpreter` - 3. Select `./.venv/Scripts/python.exe` - - JetBrains IDEs (please note, this setup is primarily optimized for PyCharm Community Edition) - 1. Open the repository root in the IDE - 2. It should automatically detect it's a Poetry project and set up a Python interpreter and virtual environment. - 3. Hit Shift+F10|Ctrl+R (or whatever you have debug mapped to) and it should start running with breakpoint debugging. Please note, JetBrains IDEs on Windows have a known bug that in some cases may prevent executing shell scripts as pre-launch tasks, for workarounds refer to [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task). - -### Subsequently - -1. If you update to the latest source code and there are new dependencies you will need to run `algokit bootstrap all` again -2. Follow step 3 above +### Initial Setup + +#### 1. Clone the Repository +Start by cloning this repository to your local machine. + +#### 2. Install Pre-requisites +Ensure the following pre-requisites are installed and properly configured: + +- **Docker**: Required for running a local Algorand network. [Install Docker](https://www.docker.com/). +- **AlgoKit CLI**: Essential for project setup and operations. Install the latest version from [AlgoKit CLI Installation Guide](https://github.com/algorandfoundation/algokit-cli#install). Verify installation with `algokit --version`, expecting `2.0.0` or later. + +#### 3. Bootstrap Your Local Environment +Run the following commands within the project folder: + +- **Install Poetry**: Required for Python dependency management. [Installation Guide](https://python-poetry.org/docs/#installation). Verify with `poetry -V` to see version `1.2`+. +- **Setup Project**: Execute `algokit project bootstrap all` to: + - Install dependencies and setup a Python virtual environment in `.venv`. + - Copy `.env.template` to `.env`. +- **Start LocalNet**: Use `algokit localnet start` to initiate a local Algorand network. + +### Development Workflow + +#### Terminal +Directly manage and interact with your project using AlgoKit commands: + +1. **Build Contracts**: `algokit project run build` compiles all smart contracts. +2. **Deploy**: Use `algokit project deploy localnet` to deploy contracts to the local network. + +#### VS Code +For a seamless experience with breakpoint debugging and other features: + +1. **Open Project**: In VS Code, open the repository root. +2. **Install Extensions**: Follow prompts to install recommended extensions. +3. **Debugging**: + - Use `F5` to start debugging. + - **Windows Users**: Select the Python interpreter at `./.venv/Scripts/python.exe` via `Ctrl/Cmd + Shift + P` > `Python: Select Interpreter` before the first run. + +#### JetBrains IDEs +While primarily optimized for VS Code, JetBrains IDEs are supported: + +1. **Open Project**: In your JetBrains IDE, open the repository root. +2. **Automatic Setup**: The IDE should configure the Python interpreter and virtual environment. +3. **Debugging**: Use `Shift+F10` or `Ctrl+R` to start debugging. Note: Windows users may encounter issues with pre-launch tasks due to a known bug. See [JetBrains forums](https://youtrack.jetbrains.com/issue/IDEA-277486/Shell-script-configuration-cannot-run-as-before-launch-task) for workarounds. + +## AlgoKit Workspaces and Project Management +This project supports both standalone and monorepo setups through AlgoKit workspaces. Leverage [`algokit project run`](https://github.com/algorandfoundation/algokit-cli/blob/main/docs/features/project/run.md) commands for efficient monorepo project orchestration and management across multiple projects within a workspace. > For guidance on `smart_contracts` folder and adding new contracts to the project please see [README](smart_contracts/README.md) on the respective folder. diff --git a/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-cd.yaml.jinja b/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-cd.yaml.jinja index eb5af8a..cd68d24 100644 --- a/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-cd.yaml.jinja +++ b/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-cd.yaml.jinja @@ -36,7 +36,7 @@ jobs: run: pipx install algokit - name: Bootstrap dependencies - run: algokit bootstrap all --project-name '{{ project_name }}' + run: algokit project bootstrap all --project-name '{{ project_name }}' - name: Configure git shell: bash diff --git a/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-ci.yaml.jinja b/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-ci.yaml.jinja index 03dae94..8294d58 100644 --- a/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-ci.yaml.jinja +++ b/template_content/{% if use_github_actions %}.github{% endif %}/workflows/{% include pathjoin('includes', 'project_name_kebab.jinja') %}-ci.yaml.jinja @@ -30,7 +30,7 @@ jobs: run: algokit localnet start - name: Bootstrap dependencies - run: algokit bootstrap all --project-name '{{ project_name }}' + run: algokit project bootstrap all --project-name '{{ project_name }}' - name: Configure git shell: bash