github.com/dahs81/otto@v0.2.1-0.20160126165905-6400716cf085/website/source/docs/appfile/dep-sources.html.md (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Dependency Sources - Appfile"
     4  sidebar_current: "docs-appfile-depsources"
     5  description: |-
     6    Application dependencies and Appfile imports both take a URL as a parameter
     7    to tell Otto where to load the external Appfile.
     8  ---
     9  
    10  # Dependency and Import Sources
    11  
    12  [Application dependencies](/docs/concepts/deps.html) and
    13  [Appfile imports](/docs/appfile/import.html) both take a URL as a parameter
    14  to mark the source of where to load the external Appfile data. Both of these URLs
    15  are in the same format and this page documents the supported values.
    16  
    17  Otto supports the following sources:
    18  
    19    * Local file paths
    20  
    21    * GitHub
    22  
    23    * BitBucket
    24  
    25    * Generic Git, Mercurial repositories
    26  
    27    * HTTP URLs
    28  
    29  Each is documented further below. The examples will use either an
    30  import statement or a dependency block. However, both imports and dependencies
    31  support all the values below.
    32  
    33  ## Local File Paths
    34  
    35  The easiest source is the local file path.
    36  
    37  In Otto, local file paths are relatively rare, except for testing purposes.
    38  If you are using local file paths, try to use relative paths into a sub-directory
    39  for maximum portability.
    40  
    41  An example is shown below:
    42  
    43  ```
    44  import "./folder" {}
    45  ```
    46  
    47  File paths are the only source URL that update automatically: Otto
    48  creates a symbolic link to the specified directory. Therfore, any changes
    49  are instantly available (versus at compile-time, like every other URL).
    50  
    51  ## GitHub
    52  
    53  Otto will automatically recognize GitHub URLs and turn them into
    54  the proper Git repository. The syntax is simple:
    55  
    56  ```
    57  dependency {
    58  	source = "github.com/hashicorp/otto/examples/mongodb"
    59  }
    60  ```
    61  
    62  GitHub source URLs will require that Git is installed on your system
    63  and that you have the proper access to the repository.
    64  
    65  You can use the same parameters to GitHub repositories as you can generic
    66  Git repositories (such as tags or branches). See the documentation for generic
    67  Git repositories for more information.
    68  
    69  ## BitBucket
    70  
    71  Otto will automatically recognize BitBucket URLs and turn them into
    72  the proper Git or Mercurial repository. An example:
    73  
    74  ```
    75  dependency {
    76  	source = "bitbucket.org/hashicorp/example"
    77  }
    78  ```
    79  
    80  BitBucket URLs will require that Git or Mercurial is installed on your
    81  system, depending on the source URL.
    82  
    83  ## Generic Git Repository
    84  
    85  Generic Git repositories are also supported. The value of `source` in this
    86  case should be a complete Git-compatible URL. Using Git requires that
    87  Git is installed on your system. Example:
    88  
    89  ```
    90  dependency {
    91  	source = "git://hashicorp.com/module.git"
    92  }
    93  ```
    94  
    95  You can also use protocols such as HTTP or SSH, but you'll have to hint
    96  to Otto (using the forced source type syntax documented below) to use
    97  Git:
    98  
    99  ```
   100  // force https source
   101  dependency {
   102  	source = "git::https://hashicorp.com/repo.git"
   103  }
   104  
   105  // force ssh source
   106  dependency {
   107  	source = "git::ssh://git@github.com/owner/repo.git"
   108  }
   109  ```
   110  
   111  URLs for Git repositories (of any protocol) support the following query
   112  parameters:
   113  
   114    * `ref` - The ref to checkout. This can be a branch, tag, commit, etc.
   115  
   116  An example of using these parameters is shown below:
   117  
   118  ```
   119  dependency {
   120  	source = "git::https://hashicorp.com/repo.git?ref=master"
   121  }
   122  ```
   123  
   124  ## Generic Mercurial Repository
   125  
   126  Generic Mercurial repositories are supported. The value of `source` in this
   127  case should be a complete Mercurial-compatible URL. Using Mercurial requires that
   128  Mercurial is installed on your system. Example:
   129  
   130  ```
   131  dependency {
   132  	source = "hg::http://hashicorp.com/module.hg"
   133  }
   134  ```
   135  
   136  In the case of above, we used the forced source type syntax documented below.
   137  Mercurial repositories require this.
   138  
   139  URLs for Mercurial repositories (of any protocol) support the following query
   140  parameters:
   141  
   142    * `rev` - The rev to checkout. This can be a branch, tag, commit, etc.
   143  
   144  ## HTTP URLs
   145  
   146  Any HTTP endpoint can serve up Otto Appfiles. For HTTP URLs (SSL is
   147  supported, as well), Otto will make a GET request to the given URL.
   148  An additional GET parameter `otto-get=1` will be appended, allowing
   149  you to optionally render the page differently when Otto is requesting it.
   150  
   151  Otto then looks for the resulting module URL in the following order.
   152  
   153  First, if a header `X-Otto-Get` is present, then it should contain
   154  the source URL of the actual module. This will be used.
   155  
   156  If the header isn't present, Otto will look for a `<meta>` tag
   157  with the name of "otto-get". The value will be used as the source
   158  URL.
   159  
   160  ## Forced Source Type
   161  
   162  In a couple places above, we've referenced "forced source type." Forced
   163  source type is a syntax added to URLs that allow you to force a specific
   164  method for download/updating the module. It is used to disambiguate URLs.
   165  
   166  For example, the source "http://hashicorp.com/foo.git" could just as
   167  easily be a plain HTTP URL as it might be a Git repository speaking the
   168  HTTP protocol. The forced source type syntax is used to force Otto
   169  one way or the other.
   170  
   171  Example:
   172  
   173  ```
   174  module "consul" {
   175  	source = "git::http://hashicorp.com/foo.git"
   176  }
   177  ```
   178  
   179  The above will force Otto to get the module using Git, despite it
   180  being an HTTP URL.
   181  
   182  If a forced source type isn't specified, Otto will match the exact
   183  protocol if it supports it. It will not try multiple methods. In the case
   184  above, it would've used the HTTP method.
   185  
   186  ## Double-Slash to Split the Root and Subdirectory
   187  
   188  Some Appfiles reference files that are above the directory where the
   189  Appfile is. For example:
   190  
   191  ```
   192  application {
   193      dependency { source = "../parent" }
   194  }
   195  ```
   196  
   197  If you depended on an application with an Appfile that looks like the
   198  above, it would need access to the parent folder. Let's pretend that this
   199  Appfile is at the URL local path "/foo/bar".
   200  
   201  If you specify the dependency like below, then Otto will be unable to get
   202  the next level dependency "../parent" because it won't exist since Otto
   203  only copies the root of the path given.
   204  
   205  ```
   206  application {
   207      dependency { source = "/foo/bar" }
   208  }
   209  ```
   210  
   211  A double-slash can be used to separate the root of the dependency
   212  with the directory where the Appfile is. If this is used, then the entire
   213  root is copied, and the Appfile in the sub-directory is loaded.
   214  The example below allows this dependency to work:
   215  
   216  ```
   217  application {
   218      dependency { source = "/foo//bar" }
   219  }
   220  ```