= WebWorks Ftp Deployment =

[[attachment:WebWorks.Deploy.Ftp.zip|Download]] (updated 12/7/2010: 1:45pm CST: Make console log resizable.  Add uri logging)

One experimental feature that we have been working on is deployment via FTP and FTPS.  The purpose of this article is the following:

 * Introduce FTP deployment for the ePublisher Platform.
 * Document the program.
 * Describe the process of implementing it in your current ePublisher workflow

== Introduction ==

The ability to deploy files using FTP is coming to ePublisher.   In order for FTP to be viable in the modern world, it must be secure.  The !WebWorks FTP deployment application supports the explicit (FTPES) protocol.  Also, the !WebWorks Ftp Deployment client supports a graphical console which indicates upload progress and messages for a given deployment.

== Documentation ==

The !WebWorks Ftp Deployment program's functionality includes four basic parts, all of which are exposed in the configuration dialog.  The configuration dialog is displayed when a user creates a new FTP deployment location.  [[#figure1|Figure 1]] shows the FTP configuration dialog.

<<Anchor(figure1)>>{{attachment:figure1.png}}<<BR>>
'''Figure 1.''' Ftp Deployment Configuration Dialog

=== Ftp Location ===

The '''Ftp Location''' field should be a valid URI to the FTP server.  The URI may be relative or absolute. If the URI is of the form ''' `ftp://myhost.net//path` ''', then the URI is absolute, and the current directory is /path.  If, however, the URI is of the form ''' `ftp://myhost.net/path` ''', the deployment client logs into the FTP server first, then the current directory is set to {{{UserLoginDirectory>/path}}}.  Additionally, the protocol may be set to ftp or ftps, depending on whether the server connection supports SSL encryption.

'''Table 1.''' Map from example server URI to server paths

|| ''' Example Ftp Location Uri ''' || ''' Example Server Path ''' ||
|| ''' `ftps://myhost.net//var/www/mydocs` ''' || /var/www/mydocs ||
|| ''' `ftp://myhost.net/public_html/mydocs` ''' || /home/johndoe/public_html/mydocs ||

=== Overwrite Strategy ===

The overwrite strategy allows you to specify whether the deployment should overwrite any existing copies of the files on the server, or only those files which have a different file size.  If a user is frequently re-generating output, this option can be useful for speeding up the deployment.

{{attachment:figure2.png}}<<BR>>
<<Anchor(figure2)>>'''Figure 2.''' Overwrite Strategy

=== Exclude single group name ===

When selected, this option will prevent the deployment program from creating a directory with the project's Group name, if the project that is being deployed only has a single group.

=== User name and password ===

As the group panel name indicates, this section is for specifying authentication information.

== Integrating WebWorks Ftp Deployment ==

Integrating !WebWorks Ftp Deployment is currently a two-step process.

 * Installing the deployment program in the proper location
 * Adding the deployment program as a Format override

=== Installation ===

To install the !WebWorks Ftp Deployment program, [[attachment:WebWorks.Deploy.Ftp.zip|download the zip file]] from the wiki page.  Next, extract !WebWorks.Deploy.Ftp.exe and !WebWorks.Deploy.Ftp.exe.config and place them in the following location:

{{{
  {ePublisher-installation-directory}\{latest-version}\Helpers\ftp
}}}

=== Format Override ===

Integrating the WebWorks Ftp Deployment program into existing ePublisher projects requires an override to each format's format.wwfmt file.  To do this:

 1. Copy the {{{format.wwfmt}}} file for the base format of the target you want to deploy using the WebWorks Ftp Deployment program.  See [[#table2|Table 2]] for example mappings of target to base format files.

 <<Anchor(table2)>>'''Table 2.''' Example Target to Base format file location mapping

 || '''Example Target Name''' || '''Base Format''' || '''Base Format File Location''' ||
 || Online || Dynamic HTML || {{{ {ePublisher-installation-directory}\{latest-version}\Formats\Dynamic HTML\format.wwfmt }}} ||
 || Help || WebWorks Help 5.0 || {{{ {ePublisher-installation-directory}\{latest-version}\Formats\WebWorks Help 5.0\format.wwfmt }}} ||
 || Eclipse || Eclipse Help || {{{ {ePublisher-installation-directory}\{latest-version}\Formats\Eclipse Help\format.wwfmt }}} ||

 2. Paste the format.wwfmt file in the Format Override (View > Format Override Directory) directory for the Target you want to deploy.

 {{attachment:figure3.png}}<<BR>>
 '''Figure 3.''' Open Format Override Directory

 3. Open the newly copied file in a text editor and add the following lines to the Capabilities section of the Format.

 {{{
  <Capabilities>
   ...
   <Capability name="deployment-action-id" value="ftp" />
   <Capability name="deployment-action-uri" value="wwhelper:ftp/WebWorks.Deploy.Ftp.exe" />
   <Capability name="deployment-info-type" value="deploy:true" />
   <Capability name="deployment-features" value="" />
  </Capabilities>
 }}}

 4. Close and reopen the project to pick up the changes to the format.
 5. Configure a new FTP deployment location.

 || '''''BE AWARE!''''' || There is an issue which prevents the label for the newly added deployment client from showing up in the User Interface.  When a user clicks Target > Target Settings… > Add deploy target > Add, an option with no label appears, as pictured in [[#figure4|Figure 4]].  Click this blank entry to open the FTP Deployment Configuration dialog. ||

 <<Anchor(figure4)>>{{attachment:figure4.png}}<<BR>>
 '''Figure 4.''' FTP deploy target option with empty label