Merge pull request #702 from algorandfoundation/feat/faster-localnet-start-reset

feat: reduce localnet start/reset time

Author: neilcampbell

docs/cli/index.md

@@ -127,30 +127,34 @@
     - [Options](#options-17)
     - [--update, --no-update](#--update---no-update)
     - [-P, --config-dir ](#-p---config-dir-)
+    - [--check](#--check)
     - [start](#start)
     - [Options](#options-18)
     - [-n, --name ](#-n---name--1)
     - [-P, --config-dir ](#-p---config-dir--1)
     - [-d, --dev, --no-dev](#-d---dev---no-dev)
     - [--force](#--force)
+    - [--check](#--check-1)
     - [status](#status)
+    - [Options](#options-19)
+    - [--check](#--check-2)
     - [stop](#stop)
   - [project](#project)
     - [bootstrap](#bootstrap)
-    - [Options](#options-19)
-    - [--force](#--force-1)
     - [Options](#options-20)
+    - [--force](#--force-1)
+    - [Options](#options-21)
     - [--interactive, --no-ci, --non-interactive, --ci](#--interactive---no-ci---non-interactive---ci)
     - [-p, --project-name ](#-p---project-name-)
     - [-t, --type ](#-t---type-)
-    - [Options](#options-21)
-    - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci)
     - [Options](#options-22)
-    - [--ci, --no-ci](#--ci---no-ci)
+    - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci)
     - [Options](#options-23)
+    - [--ci, --no-ci](#--ci---no-ci)
+    - [Options](#options-24)
     - [--ci, --no-ci](#--ci---no-ci-1)
     - [deploy](#deploy)
-    - [Options](#options-24)
+    - [Options](#options-25)
     - [-C, -c, --command ](#-c--c---command-)
     - [--interactive, --non-interactive, --ci](#--interactive---non-interactive---ci-1)
     - [-P, --path ](#-p---path-)
@@ -161,7 +165,7 @@
     - [ENVIRONMENT_NAME](#environment_name)
     - [EXTRA_ARGS](#extra_args)
     - [link](#link)
-    - [Options](#options-25)
+    - [Options](#options-26)
     - [-p, --project-name ](#-p---project-name--2)
     - [-l, --language ](#-l---language--1)
     - [-a, --all](#-a---all)
@@ -173,7 +177,7 @@
     - [run](#run)
   - [task](#task)
     - [analyze](#analyze)
-    - [Options](#options-26)
+    - [Options](#options-27)
     - [-r, --recursive](#-r---recursive)
     - [--force](#--force-2)
     - [--diff](#--diff)
@@ -182,11 +186,11 @@
     - [Arguments](#arguments-15)
     - [INPUT_PATHS](#input_paths)
     - [ipfs](#ipfs)
-    - [Options](#options-27)
+    - [Options](#options-28)
     - [-f, --file ](#-f---file--1)
     - [-n, --name ](#-n---name--2)
     - [mint](#mint)
-    - [Options](#options-28)
+    - [Options](#options-29)
     - [--creator ](#--creator-)
     - [--name ](#--name-)
     - [-u, --unit ](#-u---unit-)
@@ -198,45 +202,45 @@
     - [--mutable, --immutable](#--mutable---immutable)
     - [-n, --network ](#-n---network-)
     - [nfd-lookup](#nfd-lookup)
-    - [Options](#options-29)
+    - [Options](#options-30)
     - [-o, --output ](#-o---output--3)
     - [Arguments](#arguments-16)
     - [VALUE](#value)
     - [opt-in](#opt-in)
-    - [Options](#options-30)
+    - [Options](#options-31)
     - [-a, --account ](#-a---account-)
     - [-n, --network ](#-n---network--1)
     - [Arguments](#arguments-17)
     - [ASSET_IDS](#asset_ids)
     - [opt-out](#opt-out)
-    - [Options](#options-31)
+    - [Options](#options-32)
     - [-a, --account ](#-a---account--1)
     - [--all](#--all)
     - [-n, --network ](#-n---network--2)
     - [Arguments](#arguments-18)
     - [ASSET_IDS](#asset_ids-1)
     - [send](#send)
-    - [Options](#options-32)
+    - [Options](#options-33)
     - [-f, --file ](#-f---file--2)
     - [-t, --transaction ](#-t---transaction-)
     - [-n, --network ](#-n---network--3)
     - [sign](#sign)
-    - [Options](#options-33)
+    - [Options](#options-34)
     - [-a, --account ](#-a---account--2)
     - [-f, --file ](#-f---file--3)
     - [-t, --transaction ](#-t---transaction--1)
     - [-o, --output ](#-o---output--4)
     - [--force](#--force-3)
     - [transfer](#transfer)
-    - [Options](#options-34)
+    - [Options](#options-35)
     - [-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-35)
+    - [Options](#options-36)
     - [-m, --match ](#-m---match-)
     - [-o, --output ](#-o---output--5)
     - [-a, --alias ](#-a---alias-)
@@ -245,19 +249,19 @@
     - [Arguments](#arguments-19)
     - [KEYWORD](#keyword)
     - [wallet](#wallet)
-    - [Options](#options-36)
+    - [Options](#options-37)
     - [-a, --address ](#-a---address-)
     - [-m, --mnemonic](#-m---mnemonic)
     - [-f, --force](#-f---force-4)
     - [Arguments](#arguments-20)
     - [ALIAS_NAME](#alias_name)
     - [Arguments](#arguments-21)
     - [ALIAS](#alias)
-    - [Options](#options-37)
+    - [Options](#options-38)
     - [-f, --force](#-f---force-5)
     - [Arguments](#arguments-22)
     - [ALIAS](#alias-1)
-    - [Options](#options-38)
+    - [Options](#options-39)
     - [-f, --force](#-f---force-6)
 
 # algokit
@@ -918,6 +922,10 @@ Enable or disable updating to the latest available LocalNet version, default: do
 ### -P, --config-dir <config_path>
 Specify the custom localnet configuration directory.
 
+
+### --check
+Force check the Docker registry for new LocalNet image versions, ignoring the version check cache.
+
 ### start
 
 Start the AlgoKit LocalNet.
@@ -944,6 +952,10 @@ Control whether to launch 'algod' in developer mode or not. Defaults to 'yes'.
 ### --force
 Ignore the prompt to stop the LocalNet if it's already running.
 
+
+### --check
+Force check the Docker registry for new LocalNet image versions, ignoring the version check cache.
+
 ### status
 
 Check the status of the AlgoKit LocalNet.
@@ -952,6 +964,12 @@ Check the status of the AlgoKit LocalNet.
 algokit localnet status [OPTIONS]
 ```
 
+### Options
+
+
+### --check
+Force check the Docker registry for new LocalNet image versions, ignoring the version check cache.
+
 ### stop
 
 Stop the AlgoKit LocalNet.

pyproject.toml

@@ -168,7 +168,9 @@ suppress-none-returning = true
 pythonpath = ["src", "tests"]
 markers = [
     "mock_platform_system",
-    "pyinstaller_binary_tests"
+    "pyinstaller_binary_tests",
+    "use_real_image_version_cache: opt-out of the auto-mocked image version cache checks"
+
 ]
 addopts = "-m 'not pyinstaller_binary_tests'" # by default, exclude pyinstaller_binary_tests
 [tool.mypy]

src/algokit/cli/localnet.py

@@ -24,6 +24,14 @@
 
 logger = logging.getLogger(__name__)
 
+check_option = click.option(
+    "check",
+    "--check",
+    is_flag=True,
+    default=False,
+    help="Force check the Docker registry for new LocalNet image versions, ignoring the version check cache.",
+)
+
 
 @click.group("localnet", short_help="Manage the AlgoKit LocalNet.")
 @click.pass_context
@@ -157,7 +165,10 @@ def config_command(*, engine: str | None, force: bool) -> None:
     default=False,
     help="Ignore the prompt to stop the LocalNet if it's already running.",
 )
-def start_localnet(*, name: str | None, config_path: Path | None, algod_dev_mode: bool, force: bool) -> None:
+@check_option
+def start_localnet(
+    *, name: str | None, config_path: Path | None, algod_dev_mode: bool, force: bool, check: bool
+) -> None:
     sandbox = ComposeSandbox.from_environment()
     full_name = f"{SANDBOX_BASE_NAME}_{name}" if name is not None else SANDBOX_BASE_NAME
     if sandbox is not None and full_name != sandbox.name:
@@ -168,7 +179,7 @@ def start_localnet(*, name: str | None, config_path: Path | None, algod_dev_mode
             raise click.ClickException("LocalNet is already running. Please stop it first")
     sandbox = ComposeSandbox(SANDBOX_BASE_NAME, config_path) if name is None else ComposeSandbox(name, config_path)
     compose_file_status = sandbox.compose_file_status()
-    sandbox.check_docker_compose_for_new_image_versions()
+    sandbox.check_docker_compose_for_new_image_versions(force=check)
     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()
@@ -227,7 +238,8 @@ def stop_localnet() -> None:
     required=False,
     help="Specify the custom localnet configuration directory.",
 )
-def reset_localnet(*, update: bool, config_path: Path | None) -> None:
+@check_option
+def reset_localnet(*, update: bool, config_path: Path | None, check: bool) -> None:
     sandbox = ComposeSandbox.from_environment()
     if sandbox is None:
         sandbox = ComposeSandbox(config_path=config_path)
@@ -243,7 +255,7 @@ def reset_localnet(*, update: bool, config_path: Path | None) -> None:
         if update:
             sandbox.pull()
         else:
-            sandbox.check_docker_compose_for_new_image_versions()
+            sandbox.check_docker_compose_for_new_image_versions(force=check)
     elif update:
         if click.confirm(
             f"A named LocalNet is running, are you sure you want to reset the LocalNet configuration "
@@ -265,11 +277,14 @@ def reset_localnet(*, update: bool, config_path: Path | None) -> None:
 
 
 @localnet_group.command("status", short_help="Check the status of the AlgoKit LocalNet.")
-def localnet_status() -> None:
+@check_option
+def localnet_status(*, check: bool) -> None:
     sandbox = ComposeSandbox.from_environment()
     if sandbox is None:
         sandbox = ComposeSandbox()
 
+    sandbox.check_docker_compose_for_new_image_versions(force=check)
+
     logger.info("# container engine")
     logger.info(
         "Name: " + click.style(get_container_engine(), bold=True) + " (change with `algokit config container-engine`)"

src/algokit/core/sandbox.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
+import dataclasses
 import enum
 import json
 import logging
 import re
 import time
+from datetime import timedelta
 from pathlib import Path
 from typing import Any, cast
 
 import httpx
 
-from algokit.core.conf import get_app_config_dir
+from algokit.core.conf import get_app_config_dir, get_app_state_dir
 from algokit.core.config_commands.container_engine import get_container_engine
 from algokit.core.proc import RunResult, run, run_interactive
 
@@ -219,6 +221,8 @@ def down(self) -> None:
     def pull(self) -> None:
         logger.info("Fetching any container updates from DockerHub...")
         self._run_compose_command("pull --ignore-pull-failures --quiet")
+        logger.debug("Image version cache reset")
+        _update_image_version_cache(indexer_outdated=False, algod_outdated=False)
 
     def logs(self, *, follow: bool = False, no_color: bool = False, tail: str | None = None) -> None:
         compose_args = ["logs"]
@@ -284,15 +288,28 @@ def is_image_up_to_date(self, image_name: str) -> bool:
         latest_version = self._get_latest_image_version(image_name)
         return latest_version is None or latest_version in local_versions
 
-    def check_docker_compose_for_new_image_versions(self) -> None:
-        is_indexer_up_to_date = self.is_image_up_to_date(INDEXER_IMAGE)
-        if is_indexer_up_to_date is False:
+    def check_docker_compose_for_new_image_versions(self, *, force: bool = False) -> None:
+        should_check_registry = force or _should_check_image_versions()
+
+        if should_check_registry:
+            # Check Docker registry for new versions
+            is_indexer_outdated = not self.is_image_up_to_date(INDEXER_IMAGE)
+            is_algod_outdated = not self.is_image_up_to_date(ALGORAND_IMAGE)
+            _update_image_version_cache(indexer_outdated=is_indexer_outdated, algod_outdated=is_algod_outdated)
+        else:
+            # Use cached state
+            cached_state = _get_image_version_cache()
+            if cached_state is None:
+                return
+            is_indexer_outdated = cached_state.indexer_outdated
+            is_algod_outdated = cached_state.algod_outdated
+
+        if is_indexer_outdated:
             logger.warning(
                 "indexer has a new version available, run `algokit localnet reset --update` to get the latest version"
             )
 
-        is_algorand_up_to_date = self.is_image_up_to_date(ALGORAND_IMAGE)
-        if is_algorand_up_to_date is False:
+        if is_algod_outdated:
             logger.warning(
                 "algod has a new version available, run `algokit localnet reset --update` to get the latest version"
             )
@@ -312,6 +329,65 @@ def check_docker_compose_for_new_image_versions(self) -> None:
 INDEXER_IMAGE = "algorand/indexer:latest"
 ALGORAND_IMAGE = "algorand/algod:latest"
 CONDUIT_IMAGE = "algorand/conduit:latest"
+IMAGE_VERSION_CHECK_INTERVAL = timedelta(weeks=1).total_seconds()
+
+
+@dataclasses.dataclass
+class ImageVersionCache:
+    """Cache state for image version checks."""
+
+    indexer_outdated: bool
+    algod_outdated: bool
+
+
+def _get_image_version_cache_path() -> Path:
+    """Get the path to the image version check cache file."""
+    return get_app_state_dir() / "last-localnet-version-check"
+
+
+def _get_image_version_cache() -> ImageVersionCache | None:
+    """Get the cached image version state.
+
+    Returns an ImageVersionCache with outdated flags, or None if cache is missing/invalid.
+    """
+    cache_path = _get_image_version_cache_path()
+    try:
+        content = cache_path.read_text(encoding="utf-8")
+        data = json.loads(content)
+        return ImageVersionCache(
+            indexer_outdated=data.get("indexer_outdated", False),
+            algod_outdated=data.get("algod_outdated", False),
+        )
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _should_check_image_versions() -> bool:
+    """Determine if we should check for new image versions based on cache."""
+    cache_path = _get_image_version_cache_path()
+    try:
+        last_checked = cache_path.stat().st_mtime
+    except OSError:
+        logger.debug(f"{cache_path} inaccessible, will check for image updates")
+        return True
+
+    elapsed = time.time() - last_checked
+    if elapsed > IMAGE_VERSION_CHECK_INTERVAL:
+        logger.debug("Image version cache expired, will check for updates")
+        return True
+
+    logger.debug(f"Skipping image version check, last checked {elapsed / 3600:.1f}h ago")
+    return False
+
+
+def _update_image_version_cache(*, indexer_outdated: bool, algod_outdated: bool) -> None:
+    """Update the image version check cache with current state."""
+    cache_path = _get_image_version_cache_path()
+    try:
+        cache_data = {"indexer_outdated": indexer_outdated, "algod_outdated": algod_outdated}
+        cache_path.write_text(json.dumps(cache_data), encoding="utf-8")
+    except OSError as ex:
+        logger.debug(f"Failed to update image version cache: {ex}")
 
 
 def _wait_for_service(