Document caveats around ps:rebuild and tags/tar deployed applications. Closes #2374

The tags and tar plugins do not necessarily build from source, and running `ps:rebuild` can have some unexpected output in certain cases. Rather than try to handle that complexity - it's a lot - documenting the edge cases is the most appropriate way forward.

docs/deployment/methods/images.md

@@ -11,6 +11,13 @@ tags:destroy <app> <tag>                       # Remove app image tag
 
 The Dokku tags plugin allows you to add docker image tags to the currently deployed app image for versioning and subsequent deployment.
 
+> When triggering `dokku ps:rebuild APP` on an application deployed via the `tags` plugin, the following may occur:
+>
+> - Applications previously deployed via another method (`git`/`tar`): The application may revert to a state before the latest custom image tag was deployed.
+> - Applications that were only ever deployed via the `tags` plugin: No action will be taken against your application.
+>
+> Please use the `tags:deploy` command when redeploying an application deployed via docker image.
+
 ## Usage
 
 ### Listing tags for an application

docs/deployment/methods/tar.md

@@ -1,4 +1,4 @@
-# Tarfile Deployment
+# Tarball Deployment
 
 > New as of 0.4.0
 
@@ -7,6 +7,13 @@ tar:from <app> <url>                           # Loads an app tarball from url
 tar:in <app>                                   # Reads an tarball containing the app from stdin
 ```
 
+> When triggering `dokku ps:rebuild APP` on an application deployed via the `tar` plugin, the following may occur:
+>
+> - Applications previously deployed via another method (`git`): The application may revert to a state before the latest custom image tag was deployed.
+> - Applications that were only ever deployed via the `tar` plugin: The application will be properly rebuilt.
+>
+> Please use the appropriate`tar` command when redeploying an application deployed via tarball.
+
 ## Usage
 
 ### Deploying from a tarball

docs/deployment/process-management.md

@@ -4,8 +4,8 @@
 
 ```
 ps <app>                                       # List processes running in app container(s)
-ps:rebuildall                                  # Rebuild all apps
+ps:rebuildall                                  # Rebuild all apps from source
-ps:rebuild <app>                               # Rebuild an app
+ps:rebuild <app>                               # Rebuild an app from source
 ps:restartall                                  # Restart all deployed app containers
 ps:restart <app>                               # Restart app container(s)
 ps:scale <app> <proc>=<count> [<proc>=<count>] # Set how many processes of a given process to run
@@ -43,6 +43,11 @@ You may also rebuild all applications at once, which is useful when enabling/dis
 dokku ps:rebuildall
 ```
 
+> The `ps:rebuild` and `ps:rebuildall` commands only work for applications for which there is a source, and thus
+> will only always work deterministically for git-deployed application. Please see
+> the [images documentation](/dokku/deployment/methods/images/) and [tar documentation](/dokku/deployment/methods/tar/)
+> in for more information concerning rebuilding those applications.
+
 ### Restarting applications
 
 Applications can be restarted, which is functionally identical to calling the `release_and_deploy` function on an application. Please not that any linked containers *must* be started before the application in order to have a successful boot.

docs/getting-started/upgrading.md

@@ -27,9 +27,19 @@ sudo apt-get update
 dokku apps
 dokku ps:stop <app> # repeat to shut down each running app
 sudo apt-get install -qq -y dokku herokuish
-dokku ps:rebuildall # restart all applications
+dokku ps:rebuildall # rebuilds all applications
 ```
 
+> If you have any applications deployed via the `tags` or `tar` commands, do not run the `ps:rebuildall` command,
+> and instead trigger `ps:rebuild` manually for each `git`-deployed application:
+>
+> ```
+> dokku ps:rebuild APP
+> ```
+>
+> Please see the [images documentation](/dokku/deployment/methods/images/) and [tar documentation](/dokku/deployment/methods/tar/)
+> for instructions on rebuilding applications deployed by those plugins.
+
 ### Upgrade From Source
 
 If you installed Dokku from source (less common), upgrade with:
@@ -45,7 +55,7 @@ sudo DOKKU_BRANCH=master make install
 
 # upgrade to debian package-based installation
 sudo make install
-dokku ps:rebuildall # restart all applications
+dokku ps:rebuildall # rebuilds all applications
 ```
 
 To upgrade herokuish from source, upgrade with:

plugins/ps/commands

@@ -11,8 +11,8 @@ case "$1" in
     ps:scale <app> <proc>=<count> [<proc>=<count>...], Get/Set how many instances of a given process to run
     ps:start <app>, Start app container(s)
     ps:stop <app>, Stop app container(s)
-    ps:rebuild <app>, Rebuild an app
+    ps:rebuild <app>, Rebuild an app from source
-    ps:rebuildall, Rebuild all apps
+    ps:rebuildall, Rebuild all apps from source
     ps:restart <app>, Restart app container(s)
     ps:restartall, Restart all deployed app containers
     ps:restore, Start previously running apps e.g. after reboot

plugins/ps/subcommands/rebuild

@@ -4,7 +4,7 @@ source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
 source "$PLUGIN_AVAILABLE_PATH/ps/functions"
 
 ps_rebuild_cmd() {
-  declare desc="rebuilds app via command line"
+  declare desc="rebuilds an app from source"
   local cmd="ps:rebuild"
   [[ -z $2 ]] && dokku_log_fail "Please specify an app to run the command on"
   ps_rebuild "$2"

plugins/ps/subcommands/rebuildall

@@ -4,7 +4,7 @@ source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
 source "$PLUGIN_AVAILABLE_PATH/ps/functions"
 
 ps_rebuildall_cmd() {
-  declare desc="rebuilds all deployed apps via command line"
+  declare desc="rebuilds all apps from source"
   local cmd="ps:rebuildall"
   for app in $(dokku_apps); do
     (is_deployed "$app") && ps_rebuild "$app"