com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Quick Start Guide

In this guide, we focus on deploying the pre-built EC2 image of Stratos 2. For information on deploying Stratos 2.0 on EC2 from scratch or on other IaaSes, see the Deployment Guide.

Starting the Stratos Demo Image

Prerequisites for step 1

PrerequisiteDescription
Common PrerequisitesEnsure that the common prerequisites are met.
EC2 AccountTo follow this guide, you need an EC2 account. Create an AWS account if you do not have an account. For more information, see Sign Up for Amazon EC2. This account must be authorized to manage EC2 instances (including start and stop instances, create security groups and key pairs). 
Stratos 2.0 EC2 imageWe have created a EC2 image (AMI) for Stratos, as well as several Cartridges. The Stratos 2.0 AMI is the main AMI that you should care about. Stratos will spawn the Cartridges instances based on the preferences you set at the config time.
Create a security groupFor more information, see Creating a security group.
Create a Key PairFor more information, see Creating a Key Pair.
Gather the required dataFor more information, see Gathering data.

 


AMIs

For a quick start, you can use one of the following  public Elastic Compute Cloud (EC2) images.

EC2 ImageAsia Pacific (Singapore) RegionUS East - 1 (N. Virginia) Region

Stratos 2.0

ami-c3ca8491ami-dfb8cfb6

PHP Cartridge

ami-57cf8105ami-c5b6c1ac

MySQL Cartridge

ami-4bcf8119ami-7bb4c312
Tomcatami-23b5fb71ami-09b5c260

WSO2 Carbon Cartridge

ami-0da7e95fami-63b6c10a
Creating a Security Group

Before launching the instance, you need to create the right security group. This security group defines firewall rules for your instances, which are a list of ports that are used as part of the default Stratos deployment. These rules specify which incoming network traffic is delivered to your instance. All other traffic is ignored. The ports that should be defined are listed here: Common IaaS Configurations.

To create the security group and configure it:

  1. On the Network and Security menu, click Security Groups.
  2. Click on Create Security Group.
  3. Enter the name and description of the security group.
     
  4. Click Yes, Create .
  5. Click Inbound.
     
  6. Select "Custom TCP rule".

    All the UDP and TCP ports can be opened by adding the following two rules. Note that the latter mentioned two rules are a demo only setting. Individual rules with the specified ports must be added for security purposes in a production environment.

    Rule typePort Range
    All TCP0 - 65535
    All UDP0 - 65535

     

  7. Enter the port or port range.
    There are two kinds of ports listed in the common configurations, which are namely open for outside access and restricted internal access. You will have to ideally enter each of the ports as separate rules.  

  8. You can set the Source to be 0.0.0.0/0

    Note that setting the Source to be 0.0.0.0/0 is a demo only setting, which must be changed for security purposes in a production environment.

    For details, go to http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-network-security.html.

  9. Click Add Rule and then click Apply Rule Changes.
    Always apply rule changes, as your rule will not get saved unless the rule changes are applied.
    Repeat steps 6 to 9 to add all the ports mentioned, as each port or port range has to be added as a separate rule.

    Note down the names of your security groups if you wish to enter your user data in the wizard.

Creating a Key Pair

Before launching the instance, it is recommended to create a Key Pair. Save your private key in a safe place on your computer. Note the location because you will need the Key Pair to connect to your instance.  

To create a Key Pair and download it:

  1. On the Network and Security menu, click Key Pairs.
  2. Click Create New Key Pair.
  3. Enter a name for your Key Pair.
  4. Click Create. After the Key Pair automatically downloads, click Close.
Gathering data

The following data is required:

  • Access key and Secret key of your EC2 account
    To get your Access Key ID and Secret Access Key:
    1. On the EC2 account details menu, click My Account
    2. Click Security Credentials on the left-bar menu.
    3. Switch to the Access Keys tab.
    4. Create an access key for this setup.
      Then note the Access Key ID and Secret Access Key. 

  • Owner ID
    To view the Owner ID:
    • On the EC2 account details menu, click My Account
       
    • Your account number will appear, which is your Owner ID. Omit the hyphens when entering the Owner ID.
       
  • Availability zone
    This is the zone where the virtual machines will be launched. If you set the Availability zone to "No Preference", the system will set the default value. Only Asia Pacific Singapore and US East 1 are available at this point, and therefore the potential values are:
    • us-east-1
      This will be the default value, if you want to let the system choose the availability zone. Otherwise, provide us-east-1a, us-east-1b or us-east-1c.
    • ap-southeast-1
      This will be the default value, if you want to let the system choose the availability zone. Otherwise, provide ap-southeast-1a or ap-southeast-1b.
      
  • Domain name
    This is the CNAME for your Stratos domain, such as stratos2-demo.com

