howto-forrestbot-scp.html - forrest - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <head>
 <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <meta content="Apache Forrest" name="Generator">
 <meta name="Forrest-version" content="0.9-dev">
 <meta name="Forrest-skin-name" content="pelt">
 <title>How to deploy documentation with the Forrestbot "scp" workstage</title>
 <link type="text/css" href="skin/basic.css" rel="stylesheet">
 <link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
 <link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
 <link type="text/css" href="skin/profile.css" rel="stylesheet">
 <script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
 <link rel="shortcut icon" href="favicon.ico">
 </head>
 <body onload="init()">
 <script type="text/javascript">ndeSetTextSize();</script>
 <div id="top">
 <!--+
     |breadtrail
     +-->
 <div class="breadtrail">
 <a href="http://www.apache.org/">Apache Software Foundation</a> &gt; <a href="http://forrest.apache.org/">Apache Forrest</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
 </div>
 <!--+
     |header
     +-->
 <div class="header">
 <!--+
     |start group logo
     +-->
 <div class="grouplogo">
 <a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="images/apache-forrest.png" title="The Apache Software Foundation"></a>
 </div>
 <!--+
     |end group logo
     +-->
 <!--+
     |start Project Logo
     +-->
 <div class="projectlogo">
 <a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="images/project-logo.gif" title="Apache Forrest"></a>
 </div>
 <!--+
     |end Project Logo
     +-->
 <!--+
     |start Search
     +-->
 <div class="searchbox">
 <form action="http://www.google.com/search" method="get" class="roundtopsmall">
 <input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
                     <input name="Search" value="Search" type="submit">
 </form>
 </div>
 <!--+
     |end search
     +-->
 <!--+
     |start Tabs
     +-->
 <ul id="tabs">
 <li>
 <a class="unselected" href="index.html">Welcome</a>
 </li>
 <li class="current">
 <a class="selected" href="contrib.html">Developers</a>
 </li>
 <li>
 <a class="unselected" href="versions/index.html">Versioned Docs</a>
 </li>
 <li>
 <a class="unselected" href="pluginDocs/index.html">Plugins</a>
 </li>
 <li>
 <a class="unselected" href="tools/index.html">Tools</a>
 </li>
 </ul>
 <!--+
     |end Tabs
     +-->
 </div>
 </div>
 <div id="main">
 <div id="publishedStrip">
 <!--+
     |start Subtabs
     +-->
 <div id="level2tabs"></div>
 <!--+
     |end Endtabs
     +-->
 <script type="text/javascript"><!--
 document.write("Last Published: " + document.lastModified);
 //  --></script>
 </div>
 <!--+
     |breadtrail
     +-->
 <div class="breadtrail">

              &nbsp;
            </div>
 <!--+
     |start Menu, mainarea
     +-->
 <!--+
     |start Menu
     +-->
 <div id="menu">
 <div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
 <div id="menu_1.1" class="menuitemgroup">
 <div class="menuitem">
 <a href="contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
 </div>
 <div class="menuitem">
 <a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
 </div>
 <div class="menuitem">
 <a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
 </div>
 <div class="menuitem">
 <a href="forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
 </div>
 <div class="menuitem">
 <a href="events.html" title="List of upcoming related conferences and meetings">Events</a>
 </div>
 <div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
 <div id="menu_1.1.6" class="menuitemgroup">
 <div class="menuitem">
 <a href="guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
 </div>
 <div class="menuitem">
 <a href="committed.html" title="Notes about contribution">Being committed</a>
 </div>
 <div class="menuitem">
 <a href="tasks.html" title="Tasks to keep the project flowing">Project tasks</a>
 </div>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
 <div id="menu_1.2" class="menuitemgroup">
 <div class="menuitem">
 <a href="asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
 </div>
 <div class="menuitem">
 <a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
 </div>
 <div class="menuitem">
 <a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
 </div>
 <div class="menuitem">
 <a href="svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
 </div>
 <div class="menuitem">
 <a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
 </div>
 <div class="menuitem">
 <a href="gump.html">Gump integration</a>
 </div>
 <div onclick="SwitchMenu('menu_1.2.7', 'skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
 <div id="menu_1.2.7" class="menuitemgroup">
 <div class="menuitem">
 <a href="plan/index.html">Overview</a>
 </div>
 <div class="menuitem">
 <a href="plan/internal-xhtml.html">Internal XHTML</a>
 </div>
 </div>
 <div class="menuitem">
 <a href="todo.html">Todo</a>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Best Practices and Procedures</div>
 <div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
 <div class="menuitem">
 <a href="howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
 </div>
 <div class="menuitem">
 <a href="howto-forrestbot-svn.html" title="Publish documentation with Forrestbot svn workstage">Forrestbot svn</a>
 </div>
 <div class="menupage">
 <div class="menupagetitle">Forrestbot scp</div>
 </div>
 <div class="menuitem">
 <a href="subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
 </div>
 <div class="menuitem">
 <a href="documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
 </div>
 <div class="menuitem">
 <a href="howto-howto.html" title="Instructions for writing             a new howto-document">Write a How-to</a>
 </div>
 <div onclick="SwitchMenu('menu_1.3.7', 'skin/')" id="menu_1.3.7Title" class="menutitle">Committer notes</div>
 <div id="menu_1.3.7" class="menuitemgroup">
 <div class="menuitem">
 <a href="zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
 </div>
 <div class="menuitem">
 <a href="procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
 </div>
 <div class="menuitem">
 <a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest             Website">Publishing Forrest documentation</a>
 </div>
 </div>
 </div>
 <div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
 <div id="menu_1.4" class="menuitemgroup">
 <div class="menuitem">
 <a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
 </div>
 </div>
 <div id="credit"></div>
 <div id="roundbottom">
 <img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
 <!--+
   |alternative credits
   +-->
 <div id="credit2">
 <a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
 </div>
 </div>
 <!--+
     |end Menu
     +-->
 <!--+
     |start content
     +-->
 <div id="content">
 <div class="trail">Font size:
 	          &nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
 	          &nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
 	          &nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
 </div>
 <h1>How to deploy documentation with the Forrestbot "scp" workstage</h1>
 <div id="front-matter">
 <div class="abstract">
       This How-To describes the building and deployment of a documentation set
       with the help of the forrestbot "scp" workstage.
     </div>
 <div id="minitoc-area">
 <ul class="minitoc">
 <li>
 <a href="#Intended-Audience">Intended Audience</a>
 </li>
 <li>
 <a href="#Purpose">Purpose</a>
 </li>
 <li>
 <a href="#Prerequisites">Prerequisites</a>
 </li>
 <li>
 <a href="#Steps">Steps</a>
 <ul class="minitoc">
 <li>
 <a href="#introduction">Introduction</a>
 </li>
 <li>
 <a href="#settings">The deploy.scp.settings file</a>
 </li>
 <li>
 <a href="#buildfile">The Forrestbot buildfile</a>
 </li>
 <li>
 <a href="#checksums">The Cocoon "checksums" facility</a>
 </li>
 <li>
 <a href="#build">The "build" workstage</a>
 </li>
 <li>
 <a href="#deploy">The "deploy" workstage</a>
 </li>
 <li>
 <a href="#production">Moving the documents into production</a>
 </li>
 </ul>
 </li>
 <li>
 <a href="#Further-Reading">Further Reading</a>
 </li>
 </ul>
 </div>
 </div>
 <a name="Intended-Audience"></a>
 <h2 class="underlined_10">Intended Audience</h2>
 <div class="section">
 <p>
       Anyone who generates a static documentation set with Forrest will need
       to deploy the results, whether that be to a remote server or locally.
     </p>
 </div>
 <a name="Purpose"></a>
 <h2 class="underlined_10">Purpose</h2>
 <div class="section">
 <p>
       This howto will explain one method of using the Forrestbot, by way of the
       worked example for managing a company or private website, and using "Secure Copy (SCP)" to deploy to a remote webserver. The Forrestbot has a number of deployment methods. After you understand the principles then you will be able to apply that to whatever method is relevant.
     </p>
 <p>
       The secondary purpose is to explain to ASF committers how to manage
       project documentation, e.g. for an "Apache Labs" investigation.
     </p>
 <p>
       This howto also explains the use of the Apache Cocoon "checksums" facility
       to only process and deploy the changed files.
     </p>
 </div>
 <a name="Prerequisites"></a>
 <h2 class="underlined_10">Prerequisites</h2>
 <div class="section">
 <p>
       Refer to the <a href="tools/forrestbot.html">Forrestbot</a> documentation.
       It is not necessary to have thorough knowledge, but a basic understanding
       will help.
     </p>
 <p>
       An account on a server configured to use SSH access.
       e.g. <a href="http://apache.org/dev/new-committers-guide.html#ssh">ASF Guide for new committers</a>.
     </p>
 <p>
       Review the <a href="howto-forrestbot-svn.html">Forrestbot svn</a> howto documentation.
       That explains more generally how to use a Forrestbot.
     </p>
 <p>
       Therefore this "scp" howto can have minimal content.
     </p>
 </div>
 <a name="Steps"></a>
 <h2 class="underlined_10">Steps</h2>
 <div class="section">
 <a name="introduction"></a>
 <h3 class="underlined_5">Introduction</h3>
 <p>
       This Forrestbot uses the "getsrc.local" workstage to retrieve the sources from the local project workspace filesystem, i.e. from the top-level of your Forrest project site.
       </p>
 <p>
         This Forrestbot uses the "deploy.scp" workstage to copy the generated documents
         to the remote server. They go into a "stage" directory on the web server
         which has a .htaccess file to enable selected people to review before putting into production.
       </p>
 <a name="settings"></a>
 <h3 class="underlined_5">The deploy.scp.settings file</h3>
 <p>
         Create a file at the top-level of your project site named
         <span class="codefrag">deploy.scp.settings</span> to provide your ssh credentials.
         Set its file permissions so that only you can read it.
       </p>
 <pre class="code">&lt;?xml version="1.0"?&gt;
 &lt;project&gt;
   &lt;property name="deploy.scp.keyfile" value="/Users/me/.ssh/id_rsa"/&gt;
   &lt;property name="deploy.scp.passphrase" value="#$!*%#..."/&gt;
 &lt;/project&gt;</pre>
 <a name="buildfile"></a>
 <h3 class="underlined_5">The Forrestbot buildfile</h3>
 <p>
         The Forrestbot buildfile sets some properties and declares the workstages (i.e. Ant targets) that need to be carried out. Of course this is fully explained in the <a href="tools/forrestbot.html">Forrestbot</a>
         documentation.
       </p>
 <p>
         Create a file at the top-level of your project website named, e.g.
         <span class="codefrag">publish-stage.xml</span>

 </p>
 <pre class="code">&lt;?xml version="1.0"?&gt;
 &lt;project name="my-lab-docs" default="main"&gt;
   &lt;property name="getsrc.local.root-dir" location="."/&gt;
   &lt;target name="getsrc" depends="getsrc.clean-workdir, getsrc.local"/&gt;
   &lt;property name="deploy.scp.dest"
     value="username@apache.org:public_html/my-lab/stage"/&gt;
   &lt;import file="deploy.settings" optional="true"/&gt;
   &lt;target name="deploy" depends="deploy.scp"/&gt;
   &lt;property environment="env"/&gt;
   &lt;import file="${env.FORREST_HOME}/tools/forrestbot/core/forrestbot.xml"/&gt;
 &lt;/project&gt;</pre>
 <p>
         So it gets the sources relative to the current directory. Actually
         it reads the <span class="codefrag">forrest.properties</span> configuration file
         to find out where other stuff is located.
       </p>
 <p>
         It deploys the generated files directly to the user's "public_html" webspace
         into a "stage" sub-directory. Of course this "deploy.scp.dest" location
         could be a full pathname to an htdocs directory on the remove remote server.
       </p>
 <a name="checksums"></a>
 <h3 class="underlined_5">The Cocoon "checksums" facility</h3>
 <p>
         Instruct Forrest's Cocoon to use a "checksums" file to record the checksum
         of each document that it has processed. This enables subsequent builds to
         only process the documents that have changed. This means that each file's
         timestamp will only be touched if it is a changed document, which enables
         the Forrestbot deploy.scp workstage to only deploy the changed files.
       </p>
 <p>
         Follow the "<a href="docs_0_90/faq.html#checksums">checksums</a>" FAQ.
       </p>
 <a name="build"></a>
 <h3 class="underlined_5">The "build" workstage</h3>
 <p>
         After doing the usual process to edit source documents, review them with
         'forrest run', and ensure that things are in order with 'forrest validate'.
       </p>
 <p>
         Now do the build:
       </p>
 <pre class="code">forrest -f publish-stage.xml build</pre>
 <p>
         This does the normal site build to generate the complete set of static documents. Watch for errors.
       </p>
 <p>
         To review, see the built docs in <span class="codefrag">build/my-lab-docs</span> directory.
       </p>
 <a name="deploy"></a>
 <h3 class="underlined_5">The "deploy" workstage</h3>
 <p>
         When satisfied, then deploy the built docs:
       </p>
 <pre class="code">forrest -f publish-satge.xml deploy</pre>
 <p>
         The files that are being transferred to the remote server will now be listed.
       </p>
 <a name="production"></a>
 <h3 class="underlined_5">Moving the documents into production</h3>
 <p>
        The reason for deploying the documents into a "stage" directory was so that
        clients or collaborators could review it before going into production.
        So ask them to review your people.apache.org/my-lab/stage/ site.
        When satisfied, then:
       </p>
 <pre class="code">ssh people.apache.org
 cd publish_html/my-lab/stage
 cp -Rf * ..
 </pre>
 <p>
         That is it.
       </p>
 </div>
 <a name="Further-Reading"></a>
 <h2 class="underlined_10">Further Reading</h2>
 <div class="section">
 <ul>

 <li>
 <a href="howto-forrestbot-svn.html">How to deploy documentation with the Forrestbot "svn" workstage</a>
 </li>

 <li>
 <a href="tools/forrestbot.html">Forrestbot - automated building and deploying</a>
 </li>

 </ul>
 </div>
 </div>
 <!--+
     |end content
     +-->
 <div class="clearboth">&nbsp;</div>
 </div>
 <div id="footer">
 <!--+
     |start bottomstrip
     +-->
 <div class="lastmodified">
 <script type="text/javascript"><!--
 document.write("Last Published: " + document.lastModified);
 //  --></script>
 </div>
 <div class="copyright">
         Copyright &copy;
          2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
 <br>
     Apache, Apache Forrest, the Apache feather logo, and the Apache Forrest
     logos are trademarks of The Apache Software Foundation.
   </div>
 <!--+
     |end bottomstrip
     +-->
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<meta content="Apache Forrest" name="Generator">
	<meta name="Forrest-version" content="0.9-dev">
	<meta name="Forrest-skin-name" content="pelt">
	<title>How to deploy documentation with the Forrestbot "scp" workstage</title>
	<link type="text/css" href="skin/basic.css" rel="stylesheet">
	<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
	<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
	<link type="text/css" href="skin/profile.css" rel="stylesheet">
	<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
	<link rel="shortcut icon" href="favicon.ico">
	</head>
	<body onload="init()">
	<script type="text/javascript">ndeSetTextSize();</script>
	<div id="top">
	<!--+
	\|breadtrail
	+-->
	<div class="breadtrail">
	<a href="http://www.apache.org/">Apache Software Foundation</a> > <a href="http://forrest.apache.org/">Apache Forrest</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
	</div>
	<!--+
	\|header
	+-->
	<div class="header">
	<!--+
	\|start group logo
	+-->
	<div class="grouplogo">
	<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="images/apache-forrest.png" title="The Apache Software Foundation"></a>
	</div>
	<!--+
	\|end group logo
	+-->
	<!--+
	\|start Project Logo
	+-->
	<div class="projectlogo">
	<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="images/project-logo.gif" title="Apache Forrest"></a>
	</div>
	<!--+
	\|end Project Logo
	+-->
	<!--+
	\|start Search
	+-->
	<div class="searchbox">
	<form action="http://www.google.com/search" method="get" class="roundtopsmall">
	<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">
	<input name="Search" value="Search" type="submit">
	</form>
	</div>
	<!--+
	\|end search
	+-->
	<!--+
	\|start Tabs
	+-->
	<ul id="tabs">
	<li>
	<a class="unselected" href="index.html">Welcome</a>
	</li>
	<li class="current">
	<a class="selected" href="contrib.html">Developers</a>
	</li>
	<li>
	<a class="unselected" href="versions/index.html">Versioned Docs</a>
	</li>
	<li>
	<a class="unselected" href="pluginDocs/index.html">Plugins</a>
	</li>
	<li>
	<a class="unselected" href="tools/index.html">Tools</a>
	</li>
	</ul>
	<!--+
	\|end Tabs
	+-->
	</div>
	</div>
	<div id="main">
	<div id="publishedStrip">
	<!--+
	\|start Subtabs
	+-->
	<div id="level2tabs"></div>
	<!--+
	\|end Endtabs
	+-->
	<script type="text/javascript"><!--
	document.write("Last Published: " + document.lastModified);
	// --></script>
	</div>
	<!--+
	\|breadtrail
	+-->
	<div class="breadtrail">


	</div>
	<!--+
	\|start Menu, mainarea
	+-->
	<!--+
	\|start Menu
	+-->
	<div id="menu">
	<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
	<div id="menu_1.1" class="menuitemgroup">
	<div class="menuitem">
	<a href="contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
	</div>
	<div class="menuitem">
	<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
	</div>
	<div class="menuitem">
	<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
	</div>
	<div class="menuitem">
	<a href="forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
	</div>
	<div class="menuitem">
	<a href="events.html" title="List of upcoming related conferences and meetings">Events</a>
	</div>
	<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
	<div id="menu_1.1.6" class="menuitemgroup">
	<div class="menuitem">
	<a href="guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
	</div>
	<div class="menuitem">
	<a href="committed.html" title="Notes about contribution">Being committed</a>
	</div>
	<div class="menuitem">
	<a href="tasks.html" title="Tasks to keep the project flowing">Project tasks</a>
	</div>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
	<div id="menu_1.2" class="menuitemgroup">
	<div class="menuitem">
	<a href="asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
	</div>
	<div class="menuitem">
	<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
	</div>
	<div class="menuitem">
	<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
	</div>
	<div class="menuitem">
	<a href="svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
	</div>
	<div class="menuitem">
	<a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
	</div>
	<div class="menuitem">
	<a href="gump.html">Gump integration</a>
	</div>
	<div onclick="SwitchMenu('menu_1.2.7', 'skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
	<div id="menu_1.2.7" class="menuitemgroup">
	<div class="menuitem">
	<a href="plan/index.html">Overview</a>
	</div>
	<div class="menuitem">
	<a href="plan/internal-xhtml.html">Internal XHTML</a>
	</div>
	</div>
	<div class="menuitem">
	<a href="todo.html">Todo</a>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Best Practices and Procedures</div>
	<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
	<div class="menuitem">
	<a href="howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
	</div>
	<div class="menuitem">
	<a href="howto-forrestbot-svn.html" title="Publish documentation with Forrestbot svn workstage">Forrestbot svn</a>
	</div>
	<div class="menupage">
	<div class="menupagetitle">Forrestbot scp</div>
	</div>
	<div class="menuitem">
	<a href="subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
	</div>
	<div class="menuitem">
	<a href="documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
	</div>
	<div class="menuitem">
	<a href="howto-howto.html" title="Instructions for writing a new howto-document">Write a How-to</a>
	</div>
	<div onclick="SwitchMenu('menu_1.3.7', 'skin/')" id="menu_1.3.7Title" class="menutitle">Committer notes</div>
	<div id="menu_1.3.7" class="menuitemgroup">
	<div class="menuitem">
	<a href="zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
	</div>
	<div class="menuitem">
	<a href="procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
	</div>
	<div class="menuitem">
	<a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest Website">Publishing Forrest documentation</a>
	</div>
	</div>
	</div>
	<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
	<div id="menu_1.4" class="menuitemgroup">
	<div class="menuitem">
	<a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
	</div>
	</div>
	<div id="credit"></div>
	<div id="roundbottom">
	<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
	<!--+
	\|alternative credits
	+-->
	<div id="credit2">
	<a href="http://www.apache.org/events/current-event.html"><img border="0" title="ApacheCon" alt="ApacheCon - logo" src="http://www.apache.org/events/current-event-125x125.png" style="width: 125px;height: 125px;"></a>
	</div>
	</div>
	<!--+
	\|end Menu
	+-->
	<!--+
	\|start content
	+-->
	<div id="content">
	<div class="trail">Font size:
	<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
	<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
	<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
	</div>
	<h1>How to deploy documentation with the Forrestbot "scp" workstage</h1>
	<div id="front-matter">
	<div class="abstract">
	This How-To describes the building and deployment of a documentation set
	with the help of the forrestbot "scp" workstage.
	</div>
	<div id="minitoc-area">
	<ul class="minitoc">
	<li>
	<a href="#Intended-Audience">Intended Audience</a>
	</li>
	<li>
	<a href="#Purpose">Purpose</a>
	</li>
	<li>
	<a href="#Prerequisites">Prerequisites</a>
	</li>
	<li>
	<a href="#Steps">Steps</a>
	<ul class="minitoc">
	<li>
	<a href="#introduction">Introduction</a>
	</li>
	<li>
	<a href="#settings">The deploy.scp.settings file</a>
	</li>
	<li>
	<a href="#buildfile">The Forrestbot buildfile</a>
	</li>
	<li>
	<a href="#checksums">The Cocoon "checksums" facility</a>
	</li>
	<li>
	<a href="#build">The "build" workstage</a>
	</li>
	<li>
	<a href="#deploy">The "deploy" workstage</a>
	</li>
	<li>
	<a href="#production">Moving the documents into production</a>
	</li>
	</ul>
	</li>
	<li>
	<a href="#Further-Reading">Further Reading</a>
	</li>
	</ul>
	</div>
	</div>
	<a name="Intended-Audience"></a>
	<h2 class="underlined_10">Intended Audience</h2>
	<div class="section">
	<p>
	Anyone who generates a static documentation set with Forrest will need
	to deploy the results, whether that be to a remote server or locally.
	</p>
	</div>
	<a name="Purpose"></a>
	<h2 class="underlined_10">Purpose</h2>
	<div class="section">
	<p>
	This howto will explain one method of using the Forrestbot, by way of the
	worked example for managing a company or private website, and using "Secure Copy (SCP)" to deploy to a remote webserver. The Forrestbot has a number of deployment methods. After you understand the principles then you will be able to apply that to whatever method is relevant.
	</p>
	<p>
	The secondary purpose is to explain to ASF committers how to manage
	project documentation, e.g. for an "Apache Labs" investigation.
	</p>
	<p>
	This howto also explains the use of the Apache Cocoon "checksums" facility
	to only process and deploy the changed files.
	</p>
	</div>
	<a name="Prerequisites"></a>
	<h2 class="underlined_10">Prerequisites</h2>
	<div class="section">
	<p>
	Refer to the <a href="tools/forrestbot.html">Forrestbot</a> documentation.
	It is not necessary to have thorough knowledge, but a basic understanding
	will help.
	</p>
	<p>
	An account on a server configured to use SSH access.
	e.g. <a href="http://apache.org/dev/new-committers-guide.html#ssh">ASF Guide for new committers</a>.
	</p>
	<p>
	Review the <a href="howto-forrestbot-svn.html">Forrestbot svn</a> howto documentation.
	That explains more generally how to use a Forrestbot.
	</p>
	<p>
	Therefore this "scp" howto can have minimal content.
	</p>
	</div>
	<a name="Steps"></a>
	<h2 class="underlined_10">Steps</h2>
	<div class="section">
	<a name="introduction"></a>
	<h3 class="underlined_5">Introduction</h3>
	<p>
	This Forrestbot uses the "getsrc.local" workstage to retrieve the sources from the local project workspace filesystem, i.e. from the top-level of your Forrest project site.
	</p>
	<p>
	This Forrestbot uses the "deploy.scp" workstage to copy the generated documents
	to the remote server. They go into a "stage" directory on the web server
	which has a .htaccess file to enable selected people to review before putting into production.
	</p>
	<a name="settings"></a>
	<h3 class="underlined_5">The deploy.scp.settings file</h3>
	<p>
	Create a file at the top-level of your project site named
	<span class="codefrag">deploy.scp.settings</span> to provide your ssh credentials.
	Set its file permissions so that only you can read it.
	</p>
	<pre class="code"><?xml version="1.0"?>
	<project>
	<property name="deploy.scp.keyfile" value="/Users/me/.ssh/id_rsa"/>
	<property name="deploy.scp.passphrase" value="#$!*%#..."/>
	</project></pre>
	<a name="buildfile"></a>
	<h3 class="underlined_5">The Forrestbot buildfile</h3>
	<p>
	The Forrestbot buildfile sets some properties and declares the workstages (i.e. Ant targets) that need to be carried out. Of course this is fully explained in the <a href="tools/forrestbot.html">Forrestbot</a>
	documentation.
	</p>
	<p>
	Create a file at the top-level of your project website named, e.g.
	<span class="codefrag">publish-stage.xml</span>

	</p>
	<pre class="code"><?xml version="1.0"?>
	<project name="my-lab-docs" default="main">
	<property name="getsrc.local.root-dir" location="."/>
	<target name="getsrc" depends="getsrc.clean-workdir, getsrc.local"/>
	<property name="deploy.scp.dest"
	value="username@apache.org:public_html/my-lab/stage"/>
	<import file="deploy.settings" optional="true"/>
	<target name="deploy" depends="deploy.scp"/>
	<property environment="env"/>
	<import file="${env.FORREST_HOME}/tools/forrestbot/core/forrestbot.xml"/>
	</project></pre>
	<p>
	So it gets the sources relative to the current directory. Actually
	it reads the <span class="codefrag">forrest.properties</span> configuration file
	to find out where other stuff is located.
	</p>
	<p>
	It deploys the generated files directly to the user's "public_html" webspace
	into a "stage" sub-directory. Of course this "deploy.scp.dest" location
	could be a full pathname to an htdocs directory on the remove remote server.
	</p>
	<a name="checksums"></a>
	<h3 class="underlined_5">The Cocoon "checksums" facility</h3>
	<p>
	Instruct Forrest's Cocoon to use a "checksums" file to record the checksum
	of each document that it has processed. This enables subsequent builds to
	only process the documents that have changed. This means that each file's
	timestamp will only be touched if it is a changed document, which enables
	the Forrestbot deploy.scp workstage to only deploy the changed files.
	</p>
	<p>
	Follow the "<a href="docs_0_90/faq.html#checksums">checksums</a>" FAQ.
	</p>
	<a name="build"></a>
	<h3 class="underlined_5">The "build" workstage</h3>
	<p>
	After doing the usual process to edit source documents, review them with
	'forrest run', and ensure that things are in order with 'forrest validate'.
	</p>
	<p>
	Now do the build:
	</p>
	<pre class="code">forrest -f publish-stage.xml build</pre>
	<p>
	This does the normal site build to generate the complete set of static documents. Watch for errors.
	</p>
	<p>
	To review, see the built docs in <span class="codefrag">build/my-lab-docs</span> directory.
	</p>
	<a name="deploy"></a>
	<h3 class="underlined_5">The "deploy" workstage</h3>
	<p>
	When satisfied, then deploy the built docs:
	</p>
	<pre class="code">forrest -f publish-satge.xml deploy</pre>
	<p>
	The files that are being transferred to the remote server will now be listed.
	</p>
	<a name="production"></a>
	<h3 class="underlined_5">Moving the documents into production</h3>
	<p>
	The reason for deploying the documents into a "stage" directory was so that
	clients or collaborators could review it before going into production.
	So ask them to review your people.apache.org/my-lab/stage/ site.
	When satisfied, then:
	</p>
	<pre class="code">ssh people.apache.org
	cd publish_html/my-lab/stage
	cp -Rf * ..
	</pre>
	<p>
	That is it.
	</p>
	</div>
	<a name="Further-Reading"></a>
	<h2 class="underlined_10">Further Reading</h2>
	<div class="section">
	<ul>

	<li>
	<a href="howto-forrestbot-svn.html">How to deploy documentation with the Forrestbot "svn" workstage</a>
	</li>

	<li>
	<a href="tools/forrestbot.html">Forrestbot - automated building and deploying</a>
	</li>

	</ul>
	</div>
	</div>
	<!--+
	\|end content
	+-->
	<div class="clearboth"> </div>
	</div>
	<div id="footer">
	<!--+
	\|start bottomstrip
	+-->
	<div class="lastmodified">
	<script type="text/javascript"><!--
	document.write("Last Published: " + document.lastModified);
	// --></script>
	</div>
	<div class="copyright">
	Copyright ©
	2002-2011 <a href="http://www.apache.org/licenses/">The Apache Software Foundation. Licensed under Apache License 2.0</a>
	<br>
	Apache, Apache Forrest, the Apache feather logo, and the Apache Forrest
	logos are trademarks of The Apache Software Foundation.
	</div>
	<!--+
	\|end bottomstrip
	+-->
	</div>
	</body>
	</html>