sandbox approach
- Status: Approved
- Owner: Rob Moore
- Deciders: Anne Kenyon (Algorand Inc.), Alessandro Cappellato (Algorand Foundation), Will Winder (Algorand Inc.)
- Date created: 2022-11-14
- Date decided: 2022-11-14
- Date updated: 2022-11-16
Context¶
In order for AlgoKit to facilitate a productive development experience it needs to provide a managed Algorand sandbox experience. This allows developers to run an offline (local-only) private instance of Algorand that they can privately experiment with, run automated tests against and reset at will.
Requirements¶
- The sandbox works cross-platform (i.e. runs natively on Windows, Mac and Linux)
- You can spin up algod and indexer since both have useful use cases when developing
- The sandbox is kept up to date with the latest version of algod / indexer
- There is access to KMD so that you can programmatically fund accounts to improve the developer experience and reduce manual effort
- There is access to the tealdbg port outside of algod so you can attach a debugger to it
- The sandbox is isolated and (once running) works offline so the workload is private, allows development when there is no internet (e.g. when on a plane) and allows for multiple instances to be run in parallel (e.g. when developing multiple independent projects simultaneously)
- Works in continuous integration and local development environments so you can facilitate automated testing
Principles¶
- AlgoKit Guiding Principles - specifically Seamless onramp, Leverage existing ecosystem, Meet devs where they are
- Lightweight - the solution should have as low an impact as possible on resources on the developers machine
- Fast - the solution should start quickly, which makes for a nicer experience locally and also allows it to be used for continuous integration automation testing
Options¶
Option 1 - Pre-built DockerHub images¶
Pre-built application developer-optimised DockerHub images that work cross-platform; aka an evolved AlgoKit version of https://github.com/MakerXStudio/algorand-sandbox-dev.
Pros
- It's quick to download the images and quick to start the container since you don't need to compile Algod / indexer and the images are optimised for small size
- The only dependency needed is Docker, which is a fairly common dependency for most developers to use these days
- The images are reasonably lightweight
- The images provide an optimised application developer experience with: (devmode) algo, KMD, tealdbg, indexer
- It natively works cross-platform
Cons
- Some people have reported problems running WSL 2 on a small proportion of Windows environments (to get the latest Docker experience)
- Docker within Docker can be a problem in some CI environments that run agents on Docker in the first place
- Work needs to be done to create an automated CI/CD that automatically releases new versions to keep it up to date with latest algod/indexer versions
Option 2 - Lightweight algod client implementation¶
Work with the Algorand Inc. team to get a lightweight algod client that can run outside of a Docker container cross-platform.
Pros
- Likely to be the most lightweight and fastest option - opening up better/easier isolated/parallelised automated testing options
- Wouldn't need Docker as a dependency
Cons
- Indexer wouldn't be supported (Postgres would require Docker anyway)
- Algorand Inc. does not distribute Windows binaries.
Option 3 - Sandbox¶
Use the existing Algorand Sandbox.
Pros
- Implicitly kept up to date with Algorand - no extra thing to maintain
- Battle-tested by the core Algorand team day-in-day-out
- Supports all environments including unreleased feature branches (because it can target a git repo / commit hash)
Cons
- Sandbox is designed for network testing, not application development - it's much more complex than the needs of application developers
- Slow to start because it has to download and built algod and indexer (this is particularly problematic for ephemeral CI/CD build agents)
- It's not cross-platform (it requires bash to run sandbox.sh, although a sandbox.ps1 version could be created)
Preferred option¶
Option 1 and Option 2.
Option 1 provides a fully-featured experience that will work great in most scenarios, having option 2 as a second option would open up more advanced parallel automated testing scenarios in addition to that.
Selected option¶
Option 1
We're aiming to release the first version of AlgoKit within a short timeframe, which won't give time for Option 2 to be developed. Sandbox itself has been ruled out since it's not cross-platform and is too slow for both development and continuous integration.
Option 1 also results in a similar result to running Sandbox, so existing Algorand documentation, libraries and approaches should work well with this option making it a good slot-in replacement for Sandbox for application developers.
AlgoKit is designed to be modular: we can add in other approaches over time such as Option 2 when/if it becomes available.