docs: simplify installation guide and clarify Windows Docker requirements (#292)

Author: marc0olo

docs/containers.md

@@ -50,7 +50,7 @@ The network is expected to have the ICP ledger, the cycles ledger, and the cycle
 
 The gateway port of the network must be bound to a host port (permitted to be 0). Containerized network configurations can have the following fields:
 
-- `port-bindings`: []string, mandatory if an image is specified, in `host:container` format. There must be an entry for the gateway port.
+- `port-mapping`: []string, mandatory if an image is specified, in `host:container` format. There must be an entry for the gateway port.
 - `rm-on-exit`: bool, default false, deletes the container when the network is stopped
 - `args`: []string, appended to the container's entrypoint
 - `entrypoint`: []string, entrypoint executable for the container
@@ -62,6 +62,12 @@ The gateway port of the network must be bound to a host port (permitted to be 0)
 - `shm-size`: uint, size of `/dev/shm` in bytes.
 - `status-dir`: string, default `/app/status`, the status directory mentioned above.
 
-## Windows with WSL2 `dockerd`
+## Windows
 
-`icp-cli` will automatically integrate with Docker Desktop's support for WSL2; if unconfigured, it should Just Work. However, if you want to use a manually instantiated `dockerd` in a WSL2 instance serving local TCP, you can set `ICP_CLI_DOCKER_WSL2_DISTRO=<distro>` (as well as `DOCKER_HOST=tcp://<ip>:<port>`). Remote containers are not supported since `icp-cli` makes use of bind mounts; for this purpose you can use 'connected' networks instead of 'managed'.
+`icp-cli` automatically integrates with Docker Desktop on Windows (works with both Hyper-V and WSL2 backends). No configuration is needed—it should Just Work.
+
+### Advanced: Manual `dockerd` in WSL2
+
+If you want to use a manually instantiated `dockerd` in a WSL2 instance (instead of Docker Desktop), you can set:
+- `ICP_CLI_DOCKER_WSL2_DISTRO=<distro>` — the WSL2 distribution name running dockerd
+- `DOCKER_HOST=tcp://<ip>:<port>` — the TCP address where dockerd is listening

docs/guides/installation.md

@@ -1,14 +1,18 @@
 # Installation
 
-Install icp-cli on macOS, Linux, or Windows (WSL).
+Install icp-cli on macOS, Linux, or Windows.
 
-## macOS
+## macOS / Linux / WSL
+
+**Homebrew (macOS):**
 
 ```bash
 brew install dfinity/tap/icp-cli
 ```
 
-**Bash/Curl**
+To update later: `brew upgrade dfinity/tap/icp-cli`
+
+**Curl installer:**
 
 ```bash
 # install icp-cli
@@ -18,64 +22,22 @@ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/release
 curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/ic-wasm/releases/download/0.9.10/ic-wasm-installer.sh | sh
 ```
 
-**PowerShell (Windows)**
-
-```ps1
-# install icp-cli
-powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/download/v0.30.3/cargo-dist-installer.ps1 | iex"
-
-# install ic-wasm which is a dependency for many recipes
-powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinitiy/ic-wasm/releases/download/v0.9.11/ic-wasm-installer.ps1 | iex"
-```
-
-**From source:**
-
-Cargo is required as a pre-requisite.
-
-```bash
-git clone https://github.com/dfinity/icp-cli.git
-cd icp-cli && cargo build --release
-export PATH=$(pwd)/target/release:$PATH
-```
-
-Verify installation:
-
-```bash
-icp --version
-```
-
-## Installation Methods
-
-### Homebrew (macOS)
-
-The recommended installation method for macOS:
-
-```bash
-brew install dfinity/tap/icp-cli
-```
-
-To update later:
-
-```bash
-brew upgrade dfinity/tap/icp-cli
-```
-
-## Linux / WSL
-
-```bash
-curl --proto '=https' --tlsv1.2 -LsSf https://github.com/dfinity/icp-cli/releases/download/v0.1.0-beta.3/icp-cli-installer.sh | sh
-```
-
 The installer adds icp-cli to your PATH automatically. Restart your shell or run the `source` command shown by the installer.
 
 ## Windows
 
 ```ps1
+# install icp-cli
 powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/icp-cli/releases/download/v0.1.0-beta.3/icp-cli-installer.ps1 | iex"
+
+# install ic-wasm which is a dependency for many recipes
+powershell -ExecutionPolicy Bypass -c "irm https://github.com/dfinity/ic-wasm/releases/download/v0.9.11/ic-wasm-installer.ps1 | iex"
 ```
 
 The installer adds icp-cli to your PATH automatically. Restart your shell (and if it's inside another program, e.g. the VS Code embedded shell, restart that program too).
 
+**Docker requirement:** If you want to run a local test network, you'll need [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/). Docker is only required for local networks—you can build canisters and deploy to mainnet without it.
+
 ## Verify Installation
 
 ```bash
@@ -99,13 +61,6 @@ npm install -g ic-mops
 mops toolchain init
 ```
 
-## Other dependencies
-
-### Docker/WSL2 (Windows)
-
-On Windows, the local network will be run in a Docker container inside WSL2. It is recommended to install [Docker Desktop](https://www.docker.com/products/docker-desktop/) with WSL2 integration, but a manually run `dockerd` instance is [also supported](docs/containers.md).
-
-Docker is also a dependency for projects that manually configure their network to be container-based.
 
 ## Troubleshooting
 
@@ -119,6 +74,12 @@ export PATH="$HOME/.cargo/bin:$PATH"
 
 Then restart your shell or run `source ~/.bashrc` (or `~/.zshrc`).
 
+**"Cannot connect to Docker" (Windows)**
+
+On Windows, Docker Desktop must be running before starting a local network. Ensure:
+- Docker Desktop is installed and running
+- For manual `dockerd` setup with WSL2, see [containers.md](../containers.md)
+
 **Network launcher download fails**
 
 The network launcher downloads automatically on first use. If it fails: