github.com/dahs81/otto@v0.2.1-0.20160126165905-6400716cf085/website/source/intro/getting-started/appfile.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "Appfile"
     4  sidebar_current: "gettingstarted-appfile"
     5  description: |-
     6    Learn about the Appfile in the Otto getting started guide.
     7  ---
     8  
     9  # Appfile
    10  
    11  Up to this point, we've developed and deployed a Ruby application
    12  with _zero configuration_. For a getting started experience, it is hard
    13  to beat that.
    14  
    15  For real applications, Otto will likely need some minimal configuration.
    16  The file Otto uses for configuration is the `Appfile`. The Appfile is
    17  meant to describe everything required to develop and deploy an application.
    18  
    19  On this page, we'll write a simple Appfile that mimics the behavior that Otto
    20  automatically gave us with zero configuration. Then, in the following
    21  getting started pages, we'll augment the Appfile to add new behavior
    22  to our environment.
    23  
    24  ## A Complete Appfile
    25  
    26  We'll start by showing the complete Appfile, and then we'll go over
    27  each part in the following sections. Save the following file to the
    28  root of the example application in a file named "Appfile":
    29  
    30  ```
    31  application {
    32    name = "otto-getting-started"
    33    type = "ruby"
    34  }
    35  
    36  project {
    37    name = "otto-getting-started"
    38    infrastructure = "otto-getting-started"
    39  }
    40  
    41  infrastructure "otto-getting-started" {
    42    type = "aws"
    43    flavor = "simple"
    44  }
    45  ```
    46  
    47  This is functionally equivalent to the behavior of Otto with zero
    48  configuration for our example application.
    49  
    50  The syntax of the Appfile is [documented here](/docs/appfile).
    51  
    52  ~> **WARNING:** Make sure the name of the infrastructure is not
    53  changed above. If you change this, Otto will "lose" your infrastructure
    54  and you'll have to destroy it manually.
    55  
    56  ## Appfile Compilation
    57  
    58  Changes to an Appfile don't take effect for any Otto commands such
    59  as `otto dev` until it is recompiled. To recompile an Appfile, use
    60  `otto compile`.
    61  
    62  This feature is very nice since even if other members of a team
    63  might have edited the Appfile, your environment isn't affected
    64  until you decide to recompile.
    65  
    66  With the Appfile above, recompiling won't have any adverse effect,
    67  since we've created an Appfile that is functionally equivalent to what
    68  Otto did with zero configuration.
    69  
    70  ## Appfile Sections
    71  
    72  Now that we've written an Appfile, let's dive into the each part of it.
    73  
    74  The **application** section defines properties related to the application.
    75  In our Appfile, we specify the name of the application and the type.
    76  The type of the application is what tells Otto how to build our
    77  development environment, builds, deploys, etc. The full set of
    78  [application types](/docs/apps/index.html) is documented.
    79  
    80  In addition to the name and type of the application, this section
    81  can include application dependencies, which we cover in an upcoming
    82  step in the getting started guide.
    83  
    84  The **project** section defines the project that this application is part
    85  of. Projects currently aren't used for anything other than organization
    86  within Otto. The only important configuration here is the "infrastructure"
    87  setting which tells Otto what infrastructure to target.
    88  
    89  The **infrastructure** section defines the infrastructure targets
    90  that this application can be deployed to. This section can be repeated
    91  multiple times. The name of an infrastructure must be unique _globally_
    92  throughout your usage of Otto. If the name of an infrastructure matches
    93  another Appfile, then Otto will assume you want to deploy to the same
    94  infrastructure.
    95  
    96  There is another section that an Appfile can contain which we haven't
    97  used yet: **customization**. The customization sections change the behavior
    98  of Otto. We'll see customizations in use in an upcoming step in the
    99  getting started guide.
   100  
   101  ## Compile and Verify
   102  
   103  Once you've saved the Appfile, run `otto compile` again followed by
   104  `otto status`. The status should still look like the following:
   105  
   106  ```
   107  ==> App Info
   108      Application:    otto-getting-started (ruby)
   109      Project:        otto-getting-started
   110      Infrastructure: aws (simple)
   111  ==> Component Status
   112      Dev environment: CREATED
   113      Infra:           READY
   114      Build:           BUILD READY
   115      Deploy:          DEPLOYED
   116  ```
   117  
   118  If any of the components are not ready, then the Appfile may have a typo
   119  in it. Verify you copy and pasted the above properly and try again. Don't
   120  forget to recompile!
   121  
   122  ## Zero Configuration vs. Appfile
   123  
   124  So far, we've only recreated an Appfile that does exactly what Otto does
   125  with zero configuration. What is the point?
   126  
   127  For what we've done so far, there is no reason to have an Appfile.
   128  However, Otto with zero configuration only does the bare minimum possible
   129  for every application type, and is heavily opinionated. Writing an
   130  Appfile allows you to be explicit in how you want Otto to behave.
   131  
   132  In addition to that, features such as dependencies can't be used at all
   133  without an Appfile. This is what we're going to learn next!
   134  
   135  ## Next
   136  
   137  We've added an Appfile and re-compiled!
   138  
   139  Now that we have an Appfile that mimics our _zero configuration_ setup,
   140  we can change how Otto behaves by [customizing our Appfile](/intro/getting-started/customization.html).