Преглед изворни кода

Include linux install dock & script, split README with BUILDING.md & INSTALL.md

Signed-off-by: Guillaume Tardif <[email protected]>
Guillaume Tardif пре 5 година
родитељ
комит
2bd3ce9eef
5 измењених фајлова са 461 додато и 134 уклоњено
  1. 136 0
      BUILDING.MD
  2. 105 0
      INSTALL.md
  3. 3 134
      README.md
  4. 14 0
      scripts/install/Dockerfile-testInstall
  5. 203 0
      scripts/install/install_linux.sh

+ 136 - 0
BUILDING.MD

@@ -0,0 +1,136 @@
+
+### Prerequisites
+
+* Windows:
+  * [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-windows)
+  * make
+* macOS:
+  * [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac)
+  * make
+* Linux:
+  * [Docker 19.03 or later](https://docs.docker.com/engine/install/)
+  * make
+
+### Building the CLI
+
+Once you have the prerequisites installed, you can build the CLI using:
+
+```console
+make
+```
+
+This will output a CLI for your host machine in `./bin`.
+
+You will then need to make sure that you have the existing Docker CLI in your
+`PATH` with the name `com.docker.cli`. A make target is provided to help with
+this:
+
+```console
+make moby-cli-link
+```
+
+This will create a symbolic link from the existing Docker CLI to
+`/usr/local/bin` with the name `com.docker.cli`.
+
+You can statically cross compile the CLI for Windows, macOS, and Linux using the
+`cross` target.
+
+### Building with specific backends
+
+You can specify which backends are build using the `BUILD_TAGS` variable.
+The available backends are:
+* `aci`: For ACI support (always built)
+* `ecs`: For ECS support (always built)
+* `example`: Testing backend (off by default)
+* `local`: Beginnings of a [moby](https://github.com/moby/moby) backend
+  (off by default)
+
+If you want the ACI, ECS and example backends, then you can build as follows:
+
+```console
+make BUILD_TAGS=example cli
+```
+
+### Updating the API code
+
+The API provided by the CLI is defined using protobuf. If you make changes to
+the `.proto` files in [`protos/`](./protos), you will need to regenerate the API
+code:
+
+```console
+make protos
+```
+
+### Unit tests
+
+To run all of the unit tests, run:
+
+```console
+make test
+```
+
+If you need to update a golden file simply do `go test ./... -test.update-golden`.
+
+### End to end tests
+
+#### Local tests
+
+To run the local end to end tests, run:
+
+```console
+make e2e-local
+```
+
+Note that this requires the CLI to be built and a local Docker Engine to be
+running.
+
+#### ACI tests
+
+To run the end to end ACI tests, you will first need to have an Azure account
+and have created a service principal. You can create a service principle using
+the Azure CLI after you have done a `docker login azure`:
+
+```console
+$ docker login azure
+$ az ad sp create-for-rbac --name 'MyTestServicePrincipal' --sdk-auth
+```
+
+You can then run the ACI tests using the `e2e-aci` target with the various
+`AZURE_` environment variables set:
+
+```console
+AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make e2e-aci
+```
+
+Running the ACI tests will override your local login and the service principal
+credentials use a token that cannot be refreshed automatically.
+
+*Note:* You will need to rerun `docker login azure` if you would like to use the
+CLI after running the ACI tests.
+
+You can also run a single ACI test by specifying the test name with the
+`E2E_TEST` variable:
+```console
+AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make E2E_TEST=TestContainerRun e2e-aci
+```
+
+#### ECS tests
+
+To run the end to end ECS tests, you will need to have an AWS account and have
+credentials for it in the `~/.aws/credentials` file.
+
+You can then use the `e2e-ecs` target:
+
+```console
+TEST_AWS_PROFILE=myProfile TEST_AWS_REGION=eu-west-3 make e2e-ecs
+```
+
+## Releases
+
+To create a new release:
+* Check that the CI is green on the main branch for commit you want to release
+* Create a new tag of the form vx.y.z, following existing tags, and push the tag
+
+Pushing the tag will automatically create a new release and make binaries for
+Windows, macOS, and Linux available for download on the
+[releases page](https://github.com/docker/compose-cli/releases).

+ 105 - 0
INSTALL.md

@@ -0,0 +1,105 @@
+# Mac and Windows installation
+
+The ACI integration is built into Docker Desktop **Edge**.
+You can download it from these links:
+- [macOS](https://hub.docker.com/editions/community/docker-ce-desktop-mac)
+- [Windows](https://hub.docker.com/editions/community/docker-ce-desktop-windows)
+
+# Ubuntu Linux installation
+
+The Linux installation script and manual install instructions have been tested
+with a fresh install of Ubuntu 20.04.
+
+## Prerequisites
+
+* [Docker 19.03 or later](https://docs.docker.com/engine/install/)
+
+## Install script
+
+You can install the new CLI using the install script:
+
+```console
+curl -L https://raw.githubusercontent.com/docker/compose-cli/main/scripts/install_linux.sh | sh
+```
+
+## Manual install
+
+You can download the Docker ACI Integration CLI from [latest release](https://github.com/docker/compose-cli/releases/latest).
+
+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
+```
+
+# Testing the install script
+
+To test the install script, from a machine with docker:
+
+```console
+docker build -t testclilinux -f scripts/Dockerfile-testInstall scripts
+```

+ 3 - 134
README.md

@@ -17,7 +17,7 @@ To get started, all you need is:
 * macOS: The Edge release of
   [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac)
 * Linux:
-  TODO <!-- Move instructions from https://github.com/docker/aci-integration-beta to this repo-->
+  [Install script](INSTALL.md)
 
 :warning: *This CLI is currently in beta please create*
 *[issues](https://github.com/docker/compose-cli/issues) to leave feedback*
@@ -29,138 +29,7 @@ To get started, all you need is:
 
 ## Developing
 
-### Prerequisites
+See [Instructions](BUILDING.MD) on building the cli, running tests locally and against Azure Container Instances (ACI) or Amazon ECS, and releasing it.
+Also Check [contribution guidelines](CONTRIBUTING.md) on conventions used in this project. 
 
-* Windows:
-  * [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-windows)
-  * make
-* macOS:
-  * [Docker Desktop](https://hub.docker.com/editions/community/docker-ce-desktop-mac)
-  * make
-* Linux:
-  * [Docker 19.03 or later](https://docs.docker.com/engine/install/)
-  * make
-
-### Building the CLI
-
-Once you have the prerequisites installed, you can build the CLI using:
-
-```console
-make
-```
-
-This will output a CLI for your host machine in `./bin`.
-
-You will then need to make sure that you have the existing Docker CLI in your
-`PATH` with the name `com.docker.cli`. A make target is provided to help with
-this:
-
-```console
-make moby-cli-link
-```
-
-This will create a symbolic link from the existing Docker CLI to
-`/usr/local/bin` with the name `com.docker.cli`.
-
-You can statically cross compile the CLI for Windows, macOS, and Linux using the
-`cross` target.
-
-### Building with specific backends
-
-You can specify which backends are build using the `BUILD_TAGS` variable.
-The available backends are:
-* `aci`: For ACI support (always built)
-* `ecs`: For ECS support (on by default)
-* `example`: Testing backend (off by default)
-* `local`: Beginnings of a [moby](https://github.com/moby/moby) backend
-  (off by default)
-
-If you want the ACI, ECS and example backends, then you can build as follows:
-
-```console
-make BUILD_TAGS=example cli
-```
-
-### Updating the API code
-
-The API provided by the CLI is defined using protobuf. If you make changes to
-the `.proto` files in [`protos/`](./protos), you will need to regenerate the API
-code:
-
-```console
-make protos
-```
-
-### Unit tests
-
-To run all of the unit tests, run:
-
-```console
-make test
-```
-
-If you need to update a golden file simply do `go test ./... -test.update-golden`.
-
-### End to end tests
-
-#### Local tests
-
-To run the local end to end tests, run:
-
-```console
-make e2e-local
-```
-
-Note that this requires the CLI to be built and a local Docker Engine to be
-running.
-
-#### ACI tests
-
-To run the end to end ACI tests, you will first need to have an Azure account
-and have created a service principal. You can create a service principle using
-the Azure CLI after you have done a `docker login azure`:
-
-```console
-$ docker login azure
-$ az ad sp create-for-rbac --name 'MyTestServicePrincipal' --sdk-auth
-```
-
-You can then run the ACI tests using the `e2e-aci` target with the various
-`AZURE_` environment variables set:
-
-```console
-AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make e2e-aci
-```
-
-Running the ACI tests will override your local login and the service principal
-credentials use a token that cannot be refreshed automatically.
-
-*Note:* You will need to rerun `docker login azure` if you would like to use the
-CLI after running the ACI tests.
-
-You can also run a single ACI test by specifying the test name with the
-`E2E_TEST` variable:
-```console
-AZURE_TENANT_ID="xxx" AZURE_CLIENT_ID="yyy" AZURE_CLIENT_SECRET="yyy" make E2E_TEST=TestContainerRun e2e-aci
-```
-
-#### ECS tests
-
-To run the end to end ECS tests, you will need to have an AWS account and have
-credentials for it in the `~/.aws/credentials` file.
-
-You can then use the `e2e-ecs` target:
-
-```console
-TEST_AWS_PROFILE=myProfile TEST_AWS_REGION=eu-west-3 make e2e-ecs
-```
-
-## Releases
-
-To create a new release:
-* Check that the CI is green on the main branch for commit you want to release
-* Create a new tag of the form vx.y.z, following existing tags, and push the tag
 
-Pushing the tag will automatically create a new release and make binaries for
-Windows, macOS, and Linux available for download on the
-[releases page](https://github.com/docker/compose-cli/releases).

+ 14 - 0
scripts/install/Dockerfile-testInstall

@@ -0,0 +1,14 @@
+FROM ubuntu:latest
+
+RUN apt-get update
+RUN apt-get -y install curl grep
+RUN curl https://get.docker.com | sh
+
+COPY install_linux.sh /scripts/install_linux.sh
+RUN chmod +x /scripts/install_linux.sh
+RUN /scripts/install_linux.sh
+RUN docker version | grep Azure
+
+# check we can update
+RUN /scripts/install_linux.sh
+RUN docker version | grep Azure

+ 203 - 0
scripts/install/install_linux.sh

@@ -0,0 +1,203 @@
+#!/bin/sh
+
+#   Copyright 2020 Docker, Inc.
+
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+
+#       http://www.apache.org/licenses/LICENSE-2.0
+
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+
+# Script to install the Docker ACI integration CLI on Ubuntu (Beta).
+
+set -eu
+
+RELEASE_URL=https://api.github.com/repos/docker/compose-cli/releases/latest
+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
+
+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
+
+DOWNLOAD_URL=$(curl -s ${RELEASE_URL} | grep "browser_download_url.*docker-linux-amd64" | cut -d : -f 2,3)
+
+# Check if the ACI CLI is already installed
+if [ $(is_new_cli "docker") -eq 1 ]; then
+	if [ $(is_new_cli "/usr/local/bin/docker") -eq 1 ]; then
+		echo "You already have the Docker ACI Integration CLI installed, overriding with latest version"
+		download_dir=$($sh_c 'mktemp -d')
+		$sh_c "${download_cmd} ${download_dir}/docker-aci ${DOWNLOAD_URL}"
+		$sudo_sh_c "install -m 775 ${download_dir}/docker-aci /usr/local/bin/docker"
+		exit 0
+	fi
+	echo "You already have the Docker ACI Integration CLI installed, in a different location."
+	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
+
+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"
+
+# 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 "$DRY_RUN" ]; then
+	exit 0
+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