Getting Started - yana/yana GitHub Wiki

If you get stuck two places to check:

• Issues
• List

If these docs missed something create an Issue and let us know. If you figure out a solution let us know at [email protected].

Prerequisites

• Java JRE 1.6+
• Tomcat 5+

YANA is a basic grails/spring-based JAVA web application.

General installation proceures are as follows:

• Download the desired version of the YANA WAR file from Bintray.
• Set up Tomcat Deployment on the server to host the YANA webapp. The default install uses an H2 database for model storage and authentication info.
• Configure YANA webapp. Check the config.properties (or config.groovy if yo prefer) to set YANA up for your environment. Configuration
• Start Tomcat server. Check to make sure the tomcat processes started up and the app has bound to its listening port.

Successful startup should allow you to go to the YANA home page.

See the Build page to learn how to build the YANA web app yourself.

The YANA installation created a default login that has admin access rights. Login with this default login, username/password is: admin/admin

If you have trouble logging in, check the Configuration to be sure the settings are correct. Also check the log for any error messages.

After login, you will be asked to choose or create a project.

YANA stores your models in a "project". A project is a storage space to keep one of your models. The scope of your model depends on your needs. Some might create a model to reflect one application in one environment. Another might create a model containing information about an entire environment.

To create a project click the "Create Project" link.

Give your project a name and description. The project name will be needed when accessing the model. After the project is created it will be shown in the project list.

When you click on your new project, you will be directed to the Node List page. Since the project is new and empty you must import a specification.

The following section describes how to write your own specification. There is an example specification that comes with the YANA install. Locate conf/import/example.xml and import it using the instructions below.

A model specification is an XML document declaring Nodes, Node Types, Attributes and Relationships. These specifications can be imported into a YANA project and merged with the model already existing in the project.

Nodes may also be declared in their own model specification. These Nodes might represent common pieces of information always found in the model. One might also create a model specification to describe Nodes in a desired state.

YANA model specifications are defined in an XML document. The following XML elements are used to declare YANA model objects.

• yana: root element. Can contain attributes, types, and relationships sub elements.
• attributes: Can contain attribute sub elements.
• attribute: Declares a Node property whose value is constrained by a particular filter.
• types: Can contain type sub elements.
• type: Declares a Node Type and its attributes.
• relationships: Can contain relationship sub elements.
• relationship: Declares a Node relationship between two Nodes. Types declare the allowable Node relationships between a Parent and Child type.
• children: Can contain child sub elements. Nodes declare relationships using the children element.
• child: Releates two Nodes.

Here's an example specification that declares a model specification about two Types, a "Host" and a "Service".

<yana>
  <attributes>
    <attribute name="pool" filter="String"/>
    <attribute name="port" filter="Integer"/>
  </attributes>
  <types>
   <type name="Host">
      <description>An application host</description>
      <attributes>
      	<attribute name="pool" required="true"/>
      </attributes>
    </type>
    <type name="Service">
      <description>An application service</description>
      <attributes>
      	<attribute name="port" required="true"/>
      </attributes>
    </type>
  </types>
  <relationships>
    <relationship name="deployment" parent="Host" child="Service"/>
  </relationships>
</yana>

The relationships elements declare that Nodes of "Host" type can have child Nodes of "Service" type.

Nodes can be declared in their own model specification. Here's an example that declares Nodes for the Host and Service Types defined above.

<yana>
    <nodes>
        <node name="ubuntu" type="Host" tags="tomcat,qa">
            <description>The ubuntu server</description>
            <attributes>
                <attribute name="pool" value="web-east"/>
            </attributes>
        </node>
        <node name="tomcat" type="Service" tags="simpleapp,qa">
            <attributes>
                <attribute name="port" value="8080"/>
            </attributes>
        </node>
    </nodes>
    <children>
        <child name="tomcat" type="Service">
            <parent name="ubuntu" type="Host"/>
        </child>
    </children>
</yana>

Note, if you attempt to import Nodes into a model that does not contain the required types, the import will fail. Be sure to load model specifications in the required order.

After creating your model specification, import the document into your YANA project.

From the Admin menu select the "Import Model" item. Set the XML Source File and press the "import" button. YANA will tell you if the XML import was successful.

If your document has syntax errors, the import process will fail. Often errors are due to syntax errors. The conf/import/yana.xsd file enforces the document structure so consult it to better understand the format requirements.

After loading a model specification to your project, you may wish to export the model back to a file. The exported model can be used to store in a source code repository or it may be used to exchange with another YANA.

Go to the Admin page and select Export Model item. Your browser may prompt you to set the destination folder. After the export has been initiated the browser will direct you to the downloaded file.

Note, if you imported more than one model specification the YANA project export will reflect the merged models.

You can list the Nodes in the model by clicking on the "Nodes" menu and choosing the "List" item.

Each node in the listing shows the name, type (in square brackets), description, and tags. An icon might also be shown if the Type declared one.

Clicking on the Node name will bring you to a page to see that Node's detail. Clicking the Node Type brings you to a page to view detail about that Type. Clicking on a tag, causes a search for other Nodes that also have that tag.

Type a search term into the Search text field. Entering a keyword defaults to looking for Nodes whose name matches that keyword.

The search keyword can use a prefix to closer match Nodes. For example,

• tags: Search Nodes with this tag keyword (eg, tags:QA)
• nodetype: Search Nodes that have a Type matching keyword (eg, nodetype:Host)

Click the node name to show detail about that Node. On the Show Node page, the Node's information is organized into three areas. General information like, name, type, description and tags is displayed in its own box. The Node's attributes are displayed below the general information box The left coloumn shows the attribute name while on the right, the attribute's value.

The right side of the page shows the Node's Relationships. The relationships are organized to show Parents and Children. Clicking on the node name will navigate you to that Node's information page.

The bottom bar on the page contains buttons to edit, delete and clone.

Note, your ACL may prevent you from any of these functions.

Press the Edit button from the Show Node page. The resulting page displays a form where any of the attributes can be modified. It's also possible to change relationships.

When complete, press the Update button. Press the Cancel button to return to the Show Node page.

Cloning a Node results in a like copy.

You will be redirected to the Show Node for the new clone.

Press the Delete button in the Node page. You will be prompted to confirm. Press "OK" to delete the Node.

You will be redirected to the Node List page.

The Types menu contains items to view Node Types, Attributes, Filters and Relationships.

At this time, there is no editing ability for the items inside the Types menu.

Select the Types menu and choose the "Node Types" item.

The resulting page is a list of Node Types specified in a model specification.

The listing, for each type, shows an icon (if specified), type's name, description and a count of Nodes of that type. Clicking the link for the Node count, will search for all Nodes of that Node Type.

Click the Type name to show the information about that Type. The Show Node Type page is organized into several areas. The Type's name and description and possibly an icon are grouped in one area.

Attribute information is displayed next. Each attribute's name and Filter is displayed. If a Node is required to define a value, an asterisk will appear next to the attribute name.

To the right on the page one sees Relationship information. The Parents listing shows Types allow its Nodes to create child relationships to this Type. The Children listing shows Node Types this type can link to.

Press the "Delete" button from the Show Type page. YANA checks the model to see if any Node's of that Type exists. If not, the type will be removed from the model. If the model does contain Nodes of the type, the page will be returned stating the requirement.