Shimpz
Installation guide

Install on Windows

WSL2 · x64

Shimpz runs inside Ubuntu on WSL2 and uses Docker Desktop for its containers and volumes.

  1. Install Ubuntu on WSL2

    Open PowerShell as Administrator:

    PowerShell · Administrator
    wsl --install -d Ubuntu

    Restart if asked, open Ubuntu from the Start menu, and create your Linux username and password.

  2. Require systemd inside WSL2

    In the Ubuntu terminal, enable systemd:

    Ubuntu · systemd
    printf '[boot]\nsystemd=true\n' | sudo tee /etc/wsl.conf >/dev/null

    Close Ubuntu, run wsl --shutdown in PowerShell, then reopen Ubuntu. shimpz install refuses a WSL2 distribution that does not run systemd as PID 1.

  3. Protect Docker data with BitLocker (recommended)

    Enable BitLocker on the Windows volume that contains Docker Desktop's disk image. If you move that disk image, protect its new volume too. BitLocker is an operating-system setting: Shimpz does not turn it on or verify it, and installation is not blocked when it is off.

  4. Connect Docker Desktop

    Install Docker Desktop for Windows. Enable Use the WSL 2 based engine, then enable Ubuntu under Settings → Resources → WSL Integration.

    Use a Docker Desktop release that provides Docker Engine 25.0 or newer, runc 1.2.8+, 1.3.3+, or 1.4.0+ (shown by docker version), and Docker Compose 2.20.2 or newer.

    Do not install a second Docker Engine inside Ubuntu.

  5. Check Docker inside Ubuntu

    Ubuntu · Docker check
    uname -m
    x86_64
    docker version
    docker compose version

  6. Install Shimpz inside Ubuntu

    Ubuntu · Shimpz install
    curl -fsSL https://install.shimpz.com | sh

  7. Confirm that Admin opens

    When shimpz install succeeds, open the exact address it prints in your normal Windows browser. The default is http://127.0.0.1:7777; a configured SHIMPZ_PORT changes it. Continue when you see the initial password-and-authenticator setup or sign-in screen.