From 2bd3ce9eefbdb5a6b5bf94ecad549c78c75d4dd3 Mon Sep 17 00:00:00 2001 From: Guillaume Tardif Date: Tue, 25 Aug 2020 12:31:48 +0200 Subject: [PATCH] Include linux install dock & script, split README with BUILDING.md & INSTALL.md Signed-off-by: Guillaume Tardif --- BUILDING.MD | 136 +++++++++++++++++ INSTALL.md | 105 +++++++++++++ README.md | 137 +---------------- scripts/install/Dockerfile-testInstall | 14 ++ scripts/install/install_linux.sh | 203 +++++++++++++++++++++++++ 5 files changed, 461 insertions(+), 134 deletions(-) create mode 100644 BUILDING.MD create mode 100644 INSTALL.md create mode 100644 scripts/install/Dockerfile-testInstall create mode 100644 scripts/install/install_linux.sh diff --git a/BUILDING.MD b/BUILDING.MD new file mode 100644 index 00000000..253e6ada --- /dev/null +++ b/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). diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..370df963 --- /dev/null +++ b/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 +``` \ No newline at end of file diff --git a/README.md b/README.md index bef10995..fd4f1d33 100644 --- a/README.md +++ b/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 + [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). diff --git a/scripts/install/Dockerfile-testInstall b/scripts/install/Dockerfile-testInstall new file mode 100644 index 00000000..5dd7554a --- /dev/null +++ b/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 \ No newline at end of file diff --git a/scripts/install/install_linux.sh b/scripts/install/install_linux.sh new file mode 100644 index 00000000..8b00c16b --- /dev/null +++ b/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