stevedore

stevedore copied to clipboard

= Stevedore Marat Radchenko :slug: slonopotamus/stevedore :uri-project: https://github.com/{slug} :uri-ci: {uri-project}/actions?query=branch%3Amain

image:{uri-project}/workflows/CI/badge.svg?branch=main[Build Status,link={uri-ci}] image:https://img.shields.io/github/release/{slug}.svg[Download,link={uri-project}/releases/latest] image:https://img.shields.io/chocolatey/v/stevedore[Chocolatey package,link=https://community.chocolatey.org/packages/stevedore]

== Overview

This project aims to provide a frictionless Docker experience on Windows.

Stevedore can be used as a replacement for Docker Desktop, DockerMsftProvider or Mirantis Container Runtime.

Both Linux and Windows Containers are supported.

If you only need Linux containers, you might want to consider these projects:

• https://container-desktop.io/[Container Desktop] (Windows-only)
• https://rancherdesktop.io/[Rancher Desktop] (Windows + Linux + Mac)
• https://github.com/abiosoft/colima[Colima] (Mac-only)

== Supported OSes

• Windows 10, 11
• Windows Server 2016, 2019, 2022 (note that Linux containers are only supported via LCOW due to lack of WSL2)

== Installation

=== Manual

. Download {uri-project}/releases/latest[MSI installer] . Double-click on it . Next-next-next . Reboot your computer. This is needed to finish installation of Windows Containers feature and to add your user to docker-users group so user can access Docker service. . Proceed to <>

=== Chocolatey

Stevedore is available via https://community.chocolatey.org/packages/stevedore[Chocolatey] package manager. If you already have Chocolatey installed, you can just run the following command from elevated console:

[source,powershell]

choco install stevedore

Then reboot and proceed to <>

=== WinGet

[source,powershell]

winget install stevedore

Then reboot and proceed to <>

[[post-install]] === Post-installation steps

NOTE:: Skip this step if you didn't install Linux containers support

After installing Stevedore and rebooting, you need to install https://aka.ms/wsl2kernel[Linux kernel update package for WSL2].

Finally, run Stevedore app using desktop shortcut or start menu.

If everything was done properly, you'll be able to use docker command to work with Linux containers.

You may try docker run --rm -i hello-world from a command line to confirm that everything was set up properly.

=== Advanced: Command-line install options

Stevedore installer supports several command-line options that may be handy to configure unattended installations.

Basic usage: msiexec /i c:\path\to\stevedore.msi.

For quiet (non-interactive) installation add /quiet option.

If you only want to install specific Stevedore features, use ADDLOCAL=Feature1,Feature2,Feature3 syntax.

.List of available MSI features for ADDLOCAL

• FeatureWindowsContainers installs Windows Containers support, including Stevedore service. It allows running containers with https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container#process-isolation[process isolation].
• FeatureHyperV installs Hyper-V support. It allows running containers with https://docs.microsoft.com/en-us/virtualization/windowscontainers/manage-containers/hyperv-container#hyper-v-isolation[Hyper-V isolation].
• FeatureLinuxContainers installs Linux Containers WSL2 support.

You can also pass custom installation properties to Stevedore installer using PROPERTY=value syntax.

.List of available MSI properties

• INSTALLDIR=%ProgramFiles%\Stevedore specifies directory where Stevedore executable files will be installed
• SERVICENAME=stevedore specifies Windows service name

When installing Stevedore via Chocolatey, use this syntax: choco install stevedore --params="ADDLOCAL=Feature1,Feature2,Feature3 PROPERTY=value /quiet"

== Bundled components

• Docker Engine 20.10.17
• Docker App 0.9.1-beta3
• Buildx 0.8.2
• Docker Compose 2.6.1
• Docker Scan 0.17.0
• kubectl 1.24.3
• docker-credential-wincred 0.6.4

== Usage

After installation and reboot, docker command should be available on PATH and ready to use.

You may try docker run --rm -i hello-world from a command line to confirm that everything was set up properly.

In order to communicate with Docker engine, users needs to be in docker-users group. Upon installation, Stevedore automatically adds installing user to docker-users. If you need other users to also access Docker engine, you will need to add them manually. You can use https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.localaccounts/add-localgroupmember[Add-LocalGroupMember] PowerShell commandlet for that.

[[linux-containers]] === Linux Containers support

.Current limitations:

• WSL2 image, that Stevedore uses to run Docker, doesn't update when you update Stevedore. https://github.com/slonopotamus/stevedore/issues/25[#25]
• It is impossible to update WSL2 image without wiping all images/containers. https://github.com/slonopotamus/stevedore/issues/24[#24]

See it in action:

video::https://user-images.githubusercontent.com/92637/153852434-f4518f98-fde2-4902-81f0-655df9c554f7.mp4[]

=== Docker Compose

Stevedore installs two flavors of Docker Compose.

You can use Docker Compose V2 via docker compose command.

You can also use Docker Compose V1 compatibility mode via docker-compose command.

=== Managing Stevedore tray app auto-startup

IMPORTANT:: You need to run Stevedore tray app to use Linux containers.

. Open Windows Task Manager . Open Startup tab . Right-click on Stevedore entry . Choose Enable or Disable options to control Stevedore tray app auto-startup

=== Configuration and data files

Stevedore stores configuration and runtime data files for Windows containers under %ProgramData%\Docker directory.

Linux-specific WSL data is stored in stevedore WSL distribution located under %LOCALAPPDATA%\Stevedore directory.

== Building from source

. https://www.rust-lang.org/tools/install[Install Rust] . Install https://wixtoolset.org/releases/https://wixtoolset.org/releases/[WiX Toolset] either manually or by running choco install wixtoolset if you have https://chocolatey.org/[Chocolatey] . Install Visual Studio 2019 or 2022. Enable "Desktop development with {cpp}" workload. Also, enable "{cpp} 2019 Redistributable MSMs" "{cpp} 2022 Redistributable MSMs" in individual components. . Clone Stevedore Git repository . Run cargo install cargo-wix to install https://github.com/volks73/cargo-wix[cargo-wix] . Run cargo wix --nocapture in repository root. Ready-to-use MSI package will be built in <repo>/target/wix directory.