feat: Add support for a customisable named localnet (#373)

* feat: add name option to localnet start, allowing for a customisable LocalNet configuration
* docs: updating docs

.vscode/settings.json

@@ -2,9 +2,8 @@
   // General - see also /.editorconfig
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
-    // Don't want to use isort because it conflicts with Ruff - see run on save below
-    "source.organizeImports": true,
-    "source.fixAll": true
+    "source.organizeImports": "explicit",
+    "source.fixAll": "explicit"
   },
   "editor.defaultFormatter": "esbenp.prettier-vscode",
   "files.exclude": {

docs/cli/index.md

@@ -97,17 +97,19 @@
     - [Options](#options-16)
     - [--update, --no-update](#--update---no-update)
     - [start](#start)
+    - [Options](#options-17)
+    - [-n, --name ](#-n---name--1)
     - [status](#status)
     - [stop](#stop)
   - [task](#task)
     - [ipfs](#ipfs)
-    - [Options](#options-17)
+    - [Options](#options-18)
     - [-f, --file ](#-f---file--1)
-    - [-n, --name ](#-n---name--1)
+    - [-n, --name ](#-n---name--2)
     - [mint](#mint)
-    - [Options](#options-18)
+    - [Options](#options-19)
     - [--creator ](#--creator-)
-    - [-n, --name ](#-n---name--2)
+    - [-n, --name ](#-n---name--3)
     - [-u, --unit ](#-u---unit-)
     - [-t, --total ](#-t---total-)
     - [-d, --decimals ](#-d---decimals-)
@@ -117,45 +119,45 @@
     - [--nft, --ft](#--nft---ft)
     - [-n, --network ](#-n---network-)
     - [nfd-lookup](#nfd-lookup)
-    - [Options](#options-19)
+    - [Options](#options-20)
     - [-o, --output ](#-o---output--2)
     - [Arguments](#arguments-5)
     - [VALUE](#value)
     - [opt-in](#opt-in)
-    - [Options](#options-20)
+    - [Options](#options-21)
     - [-a, --account ](#-a---account-)
     - [-n, --network ](#-n---network--1)
     - [Arguments](#arguments-6)
     - [ASSET_IDS](#asset_ids)
     - [opt-out](#opt-out)
-    - [Options](#options-21)
+    - [Options](#options-22)
     - [-a, --account ](#-a---account--1)
     - [--all](#--all)
     - [-n, --network ](#-n---network--2)
     - [Arguments](#arguments-7)
     - [ASSET_IDS](#asset_ids-1)
     - [send](#send)
-    - [Options](#options-22)
+    - [Options](#options-23)
     - [-f, --file ](#-f---file--2)
     - [-t, --transaction ](#-t---transaction-)
     - [-n, --network ](#-n---network--3)
     - [sign](#sign)
-    - [Options](#options-23)
+    - [Options](#options-24)
     - [-a, --account ](#-a---account--2)
     - [-f, --file ](#-f---file--3)
     - [-t, --transaction ](#-t---transaction--1)
     - [-o, --output ](#-o---output--3)
     - [--force](#--force-1)
     - [transfer](#transfer)
-    - [Options](#options-24)
+    - [Options](#options-25)
     - [-s, --sender ](#-s---sender-)
     - [-r, --receiver ](#-r---receiver--1)
     - [--asset, --id ](#--asset---id-)
     - [-a, --amount ](#-a---amount--1)
     - [--whole-units](#--whole-units-2)
     - [-n, --network ](#-n---network--4)
     - [vanity-address](#vanity-address)
-    - [Options](#options-25)
+    - [Options](#options-26)
     - [-m, --match ](#-m---match-)
     - [-o, --output ](#-o---output--4)
     - [-a, --alias ](#-a---alias-)
@@ -164,19 +166,19 @@
     - [Arguments](#arguments-8)
     - [KEYWORD](#keyword)
     - [wallet](#wallet)
-    - [Options](#options-26)
+    - [Options](#options-27)
     - [-a, --address ](#-a---address-)
     - [-m, --mnemonic](#-m---mnemonic)
     - [-f, --force](#-f---force-1)
     - [Arguments](#arguments-9)
     - [ALIAS_NAME](#alias_name)
     - [Arguments](#arguments-10)
     - [ALIAS](#alias)
-    - [Options](#options-27)
+    - [Options](#options-28)
     - [-f, --force](#-f---force-2)
     - [Arguments](#arguments-11)
     - [ALIAS](#alias-1)
-    - [Options](#options-28)
+    - [Options](#options-29)
     - [-f, --force](#-f---force-3)
 
 # algokit
@@ -703,6 +705,12 @@ Start the AlgoKit LocalNet.
 algokit localnet start [OPTIONS]
 ```
 
+### Options
+
+
+### -n, --name <name>
+Specify a name for a custom LocalNet instance. AlgoKit will not manage the configuration of named LocalNet instances, allowing developers to configure it in any way they need.
+
 ### status
 
 Check the status of the AlgoKit LocalNet.

docs/features/localnet.md

@@ -26,7 +26,7 @@ We publish DockerHub images for `arm64` and `amd64`, which means that AlgoKit Lo
 
 ## Functionality
 
-### Creating / starting the LocalNet
+### Creating / Starting the LocalNet
 
 To create / start your AlgoKit LocalNet instance you can run `algokit localnet start`. This will:
 
@@ -46,15 +46,24 @@ Once they have downloaded, it won't try and re-download images unless you perfor
 Once the LocalNet has started, the following endpoints will be available:
 
 - [algod](https://developer.algorand.org/docs/rest-apis/algod/v2/):
-  - address: http://localhost:4001
+  - address: <http://localhost:4001>
   - token: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`
 - [kmd](https://developer.algorand.org/docs/rest-apis/kmd/):
-  - address: http://localhost:4002
+  - address: <http://localhost:4002>
   - token: `aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`
 - [indexer](https://developer.algorand.org/docs/rest-apis/indexer/):
-  - address: http://localhost:8980
+  - address: <http://localhost:8980>
 - tealdbg port:
-  - address: http://localhost:9392
+  - address: <http://localhost:9392>
+
+### Creating / Starting a Named LocalNet
+
+AlgoKit manages the default LocalNet environment and automatically keeps the configuration updated with any upstream changes. As a result, configuration changes are reset automatically by AlgoKit, so that developers always have access to a known good LocalNet configuration. This works well for the majority of scenarios, however sometimes developers need the control to make specific configuration changes for specific scenarios.
+
+When you want more control, named LocalNet instances can be used by running `algokit localnet start --name {name}`. This command will set up and run a named LocalNet environment (based off the default), however AlgoKit will not update the environment or configuration automatically. From here developers are able to modify their named environment in any way they like, for example setting `DevMode: false` in `algod_network_template.json`.
+
+Once you have a named LocalNet running, the AlgoKit LocalNet commands will target this instance.
+If at any point you'd like to switch back to the default LocalNet, simply run `algokit localnet start`.
 
 ### Stopping and Resetting the LocalNet
 
@@ -95,7 +104,7 @@ Needing to do this manual step every time you spin up a new development environm
 
 AlgoKit Utils provides methods to help you do this:
 
-* TypeScript - [`ensureFunded`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer.md#ensurefunded) and [`getDispenserAccount`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer.md#dispenser)
-* Python - [`ensure_funded`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.ensure_funded) and [`get_dispenser_account`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.get_dispenser_account)
+- TypeScript - [`ensureFunded`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer.md#ensurefunded) and [`getDispenserAccount`](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/docs/capabilities/transfer.md#dispenser)
+- Python - [`ensure_funded`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.ensure_funded) and [`get_dispenser_account`](https://algorandfoundation.github.io/algokit-utils-py/html/apidocs/algokit_utils/algokit_utils.html#algokit_utils.get_dispenser_account)
 
 For more details about the `AlgoKit localnet` command, please refer to the [AlgoKit CLI reference documentation](../cli/index.md#localnet).

src/algokit/cli/goal.py

@@ -9,7 +9,7 @@
     post_process,
     preprocess_command_args,
 )
-from algokit.core.sandbox import ComposeFileStatus, ComposeSandbox
+from algokit.core.sandbox import DEFAULT_NAME, ComposeFileStatus, ComposeSandbox
 
 logger = logging.getLogger(__name__)
 
@@ -34,8 +34,6 @@ def goal_command(*, console: bool, goal_args: list[str]) -> None:
 
     Look at https://developer.algorand.org/docs/clis/goal/goal/ for more information.
     """
-    volume_mount_path_local = get_volume_mount_path_local()
-    volume_mount_path_docker = get_volume_mount_path_docker()
     goal_args = list(goal_args)
     try:
         proc.run(["docker", "version"], bad_return_code_error_message="Docker engine isn't running; please start it.")
@@ -47,18 +45,27 @@ def goal_command(*, console: bool, goal_args: list[str]) -> None:
             "See https://docs.docker.com/get-docker/ for more information."
         ) from ex
 
-    sandbox = ComposeSandbox()
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is None:
+        sandbox = ComposeSandbox()
+
+    if sandbox.name != DEFAULT_NAME:
+        logger.info("A named LocalNet is running, goal command will be executed against the named LocalNet")
+
+    volume_mount_path_local = get_volume_mount_path_local(directory_name=sandbox.name)
+    volume_mount_path_docker = get_volume_mount_path_docker()
+
     compose_file_status = sandbox.compose_file_status()
-    if compose_file_status is not ComposeFileStatus.UP_TO_DATE:
+    if compose_file_status is not ComposeFileStatus.UP_TO_DATE and sandbox.name == DEFAULT_NAME:
         raise click.ClickException("LocalNet definition is out of date; please run `algokit localnet reset` first!")
 
     if console:
         if goal_args:
             logger.warning("--console opens an interactive shell, remaining arguments are being ignored")
         logger.info("Opening Bash console on the algod node; execute `exit` to return to original console")
-        result = proc.run_interactive("docker exec -it -w /root algokit_algod bash".split())
+        result = proc.run_interactive(f"docker exec -it -w /root algokit_{sandbox.name}_algod bash".split())
     else:
-        cmd = "docker exec --interactive --workdir /root algokit_algod goal".split()
+        cmd = f"docker exec --interactive --workdir /root algokit_{sandbox.name}_algod goal".split()
         input_files, output_files, goal_args = preprocess_command_args(
             goal_args, volume_mount_path_local, volume_mount_path_docker
         )

src/algokit/cli/localnet.py

@@ -6,6 +6,7 @@
 from algokit.cli.goal import goal_command
 from algokit.core import proc
 from algokit.core.sandbox import (
+    DEFAULT_NAME,
     DOCKER_COMPOSE_MINIMUM_VERSION,
     DOCKER_COMPOSE_VERSION_COMMAND,
     ComposeFileStatus,
@@ -57,31 +58,57 @@ def localnet_group() -> None:
 
 
 @localnet_group.command("start", short_help="Start the AlgoKit LocalNet.")
-def start_localnet() -> None:
-    sandbox = ComposeSandbox()
+@click.option(
+    "name",
+    "--name",
+    "-n",
+    default=None,
+    help="Specify a name for a custom LocalNet instance. "
+    "AlgoKit will not manage the configuration of named LocalNet instances, "
+    "allowing developers to configure it in any way they need.",
+)
+def start_localnet(name: str | None) -> None:
+    sandbox = ComposeSandbox.from_environment()
+    full_name = f"{DEFAULT_NAME}_{name}" if name is not None else DEFAULT_NAME
+    if sandbox is not None and full_name != sandbox.name:
+        logger.debug("LocalNet is already running.")
+        if click.confirm("This will stop any running AlgoKit LocalNet instance. Are you sure?", default=True):
+            sandbox.stop()
+        else:
+            raise click.ClickException("LocalNet is already running. Please stop it first")
+    sandbox = ComposeSandbox() if name is None else ComposeSandbox(name)
     compose_file_status = sandbox.compose_file_status()
     sandbox.check_docker_compose_for_new_image_versions()
-
     if compose_file_status is ComposeFileStatus.MISSING:
         logger.debug("LocalNet compose file does not exist yet; writing it out for the first time")
         sandbox.write_compose_file()
+        if name is not None:
+            logger.info(
+                f"The named LocalNet configuration has been created in {sandbox.directory}. \n"
+                f"You can edit the configuration by changing those files. "
+                f"Running `algokit localnet reset` will ensure the configuration is applied"
+            )
     elif compose_file_status is ComposeFileStatus.UP_TO_DATE:
         logger.debug("LocalNet compose file does not require updating")
-    else:
-        logger.warning("LocalNet definition is out of date; please run algokit localnet reset")
+    elif compose_file_status is ComposeFileStatus.OUT_OF_DATE and name is None:
+        logger.warning("LocalNet definition is out of date; please run `algokit localnet reset`")
+    if name is not None:
+        logger.info(
+            "A named LocalNet is running, update checks are disabled. If you wish to synchronize with the latest "
+            "version, run `algokit localnet reset --update`"
+        )
     sandbox.up()
 
 
 @localnet_group.command("stop", short_help="Stop the AlgoKit LocalNet.")
 def stop_localnet() -> None:
-    sandbox = ComposeSandbox()
-    compose_file_status = sandbox.compose_file_status()
-    if compose_file_status is ComposeFileStatus.MISSING:
-        logger.debug(
-            "LocalNet compose file does not exist yet; run `algokit localnet start` to start the AlgoKit LocalNet"
-        )
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is not None:
+        compose_file_status = sandbox.compose_file_status()
+        if compose_file_status is not ComposeFileStatus.MISSING:
+            sandbox.stop()
     else:
-        sandbox.stop()
+        logger.debug("LocalNet is not running; run `algokit localnet start` to start the AlgoKit LocalNet")
 
 
 @localnet_group.command("reset", short_help="Reset the AlgoKit LocalNet.")
@@ -91,12 +118,14 @@ def stop_localnet() -> None:
     help="Enable or disable updating to the latest available LocalNet version, default: don't update",
 )
 def reset_localnet(*, update: bool) -> None:
-    sandbox = ComposeSandbox()
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is None:
+        sandbox = ComposeSandbox()
     compose_file_status = sandbox.compose_file_status()
     if compose_file_status is ComposeFileStatus.MISSING:
         logger.debug("Existing LocalNet not found; creating from scratch...")
         sandbox.write_compose_file()
-    else:
+    elif sandbox.name == DEFAULT_NAME:
         sandbox.down()
         if compose_file_status is not ComposeFileStatus.UP_TO_DATE:
             logger.info("LocalNet definition is out of date; updating it to latest")
@@ -105,7 +134,20 @@ def reset_localnet(*, update: bool) -> None:
             sandbox.pull()
         else:
             sandbox.check_docker_compose_for_new_image_versions()
-
+    elif update:
+        if click.confirm(
+            f"A named LocalNet is running, are you sure you want to reset the LocalNet configuration "
+            f"in {sandbox.directory}?\nThis will stop the running LocalNet and overwrite any changes "
+            "you've made to the configuration",
+            default=True,
+        ):
+            sandbox.down()
+            sandbox.write_compose_file()
+            sandbox.pull()
+        else:
+            raise click.ClickException("LocalNet configuration has not been reset")
+    else:
+        sandbox.down()
     sandbox.up()
 
 
@@ -114,7 +156,9 @@ def reset_localnet(*, update: bool) -> None:
 
 @localnet_group.command("status", short_help="Check the status of the AlgoKit LocalNet.")
 def localnet_status() -> None:
-    sandbox = ComposeSandbox()
+    sandbox = ComposeSandbox.from_environment()
+    if sandbox is None:
+        sandbox = ComposeSandbox()
     ps = sandbox.ps()
     ps_by_name = {stats["Service"]: stats for stats in ps}
     # if any of the required containers does not exist (ie it's not just stopped but hasn't even been created),

src/algokit/core/goal.py

@@ -12,8 +12,8 @@ def get_volume_mount_path_docker() -> Path:
     return Path("/root/goal_mount/")
 
 
-def get_volume_mount_path_local() -> Path:
-    return get_app_config_dir().joinpath("sandbox", "goal_mount")
+def get_volume_mount_path_local(directory_name: str) -> Path:
+    return get_app_config_dir().joinpath(directory_name, "goal_mount")
 
 
 filename_pattern = re.compile(r"^[\w-]+\.\w+$")