Step 1: Spawning the Stratos 2.0 instance

  1. Sign in to the Amazon Web Services (AWS) Management Console and open the Amazon EC2 console at https://console.aws.amazon.com/ec2/   
     
  2. Click EC2 on the home console.
  3. Select the either the Asia Pacific (Singapore) or US - East (North Virginia) region for the instance from the region drop down list.
    In the rest of the steps, we assume that you have chosen North Virginia.
     
  4. Click Launch Instance.

  5. Select  Quick Launch Wizard.

    If you use the Classic Wizard, your response may contain an invalid JSON while searching for AMIs. Therefore, we recommend you to retry later or switch to the Quick Launch Wizard. 
  6.  Name your instance, for example Stratos2Demo.

  7. Select the Key Pair that you created (we recommend that you use a specific keypair for the Stratos installation).
  8. Select More Amazon Machine Images and click on Continue.

  9. On the next page, specific the image ID as per the table above and click Search
  10. Click on your search result and click Continue.
  11. Click Edit Details.
  12. Edit the image size.
    1. Select the Instance Details option.
    2. Change the image type to either m1.xlarge or m3.xlarge (15GB of memory).
  13. Select a security group.
    1. Select the  Security Settings  option.
    2. Click Select Existing Security Groups.
    3. Select the Stratos security group you have created previously.
  14. Add user data
    1. Click Advanced Details.
    2. Enter the following parameters with your own values in the  User Data  text-box and do not keep spaces in between the user data text. 

      You can either enter a part of the parameters or skip this entire step. If you do not enter the required configurations in this step, then you will be prompted for those configurations at a later step. 

      To avoid having to add the user data each time a server is restarted, it is recommended to enter the user data parameters at this point.

      User DataDescription
      EC2_KEY_PATH
      The path that you will upload your EC2 key.
      ACCESS_KEY
      See Access key and Secret key of your EC2 account
      SECRET_KEY
      See Access key and Secret key of your EC2 account  
      OWNER_ID
      See Owner ID
      AVAILABILITY_ZONE
      See Availability zone  
      SECURITY_GROUP
      See Creating a Security Group
      KEY_PAIR_NAME
      See Creating a Key Pair
      DOMAIN
      This is the CNAME for your Stratos domain, such as isawso2.com

       

      EC2_KEY_PATH=<YOUR_EC2_KEY_PATH>,ACCESS_KEY=<YOUR_EC2_ACCESS_KEY>,SECRET_KEY=<YOUR_EC2_SECRET_KEY>,OWNER_ID=<YOUR_EC2_OWNER_ID>,AVAILABILITY_ZONE=<YOUR_PREFERRED_AVAILABILITY_ZONE>,SECURITY_GROUP=<YOUR_EC2_SECURITY_GROUP>,KEY_PAIR_NAME=<YOUR_EC2_KEY_PAIR_NAME>,DOMAIN=<YOUR_PREFERRED_DOMAIN_NAME>

      Example

      EC2_KEY_PATH=/home/ubuntu/my-key.pem,ACCESS_KEY=GKIAJDRXVUANL8X7YCXM,SECRET_KEY=FDweWYluA6HCuJo/+SP1mJiLpOixcm4grfj36j1v,OWNER_ID=168986784701,AVAILABILITY_ZONE=ap-southeast-1a,SECURITY_GROUP=s2-demo,KEY_PAIR_NAME=my-key,DOMAIN=stratos2-demo.com

  15. Click Save details.

  16. Review the information and click Launch  to start the EC2 instance.

  17. Click Close.
    This will redirect you to the instance page. It takes a short time for an instance to launch. The instance's status appears as pending while it is launching.  After the instance is launched, its status changes to running.  


Configuring the Stratos Instance

Prerequisites for step 2

PrerequisiteDescription
Upload the Key Pair fileFor more information, see Uploading your Key Pair file.
Locate your EC2 instance hostnameFor more information, see Locating your EC2 instance hostname.  
Uploading your Key Pair file

You need to upload the PEM file that you created during the image configuration (for example, StratosKeyPair.pem) to the running Stratos instance. This file will be used to securely copy files to the runtime instances (Cartridges).

Your Key Pair is also known as your private key. In the following instances, if you have navigated to the directory of the Key Pair, enter only the name of the Key Pair; otherwise, e nter the full path of the Key Pair.

  1. Change the PEM file permissions.
    By default your PEM file will be unprotected.  When uploading your PEM file, if it is unprotected it will be rejected. Use the following command to secure your PEM file so that others will not have access to it: 

    chmod 0600 <path to the private key>
  2. Upload the Key Pair using the following scp command:  

    scp -i <path to the private key> <path to the private key> ubuntu@<EC2 instance hostname>:

    In the above command the  private key will be uploaded to  /home/ubuntu location on the Stratos instance.

    Example:

    scp -i StratosKeyPair.pem StratosKeyPair.pem ubuntu@ec2-53-123-267-637.compute-1.amazonaws.com:/tmp

    Once the command mentioned in the example completes, the PEM will be uploaded to the /tmp location on the Stratos instance.

  3. The following output will appear. Say 'yes' to connect and add the RSA fingerprint to your known hosts list.

    The authenticity of host 'ec2-53-123-267-637.compute-1.amazonaws.com (53.123.267.637)' can't be established.
    RSA key fingerprint is aa:43:w9:rc:te:66:81:98:hh:ya:65:f9:d8:f9:77:79.
    Are you sure you want to continue connecting (yes/no)? yes

     

