diff --git a/draft/tutorial/deploy-mongodb-to-centos-on-windows-azure.txt b/draft/tutorial/deploy-mongodb-to-centos-on-windows-azure.txt new file mode 100644 index 00000000000..b60f28cd30c --- /dev/null +++ b/draft/tutorial/deploy-mongodb-to-centos-on-windows-azure.txt @@ -0,0 +1,501 @@ +=========================================================== +Deploy a MongoDB Replica Set to CentOS VMs on Windows Azure +=========================================================== + +.. default-domain:: mongodb + +In this tutorial, you will learn to deploy a MongoDB replica set to +CentOS VMs on Windows Azure and access it from outside Azure. The +following are the tasks to achieve this: + + #. Sign up for the feature on the Azure portal + #. Set up affinity group + #. Create and set up the virtual machines + #. Install and run MongoDB + #. Configure the replica set + +Signing up +========== + +Sign up for ``Virtual Machines and Virtual Networks`` preview feature +from the new Azure portal* In the ``Preview`` portal, go to +Account->Preview Features. + +.. image:: img/image06.png + +Sign up for the “Virtual Machines and Virtual Networks” + +.. image:: img/image07.png + +.. TODO make this a subscript + +.. note:: + + “*” – The VM Role beta program from the old Azure portal (shown + below) is not the same as the preview feature above + + .. image:: img/image08.png + +Set up affinity group +===================== + +The affinity group needs to be set up from the old portal. + +#. If in the new Azure Management preview portal, click ‘Preview’ at + the top of the screen and then ‘Take me to the previous portal’ to + switch to the old portal + + .. image:: img/image10.png + +#. Once in the old portal, click ‘Hosted Services, Storage Accounts + & CDN’ + +#. Select ‘Affinity Groups’ and then ‘New Affinity Group’ + +#. In the “Create a New Affinity Group” dialog, enter an affinity + group name such as “mongoaffinitygroup” and choose a location + + - Choose one of the newer Azure data centers such as “West US”, + “East US” or “West Europe” + + .. image:: img/image11.png + +Create and set up the virtual machines +====================================== + +To create a 3-node MongoDB replica set you will be creating 3 VM +instances. For this step, log in to the new preview portal, or from +the old portal, click ``Visit the Previous Portal`` at the bottom of the +page + +Create instances +---------------- + +Instance 1 +~~~~~~~~~~ + +#. In the portal, click New->Virtual Machine->From Gallery + + .. image:: img/image01.png + +#. On the VM OS Selection page, choose ‘OpenLogic CentOS 6.2’ and + click the next arrow to continue + + .. image:: img/image00.png + +#. On the VM Configuration page, specify values for the parameters + + - Virtual Machine Name - ``mongodbrs1`` + - New User Name – ``mongouser``. This user will be added to the + ``sudoers`` list file + - New Password box – type a strong password that confirms to the + Azure specifications + - Retype the password to confirm + - Size – Choose appropriate size from drop down list. For anything + but small test instances, choose a size larger than Medium + - Leave ``Upload SSH key for Authentication`` unchecked + + Click the next arrow to continue + + .. image:: img/image03.png + +#. On the VM Mode page, specify values for the required parameters + + - Select ‘Standalone Virtual Machine’ + - DNS – a valid DNS prefix e.g. "mongodbrs" + - Storage Account box – choose ‘Use Automatically Generated Storage Account’ + - In the ‘Region/Affinity Group/Virtual Network’ box, select the + affinity group created previously “mongoaffinitygroup” + + Click next arrow to continue + + .. image:: img/image02.png + +#. On the VM Options page select ``None for Availability Set`` + + .. image:: img/image04.png + +#. Click the check mark to create the VM instance + +Instance 2 +~~~~~~~~~~ + +A similar process to creating instance 1. + +#. In the portal, click New->Virtual Machine->From Gallery +#. On the VM OS Selection page, choose ``OpenLogic CentOS 6.2`` and then the next arrow to continue +#. On the VM Configuration page, specify values for the parameters + + - Virtual Machine Name – ``mongodbrs2`` + - New User Name – ``mongouser``. This user will be added to the + Sudoers list file. For ease of use specify the same user name + as for instance 1 + - New Password box – type a strong password that confirms to the Azure specifications + - Retype the password to confirm + - Size – Choose the same instance size as instance 1 + - Leave ``Upload SSH key for Authentication`` unchecked + + Click the next arrow to continue + +#. On the VM Mode page, specify values for the required parameters + + - Select ``Connect to Existing Virtual Machine`` + - In the dropdown choose instance 1 ``mongodbrs1`` + - Storage Account box – choose ``Use Automatically Generated Storage Account`` + - The ``Region/Affinity Group/Virtual Network`` box should be automatically set to ``mongoaffinitygroup`` + + Click the next arrow to continue + + .. image:: img/image12.png + +#. On the VM Options page select ‘None for Availability Set’ + +#. Click the check mark to create the VM instance + +Instance 3 +~~~~~~~~~~ + +A similar process for creating instance 2. Choose ``mongodbrs3`` to be the Virtual Machine Name in step 3. + +Configure endpoints +------------------- + +Once the virtual machines are connected you need to configure the endpoints to: + +- Allow remote connection +- Allow mongo traffic + +Instance 1 +~~~~~~~~~~ + +#. In the management portal, click virtual machines and click the name of instance 1, ``mongodbrs1`` +#. Now click on endpoints +#. The ssh endpoint should be automatically created. For this endpoint ensure the following are set + + - Protocol – tcp + - Public Port – 22 + - Private Port – 22 + - Load Balanced – No + +#. Create a new endpoint for MongoDB by clicking on ``Add Endpoint`` at the bottom of the screen +#. Ensure ``Add endpoint`` is selected and click the right arrow to go to the next screen + + .. image:: img/image13.png + +#. Specify the endpoint details as below: + + - Name : MongoDB-Port + - Protocol : TCP + - Public Port : 27018 + - Private Port : 27018 + + Click on check mark to create endpoint + + .. image:: img/image14.png + +The instance now should have 2 endpoints, 1 for SSH and 1 for MongoDB + +.. image:: img/image15.png + +Instance 2 +~~~~~~~~~~ + +We need to configure the endpoints for instance 2 similar to instance 1: + +#. In the management portal, click ``virtual machines`` and click the name of instance 2 +#. Now click on ``endpoints`` +#. The ssh endpoint should be automatically created. Ensure that: + + - Name – SSH + - Protocol – TCP + - Private Port – 22 + - Load Balanced – No + +#. Now click on Edit Endpoint at the bottom of the screen and set + ``Public Port`` to 23. Click on the ``check mark`` to update +#. Create a new endpoint for MongoDB by clicking on ``Add Endpoint`` + at the bottom of the screen +#. Ensure ``Add Endpoint`` is selected and click the right arrow to go + to the next screen +#. Specify the endpoint details as below: + + - Name: MongoDB-Port + - Protocol: TCP + - Public Port: 27019 + - Private Port: 27019 + + Click on check mark to create endpoint + +The instance now should have 2 endpoints, 1 for SSH and 1 for MongoDB + +.. image:: img/image18.png + +Instance 3 +~~~~~~~~~~ + +Create endpoints for instance 3 similar to instance 2 with the following changes: + +#. In step 4, set public port to 24 +#. In step 7, set public and private ports to be 27020 + +The instance now should have 2 endpoints, 1 for SSH and 1 for MongoDB + +.. image:: img/image19.png + +Update OS +~~~~~~~~~ + +Use this optional step to update the operating system on each of your +VM instances. Once the machine endpoints have been configured above, +you need to log into the machines to update them. More information on +this can be found at `How to Log on to a Virtual Machine Running Linux +`_ +Use the username and password you used when creating the virtual +machine instances. Once you are connected to the machine, update the +operating system by running: + +.. code-block:: sh + + sudo yum update + +and following the prompts. This could take some time. + +.. note:: + + When connecting to instances 2 and 3, remember to use ports 23 and + 24 and not the default ssh port of 22. + +.. image:: img/image20.png + +Set up disks +~~~~~~~~~~~~ + +Once the instances are updated, you can then attach a data disk to +each of the instances. The data disks will be storing the actual +mongodb data as part of –dbpath. More information on Azure data disks +can be found at `Data Disk Concepts +`_. +To set up the data disk follow the steps outlined below for each of +the instances you created: + + #. Attach an empty disk to the instance as described in How to: + `Attach an empty + disk `_ + + .. note:: + + Create a data disk of at least 10 GB + + #. Now initialize the data disk by following the steps described at + `How to: Initialize a new data disk in Linux + `_ + + .. note:: + + Ensure you use ext4 for the file system and not ext3 + + #. Also once mounted, create a mongodb data directory by: + + #. Log on onto the instance + #. Run the following code to make the mongouser the owner of the data directory + + .. code-block:: sh + + sudo chown `id -u` /mnt/datadrive/ + + #. Run the following command: + + .. code-block:: sh + + mkdir -p /mnt/datadrive/data + +Install and run MongoDB +======================= + +As part of this step, you will be using the official 10gen supplied +packages to install, configure and run MongoDB as a service using +YUM. You want to install as a service since this would ensure that +mongod is started on machine restart also. More information can be +found at `Install MongoDB on RedHat Enterprise, CentOS, or Fedora +Linux +`_ +doc page. + +Install MongoDB +--------------- + +Repeat the following steps on each instance. + #. Log onto the instance + #. Create a ``/etc/yum.repos.d/10gen.repo`` file to hold information + about your repository using your favorite editor as sudo. Place + the following configuration in ``/etc/yum.repos.d/10gen.repo`` file: + + .. code-block:: sh + + [10gen] + name=10gen Repository + baseurl=http://downloads-distro.mongodb.org/repo/redhat/os/x86_64 + gpgcheck=0 + enabled=1 + + #. After saving the new .repo file, issue the following command to + update the local package database: sudo yum update + #. Issue the following command (as root or with sudo) to install + the latest stable version of MongoDB and the associated tools: + + .. code-block:: sh + + sudo yum install mongo-10gen mongo-10gen-server + + .. image:: img/image21.png + + #. When this command completes, you have successfully installed MongoDB. + + .. image:: img/image16.png + +Configure MongoDB +----------------- + +The packages installed in the previous step configure MongoDB using +the /etc/mongod.conf file in conjunction with the control script. You +can find the init script at /etc/rc.d/init.d/mongod. As part of this +step you will edit the mongod.conf file to set the appropriate +parameters. If the parameters are commented, make sure to uncomment +them. + +Instance 1 +~~~~~~~~~~ + + #. Connect to the instance using ssh or PuTTY + #. As sudo, edit /etc/mongod.conf to set the following parameters: + + .. code-block:: sh + + port = 27018 + dbpath = /mnt/datadrive/data + logpath = /mnt/datadrive/mongod.log + replSet = mongors + + #. Save the config file + +Instance 2 +~~~~~~~~~~ + + #. Connect to the instance using ssh or PuTTY + #. As sudo, edit /etc/mongod.conf to set the following parameter: + + .. code-block:: sh + + port = 27019 + dbpath = /mnt/datadrive/data + logpath = /mnt/datadrive/mongod.log + replSet = mongors + + #. Save the config file + +Instance 3 +~~~~~~~~~~ + + #. Connect to the instance using ssh or PuTTY + #. As sudo, edit /etc/mongod.conf to set the following parameter: + + .. code-block:: sh + + port = 27020 + dbpath = /mnt/datadrive/data + logpath = /mnt/datadrive/mongod.log + replSet = mongors + + #. Save the config file + +Start MongoDB +------------- + +Once the configuration files have been edited, start the database +process mongod on each instance by: + + #. Log on onto the instance + #. Run the following command to start the process: + + .. code-block:: sh + + mongod –config /etc/mongod.conf + + #. This should start the mongod process + #. Verify that mongod start by tailing the log file using the + command + + .. code-block:: sh + + tail –f /mnt/datadrive/mongod.log + + #. The ``waiting for connections`` message in the log file indicates + mongod is up and running and waiting for client + connections. This may take a while as mongod preallocates its + journal files + + .. image:: img/image17.png + +Configure the replica set +========================= + +At this point in time, you should have mongod running on all 3 of your +instances. You can now configure the 3 instances as a replica set by +connecting to 1 of the 3 instances from within Azure or from outside. +Connect to the running mongod process using the :program:`mongo` shell: + + #. If connected to the VM instance type the following command where + port is 27018 for instance 1, 27019 for instance 2 and 27020 for + instance 3: + + .. code-block:: sh + + mongo –port + + #. If connecting to the mongod process in Azure from your local + machine use the following command: + + .. code-block:: sh + + mongo –host mongodbrs.cloudapp.net –port + + #. In the :program:`mongo` shell type the following: + + .. code-block:: sh + + > conf = { + _id = “mongors”, + members : [ + {id:0, host:”mongodbrs.cloudapp.net:27018}, + {id:0, host:”mongodbrs.cloudapp.net:27019}, + {id:0, host:”mongodbrs.cloudapp.net:27020}]} + > rs.initiate(conf) + + .. image:: img/image09.png + + #. This will start the initialization of the mongodb replica set + #. Type the command ``rs.status()`` to check the status of the + replica set. Upon successful initialization, you should see 1 of + the 3 instances being the ``Primary`` of the set and the other 2 + being the ``Secondaries``. + + .. image:: img/image05.png + + #. You have now successfully initiated the replica set + +Summary +======= + +In this tutorial you have learned how to create a set of CentOS +virtual machines on Windows Azure, deploy MongoDB to them and create a +replica set out of them. You can access this set from anywhere using +the connection string ``mongodb://mongodbrs.cloudapp.net:27018, +mongodbrs.cloudapp.net:27019, +mongodbrs.cloudapp.net:27020/?replicaSet=mongors``. + +More information on MongoDB can be found at +http://docs.mongodb.org/manual/. + +To create and deploy a replica set to Windows Virtual Machines on +Azure you can use the `MongoDB Installer for Windows Azure +`_.