Github user rdowner commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/178#discussion_r115250946
--- 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`
|
+
+Additional substitutions can be given per-entity by setting the
`template.substitutions` key. For example,
+to include the address of an entity called db:
+
+ brooklyn.config
+ template.substitutions:
+ databaseAddress:
$brooklyn:entity("db").attributeWhenReady("host.address")
+
+The value can be referenced in a template with `${databaseAddress}`.
+
+
+### Example
+
+ files.preinstall:
+ # Reference a fixed resource
+ classpath://com/acme/installAcme.ps1: C:\\acme\installAcme.ps1
+ # Inject the source from a config key
+ $brooklyn:config("acme.conf"): C:\\acme\acme.conf
--- End diff --
I'd also like to see described how to install files to INSTALL_DIR and/or
RUN_DIR - do I just omit the path component?
---
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 [email protected] or file a JIRA ticket
with INFRA.
---
