Bug 867063

Summary: JBoss app's README can cause some confusion. Some user feedback provided
Product: OKD Reporter: Nam Duong <nduong>
Component: ContainersAssignee: Bill DeCoste <wdecoste>
Status: CLOSED CURRENTRELEASE QA Contact: libra bugs <libra-bugs>
Severity: low Docs Contact:
Priority: medium    
Version: 2.xCC: jhou, jofernan
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2012-12-19 19:27:19 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Nam Duong 2012-10-16 16:32:37 UTC
Description of problem:
See forum thread:  https://openshift.redhat.com/community/forums/openshift/unclear-instructions-on-how-to-deploy-a-war-directly

Here is some feedback:
1) "1. git rm deployments/example.war.dodeploy deployments/example.war": The scanner will quickly detect the .dodeploy marker file and replace it with a .deployed marker file ==> it's the .deployed marker file that you'll want to delete.
2) I'd merge the explanations of 2a and 2d: "To deploy a prebuilt WAR or to replace the contents of an already deployed WAR:"
3) when I rsync my prebuilt WAR (into an empty "deployments" folder) I don't need to restart OpenShift, it'll just deploy within seconds. No .dodeploy needed either.
4) As you can SSH onto the machine, I think that adding an "scp" for uploading your WAR tutorial might be a good addition.



Entire thread:
---
Hi @AndrewBourgeois;

I can see how the README can be a bit complex but necessary. The way you want to read it is 2a or 2b or 2c or 2d... depending on the scenario you're in when you don't want to use maven to build your war.

To address your questions directly:
> Questions:
> 1) Is this correct?
Not quite. You will want to do:
1) 'git rm -r src/ pom.xml'
2) copy your zipped war to the deployments dir and do a git push
3) rhc app tidy -a appname

Different variations of 2) is as follows in the doc as 2a or 2b or 2c, etc...

> 2) Will this redeploy my app with a "clean slate" (meaning it won't just try to override new and updated files, but remove the complete directory and start fresh)?
Depends. Let's say you're just doing 2a) the first time. Subsequent times will be 2d). Fairly simple case and the recommended one, but of course you have a lot of flexibility in how you want to deploy your pre-built war.

> 3) why does the rsync method restart the app instead of using the .dodeploy marker file?
When you do a git push, it automatically calls app stop/start hooks. Then, if JBoss sees a zipped war, it will deploy it. If you're doing an rsync, you are bypassing git and will need to manually call app stop/start (e.g., restart). If you deploy an exploded war, you have to trick JBoss into thinking it deployed a zipped war, hence the .dodeploy file.

> 4) "it takes up the size of the war file away from your OpenShift file system quota". Does it add up (git will need to keep track of the changes between every WAR) or is it only the current WAR's size that counts towards that quota?
This is why you're running app tidy, so as to minimize the buildup over time. Otherwise, yes, it will add up.

> 5) "You would have to do this after each git push". Why do I even git push when I upload the WAR using rsync?
It's either/or, not both. So if you choose to copy the war to your local git repo's deployments directory and do a git push, you don't need to rsync. Likewise, if you do rsync + app restart, you don't need to copy to your local git repo and do a git push.

Please let us know if any of the paths are misrepresented as well as how we can improve our documentation.
---

The README (that's generated at the root of your project when you create an app) telles me that I can deploy WAR files directly instead of (git) pushing the sources that'll be built by OpenShift.

As far as I can understand, I need to:

1) 'git rm -r src/ pom.xml' as OpenShift will no longer be building my project but instead just deploy the WAR I give it.

and then (based on how I want to upload my WAR)...
[git]
2a) git push my WAR into the "deployments" directory.
2b) git push a marker file using the format: appname.war.dodeploy


[rsync]
2a) rsync -avz localdir/deployments/ app_uuid.com:~/appname/repo/deployments/
2b) rhc app restart -a appname

to finish off with...
3) rhc app tidy -a appname

Questions:
1) Is this correct?
2) Will this redeploy my app with a "clean slate" (meaning it won't just try to override new and updated files, but remove the complete directory and start fresh)?
3) why does the rsync method restart the app instead of using the .dodeploy marker file?

