diff --git a/deploy/az/vms/docker-machine.md b/deploy/az/vms/docker-machine.md new file mode 100644 index 000000000..71cbbd4a7 --- /dev/null +++ b/deploy/az/vms/docker-machine.md @@ -0,0 +1,48 @@ +# Create a VM using docker-machine + +Ensure you are logged in the desired subscription Refer to [this article](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli) for more details. + +1. Use `az account show` to find your subscription id. +2. Use `docker-machine create --driver azure --azure-subscription-id --azure-resource-group --azure-ssh-user ` + +After use `docker-machine create` you'll need to authenticate in Azure (even thought if you are logged using `az`, because this is not an Azure CLI 2.0 command). This command will fully create the VM with all the needed settings to run Docker. + +**Note** Refer to this article with all the [parameters that docker-machine accepts when creating Azure VMs](https://docs.docker.com/machine/drivers/azure/#options) for finding more parameters. + +## Connecting your local environment with docker host running on the VM + +Using docker-machine you control the remote VM from your local development environment (you don't need to use ssh to login to remote VM). + +Connecting your local environment to a remote host is using by setting some environment variables, but the easiest way is to use again the docker-machine command. Just type `docker-machine env machine_name` (where machine_name is the name you gave when you created the VM). That command **do not change anything**, so do'nt do really nothing, but **outputs the environment variables you have to set**. This is the output of the command (running on a windows workstation): + +``` +SET DOCKER_TLS_VERIFY=1 +SET DOCKER_HOST=tcp://104.42.236.237:2376 +SET DOCKER_CERT_PATH=C:\Users\etoma\.docker\machine\machines\ufohost +SET DOCKER_MACHINE_NAME=ufohost +SET COMPOSE_CONVERT_WINDOWS_PATHS=true +REM Run this command to configure your shell: +REM @FOR /f "tokens=*" %i IN ('docker-machine env ufohost') DO @%i +``` + +You have to set all these environment variables, or (as the command suggest) just copy and paste the last line in your terminal. + +Once you did this, your local development machine is connected to VM running Docker on Azure: all docker and docker-compose commands will run in the VM instead of your local Docker machine! + + + + + + + + + + + + + + + + + + diff --git a/deploy/az/vms/plain-vm.md b/deploy/az/vms/plain-vm.md new file mode 100644 index 000000000..4e06ed0d3 --- /dev/null +++ b/deploy/az/vms/plain-vm.md @@ -0,0 +1,77 @@ +# Deploy a VM to run the services + +Follow these instructions to deploy a Linux-based VM with the Docker Host installed, or a VM with Windows Server 2016 plus +windows containers and Docker Daemon. + +**Note**: Use this option, only if you want to provide an environment using images pulled from DockerHub (for example, to create a test environment). If you want to +be able to deploy images built by yourself (but not pushed to DockerHub) follow the [instructions about using docker-machine](./docker-machine.md). + +You can use this machine to install the microservices and having a "development" environment (useful to develop and test the client apps). + +Please note that this deployment is not a production deployment. In a production-based scenario, you should deploy all containers in ACS. + +## Create the VM + +Ensure you are logged in the desired subscription (use `az login` and `az account set` if needed. Refer to [this article](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli) for more details. + +Go to `linux-vm` or `win-vm` folder (based on if you want a Linux or Windows VM). Then: + +1. Edit the file `linuxvm.parameters.json` or `windowsvm.parameters.json` (based on what VM do you want to create) with your desired values +2. Run the [create-resources script](../readme.md) to deploy the desired template (`linux-vm/linuxvm.json` or `win-vm/windowsvm.json`). + +I. e. if you are in Windows and want to deploy a linux based VM, in a new resourcegroup located in westus, go to `deploy\az` folder and type: + +``` +create-resources.cmd vms\linux-vm\linuxvm newResourceGroup -c westus +``` + +**Note:** To avoid errors, ARM template used generates unique names for: + +1. VM used storage +2. Public DNS + +Those public names are based on the parameters set in the parameters file. + +### The parameters file (linuxvm.parameters.json or winsowsvm.parameters.json) + +Both files are identical and contains the minimum set of parameters needed by the ARM template to deploy the VM. ARM template accepts some other parameters (set with default values). Look the template for more info. + +The parameters defined are: + +1. `newStorageAccountName`: Name of the storage created for the VM. To ensure uniqueness a unique suffix will be added to this value. +2. `adminUsername`: Admin login +3. `adminPassword`: Admin password +4. `dnsNameForPublicIP`: DNS of the VM. To ensure uniqueness a unique suffix will be added to this value. +5. `VMName`: Name of the VM inside Azure + +## Finding the IP and DNS of the VM + +To find the IP and FQDN of the VM you can type `az vm list --resource-group --output table --show-details` (where resourcegroup is the +name of the resourcegroup where you created the VM). This command will generate output like: + +``` +Name ResourceGroup PowerState PublicIps Fqdns Location +---------- --------------- ------------ ------------- ------------------------------------------------ ---------- +MyDockerVM MyResourceGroup VM running xx.xx.xxx.xxx eshop-srvxxxxxxxxxxxxx.westus.cloudapp.azure.com westus +``` + +You can use this information to connect your new VM. + +## Deploy services in the VM + +We are providing public images of the services in DockerHub (https://hub.docker.com/u/eshop/). To use these images, just create a folder in the VM and copy +following files to it (those files are in the root of the repo): + +1. `docker-compose.nobuild.yml` +2. `docker-compose.prod.yml` + +**Note:** The `docker-compose.nobuild.yml` is just a version of the `docker-compose.yml` without the `build` section. Is neede due [docker-compose bug](https://github.com/docker/compose/issues/2945). + +Then log into the VM and run the command `docker-compose -f docker-compose.nobuild.yml -f docker-compose.prod.yml up --no-build -d` to start all the microservices. + + + + + + + diff --git a/deploy/az/vms/readme.md b/deploy/az/vms/readme.md index b91fb504c..25085f75c 100644 --- a/deploy/az/vms/readme.md +++ b/deploy/az/vms/readme.md @@ -1,68 +1,10 @@ -# Deploy a VM to run the services +## Create VM with Docker installed -Follow these instructions to deploy a Linux-based VM with the Docker Host installed, or a VM with Windows Server 2016 plus -windows containers and Docker Daemon. - -You can use this machine to install the microservices and having a "development" environment (useful to develop and test the client apps). - -Please note that this deployment is not a production deployment. In a production-based scenario, you should deploy all containers in ACS. - -## Create the VM - -Ensure you are logged in the desired subscription (use `az login` and `az account set` if needed. Refer to [this article](https://docs.microsoft.com/en-us/cli/azure/authenticate-azure-cli) for more details. - -Go to `linux-vm` or `win-vm` folder (based on if you want a Linux or Windows VM). Then: - -1. Edit the file `linuxvm.parameters.json` or `windowsvm.parameters.json` (based on what VM do you want to create) with your desired values -2. Run the [create-resources script](../readme.md) to deploy the desired template (`linux-vm/linuxvm.json` or `win-vm/windowsvm.json`). - -I. e. if you are in Windows and want to deploy a linux based VM, in a new resourcegroup located in westus, go to `deploy\az` folder and type: - -``` -create-resources.cmd vms\linux-vm\linuxvm newResourceGroup -c westus -``` - -**Note:** To avoid errors, ARM template used generates unique names for: - -1. VM used storage -2. Public DNS - -Those public names are based on the parameters set in the parameters file. - -### The parameters file (linuxvm.parameters.json or winsowsvm.parameters.json) - -Both files are identical and contains the minimum set of parameters needed by the ARM template to deploy the VM. ARM template accepts some other parameters (set with default values). Look the template for more info. - -The parameters defined are: - -1. `newStorageAccountName`: Name of the storage created for the VM. To ensure uniqueness a unique suffix will be added to this value. -2. `adminUsername`: Admin login -3. `adminPassword`: Admin password -4. `dnsNameForPublicIP`: DNS of the VM. To ensure uniqueness a unique suffix will be added to this value. -5. `VMName`: Name of the VM inside Azure - -## Finding the IP and DNS of the VM - -To find the IP and FQDN of the VM you can type `az vm list --resource-group --output table --show-details` (where resourcegroup is the -name of the resourcegroup where you created the VM). This command will generate output like: - -``` -Name ResourceGroup PowerState PublicIps Fqdns Location ----------- --------------- ------------ ------------- ------------------------------------------------ ---------- -MyDockerVM MyResourceGroup VM running xx.xx.xxx.xxx eshop-srvxxxxxxxxxxxxx.westus.cloudapp.azure.com westus -``` - -You can use this information to connect your new VM. - -## Deploy services in the VM - -We are providing public images of the services in DockerHub (https://hub.docker.com/u/eshop/). To use these images, just create a folder in the VM and copy -following files to it (those files are in the root of the repo): - -1. `docker-compose.yml` -2. `docker-compose.prod.yml` - -Then log into the VM and run the command `docker-compose -f docker-compose.yml -f docker-compose.prod.yml up --no-build -d` to start all the microservices. +There are two options for creating VM machines with Docker installed: +1. [Deploying a Linux VM to run single-server development environment using docker-machine (**Recommended for development environments**)](./docker-machine.md) +2. [Deploying a Linux VM or Windows Server 2016 to run a single-server development environment using ARM template (**Recommended for creating testing environments**)](./plain-vm.md) +If you want to create a VM for deploying images you build locally, then use the first option. +If you want to create a VM to run images deployed to DockerHub (to provide some test environment) then use the second option. \ No newline at end of file diff --git a/deploy/readme.md b/deploy/readme.md index 0a24fdaba..bf51a7bf2 100644 --- a/deploy/readme.md +++ b/deploy/readme.md @@ -10,7 +10,10 @@ Login into your azure subscription by typing `az login` (note that you maybe nee ## Deploying Virtual machines to host the services -1. [Deploying a Linux VM or Windows Server 2016 to run a single-development environment](az/vms/readme.md) +1. [Deploying a Linux VM to run single-server development environment using docker-machine (**Recommended for development environments**)](az/vms/docker-machine.md) +2. [Deploying a Linux VM or Windows Server 2016 to run a single-server development environment using ARM template (**Recommended for creating testing environments**)](az/vms/plain-vm.md) + +Using `docker-machine` is the recommended way to create a VM with docker installed. But it is limited to Linux based VMs. ## Deploying Azure resources used by the services