Github user rdowner commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115251215
--- Diff: guide/blueprints/config-files.md ---
@@ -0,0 +1,78 @@
+---
+title: Uploading Script and Configuration Files
+layout: website-normal
+toc: ../guide_toc.json
+categories: [use, guide, defining-applications]
+---
+
+Blueprints often require that parameterized scripts and configuration
files are available to be copied to the
+target VM. These must be URLs resolvable from the Brooklyn instance, or on
the Brooklyn classpath. One simple way
+to achieve this is to compile the support files into a .jar, which is then
added to Brooklyn's 'dropins' folder.
+Alternatively, an OSGi bundle can be used, referenced from the catalog
item.
+
+There are two types of file that can be uploaded: plain files and
templated files. A plain
+file is uploaded unmodified. A templated file is interpreted as a
[FreeMarker](http://freemarker.org)
+template. This supports a powerful set of substitutions. In brief,
anything (unescaped) of the form
+`${name}` will be substituted, in this case looking up "name" for the
value to use.
+
+
+### Using files
+
+Files can be referenced as URLs. This includes support for things like
`classpath://mypath/myfile.bat`.
+This looks for the given (fully qualified) resource on the Brooklyn
classpath.
+
+The destination for the file upload is specified in the entity's
configuration. Note that the backslash character
+(\\) must be escaped when using Windows. For example:
`C:\\install7zip.ps1`.
+
+Files can be uploaded at several stages of an entity's lifecycle:
+
+| Config key | Copied before lifecycle phase | Templated |
+|------------------------|-------------------------------|-----------|
+| `files.preinstall` | Pre-install | â |
+| `files.install` | Install | â |
+| `files.customize` | Customize | â |
+| `files.runtime` | Launch | â |
+| `templates.preinstall` | Pre-install | â |
+| `templates.install` | Install | â |
+| `templates.customize` | Customize | â |
+| `templates.runtime` | Launch | â |
+
+
+### Template substitutions
+
+Templated files (be they configuration files or scripts) gives a powerful
way to inject dependent
+configuration when installing an entity (e.g. for customising the install,
or for referencing the
+connection details of another entity). Available substitutions are:
+
+| Substitution | Effect
|
+|---------------------------|--------------------------------------------------------------------|
+| `${config['key']}` | Equivalent to `entity.config().get(key)`
|
+| `${attribute['key']}` | Equivalent to `entity.sensors().get(key)`
|
+| `${mgmt['key']}` | Loads the value for `key` from the
management context's properties |
+| `${entity.foo}` | FreeMarker calls `getFoo` on the entity
|
+| `${driver.foo}` | FreeMarker calls `getFoo` on the entity's
[driver](http://brooklyn.apache.org/v/latest/java/entity.html#things-to-know) |
+| `${location.foo}` | FreeMarker calls `getFoo` on the entity's
location |
+| `${javaSysProps.foo.bar}` | Loads the system property named `foo.bar`
|
--- End diff --
How do I insert a literal `${ABC}`? (Important in shell scripts, for
example)
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
