feat: start network docker container with cli

[elizabethengelman]

What

This PR adds the network start and network stop subcommands to allow users to start and stop the stellar docker container using the CLI.

Start help output

$ soroban network start --help
Start network

This command allows for starting a stellar quickstart container. To run it, you can use the following command: `soroban network start <NETWORK> [OPTIONS]`

By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command: docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc

Usage: soroban network start [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>
          Network to start

          [possible values: local, testnet, futurenet, pubnet]

Options:
  -d, --docker-socket-path <DOCKER_SOCKET_PATH>
          Optional argument to override the default docker socket path. This is useful when you are using a non-standard docker socket path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock

  -l, --limit <LIMIT>
          Optional argument to specify the limits for the local network only

  -p, --ports-mapping <PORTS_MAPPING>...
          Argument to specify the HOST_PORT:CONTAINER_PORT mapping

          [default: 8000:8000]

  -r, --disable-soroban-rpc
          Optional argument to turn off soroban rpc

  -t, --image-tag-override <IMAGE_TAG_OVERRIDE>
          Optional argument to override the default docker image tag for the given network

  -v, --protocol-version <PROTOCOL_VERSION>
          Optional argument to specify the protocol version for the local network only

  -h, --help
          Print help (see a summary with '-h')

Stop help output

$ soroban network stop --help
Stop network

Usage: soroban network stop [OPTIONS] <NETWORK>

Arguments:
  <NETWORK>  Network to stop [possible values: local, testnet, futurenet, pubnet]

Options:
  -d, --docker-socket-path <DOCKER_SOCKET_PATH>
          Optional argument to override the default docker socket path. This is useful when you are using a non-standard docker socket path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock
  -h, --help
          Print help

Output when the command is not able to connect to the docker daemon

$ soroban network start testnet
ℹ️  Starting testnet network
⛔️ Failed to connect to the Docker daemon at "/var/run/docker.sock". Is the docker daemon running?
ℹ️  Running a local Stellar network requires a Docker-compatible container runtime.
ℹ️  Please note that if you are using Docker Desktop, you may need to utilize the `--docker-socket-path` flag to pass in the location of the docker socket on your machine.

error: ⛔ ️Failed to start container: error trying to connect: No such file or directory (os error 2)

Output when the command starts the container successfully

ℹ️  Starting testnet network
✅ Container started: stellar-testnet
ℹ️  To stop this container run: soroban network stop testnet --docker-socket-path /Users/elizabethengelman/.docker/run/docker.sock

Why

To make it easier for users to run a stellar node for soroban development.

Known limitations

I learned that when using Docker Desktop, it starts the docker daemon on a non-standard socket 😵‍💫 . The Docker Desktop UI allows a user to overwrite this, in an advanced setting. But I figured allowing the user to do this all via the CLI would probably be easier, so I added the --docker-socket-path flag. I think that it may be helpful to allow the user to set an env var for this, instead of always passing a flag, but I'll plan to allow for this in a followup PR.

resources that helped identify this:
- fussybeaver/bollard#345 (suggestion of using DOCKER_HOST env var did not work)
- https://docs.docker.com/desktop/mac/permission-requirements/
- https://devops.stackexchange.com/questions/17905/ctop-does-not-work-with-latest-version-of-docker-get-http-unix-sock-info-d#:~:text=This%20is%20probably%20because%20Docker,sock%20anymore.&text=If%20you%20want%20to%20have,used%20and%20press%20Apply%20%26%20restart%20.

Todo

• handle unwraps more gracefully
• revisit errors / error handling
• pull shared stuff out into a shared module (specifically docker connect stuff)
• address the rest of https://github.com/stellar/soroban-tools/pull/1107/files#r1456367830
• document how / why you need to override the socket path for docker desktop
• make sure i have the correct default image tags
• address feat: start network docker container with cli #1107 (comment)
• address feat: start network docker container with cli #1107 (comment)

To handle in a followup PR

• allow for mounting volumes
• add a healthcheck, and don’t release the control back to the command line until container is healthy, see feat: start network docker container with cli #1107 (comment)
• add the ability to have it be non-detached mode. and allowing it to stream the output of the container. Or just tell them how to attach and see the logs?
• put a link to some docs explaining more about connecting to docker, see feat: start network docker container with cli #1107 (comment)
• allow for users to pass in their non-standard docker socket path in an env var instead of just --docker-socket-path

[willemneal]

Looks great! Just one nit about using expect vs using an error. The error lets you capture the failed command.

You can use .map_error(|_| Error::CommandFailed(docker_command.clone()))?. This let's you use your own error and the inner anonymous function only executes if there was an error.

[chadoh]

Solid start! Marking as "request changes" for the various doc comment stuff. The "start in detached by default with more complex health checks" thing (see comment below) would be awesome, but we could also do it in a follow-up to this one. It's already v useful to have these commands, so it might not be worth holding it up. lmk if you think we should do it at all, and if so, if we should do it now or wait for later.

[chadoh]

I also think it would be really cool if we checked if Docker Daemon is running and, if not, rather than allowing Docker's error message to bubble through:

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.

...we could instruct them on how to install colima. OR, we could automatically install it for them? (We could offer, and if they say y, then we could go ahead with it. But even then it seems error-prone, doesn't it?) If colima is already installed, then maybe we just automatically start a colima network called stellar? Not sure if we would also want to stop the colima network when we soroba network stop the last network—probably not?

I don't think we need to be all-in on colima, though. If there are other alternatives to Docker Desktop/Daemon like it, then we could check for those, too. And in any case, rather than bubbling the cannot connect to docker daemon error, we could throw a message that's more instructive & actionable. Maybe something along the lines of:

Running a local Stellar network requires a Docker-compatible container runtime. You can:
- install/open Docker Desktop: https://www.docker.com/products/docker-desktop/
- install/run colima: https://github.com/abiosoft/colima

Or maybe we sniff their OS and recommend colima only if they're on a Mac, podman if linux, and containerd if Windows, which are the suggestions in this blog post. I don't know. But I want to make sure we make this feel doable to total Docker & Stellar newbies who try to start a local dev environment with soroban network start.

[leighmcculloch]

Rather than hardcoding specific recommendations into the CLI, I think we should have a message similar to what's displayed above, but link to the soroban.stellar.org docs and place a page there with links out to docker/container runtimes folks can try, with recs based on mac, linux, windows. It means we can update the list as needed.

I'd also keep the original error. Never know what type of useful information might be found by passing through errors:

docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.
Running a local Stellar network requires a docker-compatible container runtime.
See this url for a list of some common container runtimes to install: https://soroban.stellar.org/container-runtimes

[elizabethengelman]

@chadoh @leighmcculloch Regarding the error case when the docker daemon can’t be found - I realized that when using bollard (and the underlying Docker API) it doesn’t seem to bubble up the original error ( docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?) but instead returns a kind of vague Hyper error: error trying to connect: No such file or directory (os error 2)

So instead, I’m priting out a message similar to Cannot connect…, and that is where we can also include a link to the docs when we have a page for that message, which I can work on in a followup.

ℹ️  Starting testnet network
⛔️ Failed to connect to the Docker daemon at "/var/run/docker.sock". Is the docker daemon running?
Running a local Stellar network requires a Docker-compatible container runtime.
Please note that if you are using Docker Desktop, you may need to utilize the `--docker-socket-path` flag to pass in the location of the docker socket on your machine.

error: ⛔ ️Failed to start container: error trying to connect: No such file or directory (os error 2)