From cf3e9e95f636c4eb8f2a64badc21f24da7cf7172 Mon Sep 17 00:00:00 2001 From: Tung Bui Date: Mon, 13 Jul 2026 09:37:30 +0700 Subject: [PATCH] docs: add Windows (PowerShell host) usage guide All examples elsewhere in the repo are written for a Bash host shell. Add docs/usage/windows_usage.md translating the README quick-start and run_mode.md examples to PowerShell syntax (backtick line continuation, ${PWD}/$HOME path interpolation, mounting the current directory to a plain Linux path like /workspace instead of mirroring the Windows path inside the container). This is a different topic from the existing powershell_usage.md, which covers using pwsh *inside* the container - both docs now cross-link to avoid confusing the two. Linked from docs/usage/README.md and from the README's Getting Started section. --- README.md | 2 + docs/usage/README.md | 4 ++ docs/usage/windows_usage.md | 113 ++++++++++++++++++++++++++++++++++++ 3 files changed, 119 insertions(+) create mode 100644 docs/usage/windows_usage.md diff --git a/README.md b/README.md index a2cc1a2..e21b929 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ ## Getting Started +> The commands below are written for a Bash host shell. Running from a Windows PowerShell host? See [**windows_usage**](./docs/usage/windows_usage.md) for the PowerShell-syntax equivalents. + ### 1. Quick Start ```bash diff --git a/docs/usage/README.md b/docs/usage/README.md index 74fab4d..cde5da9 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -42,6 +42,10 @@ This guide us how to use the `devops-toolkit` with serveral usecases - Check [**powershell_usage**](./powershell_usage.md) +## Windows (PowerShell host) + +- Running the toolkit from a Windows PowerShell host? Check [**windows_usage**](./windows_usage.md) + ## Troubleshooting - For any issues, check [this document](../troubleshooting/TROUBLESHOOTING.md) diff --git a/docs/usage/windows_usage.md b/docs/usage/windows_usage.md new file mode 100644 index 0000000..16e95ef --- /dev/null +++ b/docs/usage/windows_usage.md @@ -0,0 +1,113 @@ +# Use devops-toolkit on Windows (PowerShell host) + +## Overview + +This guide is for Windows users running commands from a PowerShell host - either +Windows PowerShell 5.1 (built into Windows) or PowerShell 7+ (`pwsh`) - who want +to run the devops-toolkit container. + +Most examples elsewhere in this repo (README, [run_mode.md](./run_mode.md), the +other `*_usage.md` docs) are written for a Bash host shell. This page translates +them to PowerShell syntax. + +> Looking for how to use PowerShell (`pwsh`) *inside* the running container +> instead? See [powershell_usage.md](./powershell_usage.md). + +## Prerequisite + +- [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/), with the WSL2 backend enabled (recommended) +- Windows PowerShell 5.1 (built into Windows) or [PowerShell 7+](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) + +## Key differences from the Bash examples in this repo + +1. **Line continuation**: PowerShell uses a backtick (`` ` ``) at the end of a + line instead of Bash's backslash (`\`). +2. **Current directory**: use `${PWD}` instead of Bash's `$PWD` - PowerShell + interpolates it to the same plain path string (e.g. `C:\Users\you\project`). +3. **Home directory**: `$HOME` works the same in PowerShell as in Bash (both + Windows PowerShell 5.1 and PowerShell 7+ define it) - `$env:USERPROFILE` is + the classic Windows equivalent if you prefer it. +4. **Mounting a Windows path into the Linux container**: pick a plain Linux-side + mount point like `/workspace` rather than mirroring the Windows path on both + sides of `-v` - a container path like `C:\Users\you\project` is legal but + awkward, since Linux has no concept of drive letters. + +## Run with Docker command + +### Use case 1: Quick start + +```powershell +New-Item -ItemType Directory -Force "$HOME\.dtc" | Out-Null # Skip if you already created the configuration folder before +docker pull tungbq/devops-toolkit:latest +docker run -it --rm --name devops-toolkit-demo1 ` + -v "${HOME}\.dtc:/dtc" ` + --network host ` + tungbq/devops-toolkit:latest +``` + +### Use case 2: Mount the current directory and a config folder + +```powershell +docker run -it --name devops-toolkit-demo2 ` + --volume "${PWD}:/workspace" ` + --volume "${HOME}\.dtc:/dtc" ` + --volume "${HOME}\.ssh:/root/.ssh" ` + --workdir /workspace ` + --network host ` + tungbq/devops-toolkit:latest + +# Adjust the docker run command based on your use case +``` + +### Use case 3: Mount individual tool configs from the host + +```powershell +docker run -it --name devops-toolkit-demo3 ` + --volume "${HOME}\.aws:/root/.aws" ` + --volume "${HOME}\.azure:/root/.azure" ` + --volume "${HOME}\.kube:/root/.kube" ` + --volume "${HOME}\.terraform.d:/root/.terraform.d" ` + --volume "${HOME}\.config\helm:/root/.config/helm" ` + --volume "${HOME}\.ansible:/root/.ansible" ` + --volume "${HOME}\.gitconfig:/root/.gitconfig" ` + --volume "${HOME}\.ssh:/root/.ssh" ` + --volume "${PWD}:/workspace" ` + --workdir /workspace ` + --network host ` + tungbq/devops-toolkit:latest + +# Adjust the docker run command based on your use case +``` + +### Use case 4: Attach to an already-running container + +```powershell +docker exec -it my_devops_toolkit /bin/bash +``` + +Sample Result + +```text +PS C:\Users\you> docker run -it --rm --name devops-toolkit-demo1 -v "${HOME}\.dtc:/dtc" --network host tungbq/devops-toolkit:latest +Custom configuration directory detected. Setting up symlinks... +root@a1b2c3d4e5f6:~# +``` + +### Note + +- Common run options (interactive mode, container naming, keeping vs. removing + the container, etc.) are the same as documented in + [run_mode.md](./run_mode.md) - only the PowerShell line-continuation and path + syntax above change. +- `--network host` needs Docker Desktop 4.34+ with host networking enabled + (Settings → Resources → Network). If it's unavailable in your version, drop + the flag and either publish ports explicitly (`-p HOST_PORT:CONTAINER_PORT`) + or, from inside the container, reach services on the host via + `host.docker.internal` instead of `localhost`. +- Once inside the container you land in a `bash` shell by default. `pwsh` is + also installed - see [powershell_usage.md](./powershell_usage.md) for using + PowerShell *inside* the container. + +## Troubleshooting + +- For any issues, check [this reference](../troubleshooting/TROUBLESHOOTING.md)