The following questions are related to the following excerpt from the README: "WARNING: If you go with option 2) there are a couple issues to keep in mind with both prebuilt and exploded wars. With exploded wars the main issue is with committing binaries (class and jar files) can make merge conflicts tedious. With prebuilt wars the main issue is each time you modify the war and git push, it takes up the size of the war file away from your OpenShift file system quota. One alternative to this (other then using Maven from option 1) is to use rsync to push your war into the deployments folder. You would have to do this after each git push followed by 'rhc app restart -a appname'. Example:

rsync -avz localdir/deployments/ app_uuid.com:~/appname/repo/deployments/

Note: You can get the information in the uri above from running 'rhc domain show'

If you have already committed large files to your git repo, you rewrite or reset the history of those files in git to an earlier point in time and then 'git push --force' to apply those changes on the remote OpenShift server. A git gc on the remote OpenShift repo can be forced with (Note: tidy also does other cleanup including clearing log files and tmp dirs):

rhc app tidy -a appname"

4) "it takes up the size of the war file away from your OpenShift file system quota". Does it add up (git will need to keep track of the changes between every WAR) or is it only the current WAR's size that counts towards that quota?
5) "You would have to do this after each git push". Why do I even git push when I upload the WAR using rsync?


---

Comment 1 Bill DeCoste 2012-11-06 18:24:41 UTC
READMEs updated

Comment 3 Bill DeCoste 2012-11-07 13:47:11 UTC
Added line in template README describing and pointing to the markers README

https://github.com/openshift/origin-server/pull/841

Comment 4 Jianwei Hou 2012-11-08 08:38:44 UTC
(In reply to comment #3)
> Added line in template README describing and pointing to the markers README
> 
> https://github.com/openshift/origin-server/pull/841

Sorry I didn't make it clear, I mean the contents for deployment markers are removed in current fix.
I think they are helpful, so I want to make sure whether they are removed intentionally
Thanks!

=========================removed contents==============================

The filesystem deployment scanner in AS 7 and later works differently from 
previous JBoss AS releases. The scanner will no longer attempt to directly 
monitor the deployment content and decide if or when the end user wishes 
the content to be deployed. Instead, the scanner relies on a system of marker 
files, with the user's addition or removal of a marker file serving as a sort
of command telling the scanner to deploy, undeploy or redeploy content.

The marker files always have the same name as the deployment content to which
they relate, but with an additional file suffix appended. For example, the 
marker file to indicate the example.war should be deployed is named 
example.war.dodeploy. Different marker file suffixes have different meanings.

The relevant marker file types are:

.dodeploy     -- Placed by the user to indicate that the given content should 
                 be deployed into the runtime (or redeployed if already 
                 deployed in the runtime.)

.deploying    -- Placed by the deployment scanner service to indicate that it 
                 has noticed a .dodeploy file and is in the process of 
                 deploying the content. This marker file will be deleted when 
                 the deployment process completes.
              
.deployed     -- Placed by the deployment scanner service to indicate that the 
                 given content has been deployed into the runtime. If an end 
                 user deletes this file, the content will be undeployed.
               
.faileddeploy -- Placed by the deployment scanner service to indicate that the 
                 given content failed to deploy into the runtime. The content 
                 of the file will include some information about the cause of 
                 the failure.

.undeploying  -- Placed by the deployment scanner service to indicate that it 
                 has noticed a .deployed file has been deleted and the 
                 content is being undeployed. This marker file will be deleted 
                 when the undeployment process completes.
              
.undeployed   -- Placed by the deployment scanner service to indicate that the 
                 given content has been undeployed from the runtime. If an end 
                 user deletes this file, it has no impact.

Comment 5 Bill DeCoste 2012-11-08 13:23:47 UTC
Yes, that content was removed intentionally. Users should NOT be using those files. This was the cause of half the confusion from the user. All of the .* files are handled behind the scenes by us and can cause problems if directly used by the user.

Comment 6 Jianwei Hou 2012-11-09 03:13:24 UTC
Verified on devenv_2445

Steps:
1. Create a jbossas/jbosseap/jbossews applications
2. Check README in app root directory

READMEs have been updated