Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


This articles describes how to setup the Maestrano Hub component on a server / auto-scaling group using mno-deploy, Maestrano's Ansible automation framework.




Table of Contents
stylenone




1 - Prerequisites

This documentation is tailored for AWS. While the steps can be adapted for other platforms you may need to contact us to get further guidance if you are trying to use the below instructions for Azure, SoftLayer or Google Compute Cloud.

In order to perform this installation you will need to setup a Github repository to store your configuration (e.g. mno-deploy-myproject) and setup a build process to package this repository as a tar.gz archive and push it to one of your AWS S3 buckets. This section provides more information on what to include in this configuration repository.

2 - Configuration

This section describes how to setup the ansible configuration parameters in mno-deploy to deploy Maestrano Hub. These configuration activities should be performed on your configuration project (e.g. mno-deploy-myproject) under ansible/vars/<environment_name>.yml and ansible/vars/<environment_name>_secrets.yml

1.1 - Infrastructure configuration

In order to setup Maestrano Hub you need to fill certain parameters describing how the Load Balancer, Launch Configuration and Auto-Scale group should be configured for MnoHub.

A basic example is provided here: https://github.com/maestrano/mno-deploy/blob/develop/ansible/vars/example.yml#L91

Below is a commented example of what each parameter means. You can see the full list of default values by looking at the group_vars on github.

Code Block
# MnoHub Infrastructure Configuration
mnohub:
  # should this component be setup or not
  skip: false
  launch_configuration:
	# AWS instance size for mnohub
    instance_type: c3.large
	# OPTIONAL - you can use spot instances in test environments
    spot_price: 0.0235
  auto_scaling_group:
	# how many instances of MnoHub should be launched at minima
    min_size: 1
	# max number of instances to launch
    max_size: 2
	# target number - used when failure occurs on one of the machines
    desired_capacity: 1
  elastic_load_balancer:
	# this block specifies how to load balance traffic
    listeners:
      - 
		# incoming traffic protocol - if you are behind a firewall you may set it to HTTP
		protocol: https
		# incoming traffic port - if you are behind a firewall you may set it to 80
        load_balancer_port: 443
		# protocol to use on the instance - if encryption in transit is required you may set it to https
        instance_protocol: http
		# port to use on the instance - if encryption in transit is required you may set it to 443
        instance_port: 80
		# IAM certificate to use on the ELB side. Only required if load_balancer_port is 443 and protocol is https
        ssl_certificate_id: "arn:aws:iam::647381683421:server-certificate/some.iam.certificate"


1.2 - Application configuration

The configuration block below relates the Maestrano Hub runtime configuration. This runtime configuration is split between settings and secrets. Therefore the configuration is spread over two files:

  • settings: ansible/vars/<environment_name>.yml
  • secrets (encrypted): ansible/vars/<environment_name>_secrets.yml

Below is a commented example of what each parameter means. You can see the full list of default values by looking at the group_vars on github.

