From 6e6ed0648fbbfa8926f218fd71d70e5803bd0d48 Mon Sep 17 00:00:00 2001 From: Christopher Crone Date: Tue, 9 Jun 2020 16:06:05 +0200 Subject: [PATCH] docs: Add Linux install instructions Signed-off-by: Christopher Crone --- docs/install/install.sh | 182 ++++++++++++++++++++++++++++++++++++++++ docs/install/linux.md | 97 +++++++++++++++++++++ 2 files changed, 279 insertions(+) create mode 100755 docs/install/install.sh create mode 100644 docs/install/linux.md diff --git a/docs/install/install.sh b/docs/install/install.sh new file mode 100755 index 000000000..62fd74279 --- /dev/null +++ b/docs/install/install.sh @@ -0,0 +1,182 @@ +#!/bin/sh + +# Script to install the Docker ACI integration CLI on Ubuntu (Beta). + +set -eu + +CLI_VERSION=${CLI_VERSION:-0.1.4} +DOWNLOAD_URL="${DOWNLOAD_URL:-https://github.com/docker/aci-integration-beta/releases/download/v${CLI_VERSION}/docker-linux-amd64}" +LINK_NAME="${LINK_NAME:-com.docker.cli}" +DRY_RUN="${DRY_RUN:-}" + +desktop_install_url="https://www.docker.com/products/docker-desktop" +engine_install_url="https://docs.docker.com/get-docker/" + +link_path="/usr/local/bin/${LINK_NAME}" +existing_cli_path="/usr/bin/docker" + +manual_install() { + echo "Please follow the manual install instructions" +} + +is_new_cli() { + azure_version_str="$($1 version 2>/dev/null | grep 'Azure' || true)" + if [ -n "$azure_version_str" ]; then + echo 1 + else + echo 0 + fi +} + +echo "Running checks..." + +# Check OS +if [ "$(command -v uname)" ]; then + case "$(uname -s)" in + "Linux") + # Check for Ubuntu/Debian based distro + if ! [ -f "/etc/lsb-release" ]; then + echo "Warning: This script has been tested on Ubuntu and may not work on other distributions" + fi + # Pass + ;; + "Darwin") + echo "Error: Script not needed on macOS, please install Docker Desktop Edge: $desktop_install_url" + exit 1 + ;; + "*") + echo "Error: Unsupported OS, please follow manual instructions" + exit 1 + ;; + esac +else + # Assume Windows + echo "Error: Script not needed on Windows, please install Docker Desktop Edge: $desktop_install_url" + exit 1 +fi + +user="$(id -un 2>/dev/null || true)" +sh_c='sh -c' +sudo_sh_c='sh -c' +if [ "$user" != 'root' ]; then + if [ "$(command -v sudo)" ]; then + sudo_sh_c='sudo -E sh -c' + elif [ "$(command -v su)" ]; then + sudo_sh_c='su -c' + else + echo "Error: This installer needs the ability to run commands as root." + exit 1 + fi +fi + +if [ -n "$DRY_RUN" ]; then + sh_c="echo $sh_c" + sudo_sh_c="echo $sudo_sh_c" +fi + +# Check if Docker Engine is installed +if ! [ "$(command -v docker)" ]; then + echo "Error: Docker Engine not found" + echo "You need to install Docker first: $engine_install_url" + exit 1 +fi + +# Check if the ACI CLI is already installed +if [ $(is_new_cli "docker") -eq 1 ]; then + echo "You already have the Docker ACI Integration CLI installed" + exit 1 +fi + +# Check if this script has already been run +if [ -f "${link_path}" ]; then + echo "Error: This script appears to have been run as ${link_path} exists" + echo "Please uninstall and rerun this script or follow the manual instructions" + exit 1 +fi + +# Check current Docker CLI is installed to /usr/bin/ +if ! [ -f "${existing_cli_path}" ]; then + echo "Error: This script only works if the Docker CLI is installed to /usr/bin/" + manual_install + exit 1 +fi + +# Check that PATH contains /usr/bin and /usr/local/bin and that the latter is +# higher priority +path_directories=$(echo "${PATH}" | tr ":" "\n") +usr_bin_pos=-1 +usr_local_bin_pos=-1 +count=0 +for d in ${path_directories}; do + if [ "${d}" = '/usr/bin' ]; then + usr_bin_pos=$count + fi + if [ "${d}" = '/usr/local/bin' ]; then + usr_local_bin_pos=$count + fi + count=$((count + 1)) +done +if [ $usr_bin_pos -eq -1 ]; then + echo "Error: /usr/bin not found in PATH" + manual_install + exit 1 +elif [ $usr_local_bin_pos -eq -1 ]; then + echo "Error: /usr/local/bin not found in PATH" + manual_install + exit 1 +elif ! [ $usr_local_bin_pos -lt $usr_bin_pos ]; then + echo "Error: /usr/local/bin is not ordered higher than /usr/bin in your PATH" + manual_install + exit 1 +fi + +download_cmd='curl -fsSLo' +# Check that system has curl installed +if ! [ "$(command -v curl)" ]; then + echo "Error: curl not found" + echo "Please install curl" + exit 1 +fi + +echo "Checks passed!" +echo "Downloading CLI..." + +# Download CLI to temporary directory +download_dir=$($sh_c 'mktemp -d') +$sh_c "${download_cmd} ${download_dir}/docker-aci ${DOWNLOAD_URL}" + +echo "Downloaded CLI!" +echo "Installing CLI..." + +# Link existing Docker CLI +$sudo_sh_c "ln -s ${existing_cli_path} ${link_path}" + +# Install downloaded CLI +$sudo_sh_c "install -m 775 ${download_dir}/docker-aci /usr/local/bin/docker" + +# Exit on dry run +if [ -n "$DRY_RUN" ]; then + exit 0 +fi + +# Clear cache +cleared_cache=1 +if [ "$(command hash)" ]; then + $sh_c "hash -r" +elif [ "$(command rehash)" ]; then + $sh_c "rehash" +else + cleared_cache= + echo "Warning: Unable to clear command cache" +fi + +if [ -n "$cleared_cache" ]; then + # Check ACI CLI is working + if [ $(is_new_cli "docker") -eq 0 ]; then + echo "Error: Docker ACI Integration CLI installation error" + exit 1 + fi + echo "Done!" +else + echo "Please log out and in again to use the Docker ACI integration CLI" +fi diff --git a/docs/install/linux.md b/docs/install/linux.md new file mode 100644 index 000000000..eb89d69b2 --- /dev/null +++ b/docs/install/linux.md @@ -0,0 +1,97 @@ +# Installing the Docker ACI Integration CLI on Linux (Beta) + +This CLI adds support for running and managing containers on Azure Container +Instances (ACI). + +> :warning: **This CLI is in beta**: The installation process, commands, and +> flags will change in future releases. + +## Prerequisites + +* [Docker 19.03 or later](https://docs.docker.com/get-docker/) + +## Install script + +You can install the new CLI using the install script: + +```console +curl -L https://github.com/docker/aci-integration-beta/releases/download/v0.1.4/install.sh | sh +``` + +## Manual install + +You can download the Docker ACI Integration CLI using the following command: + +```console +curl -Lo docker-aci https://github.com/docker/aci-integration-beta/releases/download/v0.1.4/docker-linux-amd64 +``` + +You will then need to make it executable: + +```console +chmod +x docker-aci +``` + +To enable using the local Docker Engine and to use existing Docker contexts, you +will need to have the existing Docker CLI as `com.docker.cli` somewhere in your +`PATH`. You can do this by creating a symbolic link from the existing Docker +CLI. + +```console +ln -s /path/to/existing/docker /directory/in/PATH/com.docker.cli +``` + +> **Note**: The `PATH` environment variable is a colon separated list of +> directories with priority from left to right. You can view it using +> `echo $PATH`. You can find the path to the existing Docker CLI using +> `which docker`. You may need root permissions to make this link. + +On a fresh install of Ubuntu 20.04 with Docker Engine +[already installed](https://docs.docker.com/engine/install/ubuntu/): + +```console +$ echo $PATH +/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin +$ which docker +/usr/bin/docker +$ sudo ln -s /usr/bin/docker /usr/local/bin/com.docker.cli +``` + +You can verify that this is working by checking that the new CLI works with the +default context: + +```console +$ ./docker-aci --context default ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +$ echo $? +0 +``` + +To make this CLI with ACI integration your default Docker CLI, you must move it +to a directory in your `PATH` with higher priority than the existing Docker CLI. + +Again on a fresh Ubuntu 20.04: + +```console +$ which docker +/usr/bin/docker +$ echo $PATH +/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin +$ sudo mv docker-aci /usr/local/bin/docker +$ which docker +/usr/local/bin/docker +$ docker version +... + Azure integration 0.1.4 +... +``` + +## Uninstall + +To remove this CLI, you need to remove the binary you downloaded and +`com.docker.cli` from your `PATH`. If you installed using the script, this can +be done as follows: + +```console +sudo rm /usr/local/bin/docker /usr/local/bin/com.docker.cli +```