OpenAperture

OpenAperture is a free, open-source hybrid cloud management platform that delivers software quickly and consistently regardless of location or workload. This future-ready platform from Lexmark Enterprise Software provides a comprehensive management system to handle the six pillars of cloud management – provisioning, deployment, monitoring, maintenance, security and metering.

Building & Deploying System Components

OpenAperture is designed to "eat it's own dog food", i.e. deploy itself. Each System Component, therefore, can be built and deployed using a docker container. The following table describes the required installations for each System Component (build-time requirements), as well as the Fleet configuration (run-time configuration) needed to deploy the containers. Each components should have it's own corresponding deployment repository, with the following configuration:

Build-Time Requirements	Run-Time Configuration
Manager
The Manager has the following build-time requirements: The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir postgresql-client A PEM file is required for encrypting sensitive values at rest in the database. Both the public and private key files are required.	The Manager has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MANAGER_DATABASE_HOST:  String hostname of the database connection MANAGER_DATABASE_NAME:  String name of the database MANAGER_PASSWORD:  String containing the database password MANAGER_USER_NAME:  String containing the database user MANAGER_MESSAGING_KEYNAME:  String name of the PEM file that should be used for encrypting private information MANAGER_MESSAGING_PRIVATE_KEY:  String containing the absolute path to the private key of the PEM file that should be used for encrypting private information MANAGER_MESSAGING_PUBLIC_KEY:  String containing the absolute path to the public key of the PEM file that should be used for encrypting private information MIX_ENV:  String containing the mix environment (i.e. prod) PORT:  Integer representing the port for Phoenix (default is not set for prod) OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret MANAGER_OAUTH_VALIDATE_URL:  String pointing to the OAuth validationg URL for the OAuth Provider OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the Manager UI_URL:  String pointing to a UI URL
Overseer
The Overseer has the following build-time requirements: The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir	The Overseer has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider QUEUE_NAME:  String with the AMQP queue name for "overseer" messages; specific to the associated MessagingExchange SYSTEM_MODULES_QUEUE_NAME:  String with the AMQP queue name for "system_modules" messages; specific to the associated MessagingExchange
Notifications
The Notifications has the following build-time requirements: The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir	The Notifications has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider EMAIL_QUEUE_NAME:  String with the AMQP queue name for "notifications_email" messages; specific to the associated MessagingExchange HIPCHAT_QUEUE_NAME:  String with the AMQP queue name for "notifications_hipchat" messages; specific to the associated MessagingExchange HIPCHAT_AUTH_TOKENS:  String containing a comma-delimited list of HipChat API authentication tokens (v2). HIPCHAT_DEFAULT_ROOM_NAME:  String defining the default HipChat room id or name in which to publish all messages SMTP_FROM:  String containing the email address used to send emails from an SMTP server SMTP_PASSWORD:  String containing the password associated with the email address used to send emails from an SMTP server SMTP_PORT:  Integer representing the port for the SMTP server SMTP_URI:  String containing the URL of the SMTP server
WorkflowOrchestrator
The WorkflowOrchestrator has the following build-time requirements: The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir	The WorkflowOrchestrator has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider UI_URL:  String pointing to a UI URL QUEUE_NAME:  String with the AMQP queue name for "workflow_orchestration" messages; specific to the associated MessagingExchange
Builder
The Builder has the following build-time requirements: The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir makedev apt-transport-https lxc-docker-x.x.x (the version will vary based on the current CoreOS version of docker) The git executable must be in the PATH The goon executable must be in the PATH	The Builder has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider DOCKER_REGISTRY_EMAIL:  String containing the email associated with a Docker registry DOCKER_REGISTRY_PASSWORD:  String containing the password for a user associated with a Docker registry DOCKER_REGISTRY_URL:  String containing the URL for a Docker registry DOCKER_REGISTRY_USERNAME:  String containing the username for a user associated with a Docker registry GITHUB_OAUTH_TOKEN:  String containing an x-oauth-basic token for Github; this token is required to have access to all source and deployment repositories. The value should be in the format of x-oauth-basic:*token* QUEUE_NAME:  String with the AMQP queue name for "builder" messages; specific to the associated MessagingExchange
Deployer
The Deployer has the following build-time requirements: The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir The fleetctl executable must be in the PATH (the release will vary based on the current CoreOS version of docker) In order for fleetctl to be successful, SSH access to the application clusters is required. The deployer's scripts will check for the SSH file in /root/.ssh/id_rsa	The Deployer has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider QUEUE_NAME:  String with the AMQP queue name for "deployer" messages; specific to the associated MessagingExchange
Deployer OA
The Deployer OA has the following build-time requirements (note that the source code is the same as Deployer, simply a different deployment config): The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir The fleetctl executable must be in the PATH (the release will vary based on the current CoreOS version of docker) In order for fleetctl to be successful, SSH access to the application clusters is required. The deployer's scripts will check for the SSH file in /root/.ssh/id_rsa	The Deployer OA has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider QUEUE_NAME:  String with the AMQP queue name for "deploy_oa" messages; specific to the associated MessagingExchange
FleetManager
The FleetManager has the following build-time requirements (note that the source code is the same as Deployer, simply a different deployment config): The following package(s) are required to be installed: erlang-solutions_1.0_all (from erlang-solutions.com). This will install Erlang and Elixir The fleetctl executable must be in the PATH (the release will vary based on the current CoreOS version of docker) In order for fleetctl to be successful, SSH access to the application clusters is required. The deployer's scripts will check for the SSH file in /root/.ssh/id_rsa	The FleetManager has the following build-time environment configuration: BROKER_ID:  Integer representing the MessagingBroker, which should be used to connect to the AMQP broker EXCHANGE_ID:  Integer representing the MessagingExchange, which should be associated with the component MIX_ENV:  String containing the mix environment (i.e. prod) MANAGER_URL:  String pointing to the OpenAperture Manager OAUTH_CLIENT_ID:  String containing the OAuth Client ID OAUTH_CLIENT_SECRET:  String containing the OAuth Client Secret OAUTH_LOGIN_URL:  String pointing to the OAuth login URL for the OAuth Provider QUEUE_NAME:  String with the AMQP queue name for "fleet_manager" messages; specific to the associated MessagingExchange