Locating your EC2 instance hostname

To get your  EC2 instance hostname:

  1. On the Instances menu in the navigation panel, click the Instances sub-menu. 
    The list of instances that you own will appear. 

  2. Search and select the correct instance.
    The EC2 instance hostname will appear in the second line of the bottom pane that contains descriptions on the instance. 
     

 


Step 2: Configuring the Stratos Instance

Once the instance is successfully launched, you need to configure several settings that will be used by Stratos to manage and launch the virtual machines (Cartridges) available.

  1. Login to the instance using ssh with ubuntu as the username and the Key Pair that you downloaded when you were spawning the instance as the password.
    If you have navigated to the directory of the Key Pair, enter only the name of the Key Pair in the following ssh command; otherwise, e nter the full path of the private key.

    ssh -i <private key path> ubuntu@<EC2 instance hostname>

    Example:

    ssh -i StratosKeyPair.pem ubuntu@ec2-53-123-267-637.compute-1.amazonaws.com
  2. Once connected, start a root session using:

    sudo -i
  3. Navigate to the /opt location using:

    cd /opt
  4. Run the config.sh script located in this directory, using:

    ./config.sh
  5. The script prompts you to override data. 

    root@ip-10-149-5-240:/opt# ./config.sh 
    Please confirm that you want to be prompted, irrespective of whether the data is available in the user-data? [y/n]
    • Enter [n] 
      As we have provided user data when launching the instance you can use this option. However, you will be prompted for the values that are not found in the user data section.

    • Enter [y] 
      This will discard the values in the User Data section and will prompt for the user data details that need to be configured according to your EC2 account. This is useful if you have mistakenly added incorrect values for fields in the User Data section. Answer to the list of questions, using the data gathered above.

      Beware that you are working under a Linux system, so filename capitalization does matter (for example /tmp/StratosKeyPair.pem).


      Please copy your EC2 public key and enter full path to
      it (eg: /home/ubuntu/EC2S2KEY.pem):/tmp/StratosKeyPair.pem
      Access Key of EC2 account : AKIAJIPHGYXXXXXXXXX
      Secret key of EC2 account : 0MvN0gEZXjKPpz6j0MCoAMXXXXXXXXXXXXXXXX
      Owner id of EC2 account :86306XXXXXXX
      Availability zone (default value: us-east-1c) :us-east-1
      Name of the EC2 security group (eg: s2demo) :Stratos
      Name of the key pair (eg: EC2S2KEY) :StratosKeyPair
      Domain name for Stratos (default value: stratos2.wso2.com) :isawso2.com
      updating: launch-params (stored 0%)
      updating: launch-params (stored 0%)
      updating: launch-params (stored 0%)

    Once all questions are answered, the script will configure the various deployment scripts and Stratos will be ready to create tenants and allows them to use Cartridges. 

    You have successfully configured STRATOS 2.0. !!
    Make sure you have read the configuration guide and have setup properly, press [y] to continue, [n] to exit.
  6. Answer 'y' to the next question and all the servers will be started.

    Starting BAM server ...
    nohup: appending output to `nohup.out'
    Starting CC server ...
    nohup: appending output to `nohup.out'
    Starting SC server ...
    nohup: appending output to `nohup.out'
    Starting ELB server ...
    nohup: appending output to `nohup.out'
    Starting Agent server ...
    nohup: appending output to `nohup.out'
    Starting internal Git Server ...
    nohup: appending output to `nohup.out'
    Stratos 2.0 servers started up successfully!

If you make a mistake during the confirmation, use the  clean.sh script to reset the configuration before running the  config.sh script again.

Registering a tenant and configuring Cartridges

Once the Stratos main servers have been started, you can connect to the Stratos controller (which is the “heart” of Stratos) to create a tenant. A tenant is an organization that will use the PaaS. Inside an organization, one or N Cartridges (runtimes) can be subscribed to.

The Stratos controller runs at: https://<INSTANCE_HOSTNAME>:9445 (for example, https://ec2-184-72-129-229.compute-1.amazonaws.com:9445). Once you are connected, login using the default admin user (admin/admin). This logs you in as the super tenant administrator.

  1. Change your default super tenant admin password.
  2. Create a Tenant.
  3. Subscribe to Cartridges. For more information, see Subscribing to a Cartridge and Connecting to another Cartridge when subscribing.
  4. If you wish, map a domain to the newly created Cartridge.
  5. Map the host name to ELB IP.


com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.