Code Block
mnohub_config:
  # Whether to run migration. Should be set to false
  skip_migrations: false
  # Enable/Disable sidekiq for Maestrano Hub. Should be set to false
  background_jobs_disabled: false
  # This section describes how assets (images, js/css files) are stored
  carrierwave:
	# Name of the AWS buckets where assets will be stored
    public_bucket: some-aws-bucket
	# Domain used to serve assets. Typically this will be the s3 host or cloudfront host
	# if you have activated Cloudfront for your S3 bucket
    asset_host: some-cloudfront-id.cloudfront.net
  general:
	# OPTIONAL: only required if you want to enable hosted apps by us. Please contact us.
    nex_host: "https://{{ nex.dns_record.record }}"
	# OPTIONAL: only required if hosted apps are enabled. Please contact us.
    apps_domain: "apps.uat.maestrano.io"
	# This value is used to generate unique email addresses for application providers
    virtual_email_domain: "appmail.somearbitrarydomain.com"
  # OPTIONAL (will default to maestrano.dns_record.record)
  # This block defines how Maestrano Hub should be accessed outside of the VPC
  # This configuration block is typically used by other applications
  public_dns:
    scheme: https
    host: api-hub.mydomain.com
  # OPTIONAL (will default to maestrano.dns_record.record)
  # This block defines how Maestrano Hub should be accessed inside the VPC
  # This configuration block is typically used by other applications 
  private_dns:
    scheme: http
    host: api-hub.internal
  # OPTIONAL (will default to rds.endpoint)
  # Describe the database access
  database:
    host: some-db-host.somedomain.com
  # OPTIONAL: if specified then an initial tenant will be created on first deploy
  default_tenant:
    name: Some Tenant Name
    id: some-uuid
    key: some-secret-key
    scheme: https
    host: frontend-host.example.com
  # OPTIONAL: New Relic app name and enablement flag. The global var newrelic_license_key must be set.
  new_relic:
    enabled: true
    app_name: MnoHub
  # OPTIONAL: whether to monitor the application using Splunk. The global vars splunk_* must be set
  splunk:
    enabled: true
  # OPTIONAL: whether to monitor the application using Splunksumologic. The global configuration block 'sumologic' must be set
  sumocollector:
    enabled: true


Below is an example of secrets configuration block. Note that the <environment_name>_secret.yml must stay encrypted using ansible-vault.

Code Block
# MnoHub configuration
mnohub_config:
  # Database credentials
  database:
    username: db_username
    password: some_password
  # Rails secrets
  secrets:
    # This key is used to encrypt credentials in database. Use "rake secret" to generate it.
    encryption_key: some_random_key
    # This service is used to convert monetary values. Put your OpenExchangeRate.org API key
    open_exchange_rate_id: open_exchange_rate_api_key
	# Rails secret. Use "rake secret" to generate it.
    secret_token: some_random_key
	# Rails secret. Use "rake secret" to generate it.
    secret_key_base: some_random_key
  # The AWS credentials to use to manage the 'assets' bucket (used to upload images, js/css files)
  s3_bucket:
    access_key: aws_key
    secret_access_key: aws_secret
  # OPTIONAL: Payment gateway. eWay credentials.
  eway:
    login: eway_login
    username: eway_username
    password: eway_password
  # OPTIONAL: Payment gateway. Braintree credentials.
  braintree:
    merchant_id: braintree_merchant_id
    public_key: braintree_public_api_key
    private_key: braintree_private_api_key


3 - Infrastructure setup

1.1 - Using Ansible

You can use the mno-deploy Ansible script to deploy Maestrano Hub. Usually Maestrano Hub will be setup as part of running the setup_infrastructure.sh script, which sets up the whole Virtual Private Cloud.

To run that script, just follow the instructions below:

Code Block
# Export your AWS API keys. Your keys must have enough privileges to create and manage an entire VPC
export AWS_ACCESS_KEY_ID=aws-api-key
export AWS_SECRET_ACCESS_KEY=aws-api-secret
export AWS_DEFAULT_REGION=aws-region # e.g. ap-southeast-1

# Specify the version of the configuration scripts to use. Note the configuration scripts will be fetched 
# from the AWS bucket specified in your continuous integration tool (e.g. Codeship) which packages the configuration script
# from Github and sends to AWS S3.
export MNO_DEPLOY_VERSION=develop/latest

# If you want to use your local configuration - e.g. if you have checkout the configuration project from Github - just
# specify 'local'
export MNO_DEPLOY_VERSION=local

# Name the configuration to use. The name of the environment must have corresponding <environment>.yml and <environment>_secrets.yml files.
export ENVIRONMENT_CONFIGURATION=myenv

# Path to key or script used to decrypt the <environment>_secrets.yml file.
export ANSIBLE_VAULT_PASSWORD_FILE=some/path/to/key.txt

# Finally run the script
sh scripts/setup_infrastructure.sh


1.2 - Manual Setup