Starting the System Component Docker Containers

OpenAperture is designed to manage itself, that is build itself, deploy itself. Due to this back, the first time you spin up an OpenAperture instance, there is a small, manual step that is required. In order to successfully spin up a Manager, the EtcdCluster must be registered in the database (before the RESTful services will come online). To get around this behavior, a manual database insert is required (the example below uses 123abc as the etcd token and assumes that the psql command line tools have been installed):

INSERT INTO messaging_exchanges (
  name,
  inserted_at,
  updated_at
)
VALUES (
  'Name of Primary Exchange',
  now(),
  now()
);

INSERT INTO etcd_clusters (
  etcd_token,
  allow_docker_builds,
  messaging_exchange_id,
  name,
  inserted_at,
  updated_at
)
VALUES (
  '123abc',
  false,
  *id from previous insert*,
  'OA Primary Cluster',
  now(),
  now()
);
			

Once the Manager is running successfully, you can define your remaining Exchanges, Brokers, BrokerConnections, etc... The following set of commands will allow you to spin up a Fleet service on a CoreOS cluster (for the first time):

• Clone Deployment Repo:  git clone https://github.com/MyOrg/overseer_deploy.git
• Change into the directory:  cd overseer_deploy
• Update the overseer@.service.eex with the required run-time configuration
• Build the docker container
• Login:  docker login -e="email@address.com" -u="user" -p="pass"
• Build:  docker build --force-rm=true --no-cache=true --rm=true -t company/oa_overseer .
• Tag:  docker tag --force=true *image_id* company/oa_overseer:*source commit hash*
• Push:  docker push company/oa_overseer
• Submit the Fleet file:  fleetctl submit overseer.service
• Start the service:  fleetctl start overseer@{0..2}.service
• Ensure the service is running:  fleetctl list-units (service should be in a "launched", "running" state.
• View the docker logs to ensure that no exceptions occurred during startup
• Find the container id:  docker ps
• View the logs:  docker logs -f *container-id*