Red Hat Bugzilla – Bug 867063
JBoss app's README can cause some confusion. Some user feedback provided
Last modified: 2015-05-14 19:00:49 EDT
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.
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:
> 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)...
2a) git push my WAR into the "deployments" directory.
2b) git push a marker file using the format: appname.war.dodeploy
2a) rsync -avz localdir/deployments/ email@example.com:~/appname/repo/deployments/
2b) rhc app restart -a appname
to finish off with...
3) rhc app tidy -a appname
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/ firstname.lastname@example.org:~/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?
Added line in template README describing and pointing to the markers README
(In reply to comment #3)
> Added line in template README describing and pointing to the markers README
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
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
.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.
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.
Verified on devenv_2445
1. Create a jbossas/jbosseap/jbossews applications
2. Check README in app root directory
READMEs have been updated