docs: better timeout error

cli/app/rollback.go

@@ -163,7 +163,7 @@ recipes.
 			}
 		}
 
-		if err := stack.RunDeploy(cl, deployOpts, compose); err != nil {
+		if err := stack.RunDeploy(cl, deployOpts, compose, app.Type); err != nil {
 			logrus.Fatal(err)
 		}
 

cli/app/upgrade.go

@@ -164,7 +164,7 @@ recipes.
 			logrus.Fatal(err)
 		}
 
-		if err := stack.RunDeploy(cl, deployOpts, compose); err != nil {
+		if err := stack.RunDeploy(cl, deployOpts, compose, app.Type); err != nil {
 			logrus.Fatal(err)
 		}
 

cli/internal/deploy.go

@@ -126,7 +126,7 @@ func DeployAction(c *cli.Context) error {
 		logrus.Fatal(err)
 	}
 
-	if err := stack.RunDeploy(cl, deployOpts, compose); err != nil {
+	if err := stack.RunDeploy(cl, deployOpts, compose, app.Env["TYPE"]); err != nil {
 		logrus.Fatal(err)
 	}
 

pkg/upstream/stack/stack.go

@@ -158,7 +158,7 @@ func pruneServices(ctx context.Context, cl *dockerclient.Client, namespace conve
 }
 
 // RunDeploy is the swarm implementation of docker stack deploy
-func RunDeploy(cl *dockerclient.Client, opts Deploy, cfg *composetypes.Config) error {
+func RunDeploy(cl *dockerclient.Client, opts Deploy, cfg *composetypes.Config, recipeName string) error {
 	ctx := context.Background()
 
 	if err := validateResolveImageFlag(&opts); err != nil {
@@ -170,7 +170,7 @@ func RunDeploy(cl *dockerclient.Client, opts Deploy, cfg *composetypes.Config) e
 		opts.ResolveImage = ResolveImageNever
 	}
 
-	return deployCompose(ctx, cl, opts, cfg)
+	return deployCompose(ctx, cl, opts, cfg, recipeName)
 }
 
 // validateResolveImageFlag validates the opts.resolveImage command line option
@@ -183,7 +183,7 @@ func validateResolveImageFlag(opts *Deploy) error {
 	}
 }
 
-func deployCompose(ctx context.Context, cl *dockerclient.Client, opts Deploy, config *composetypes.Config) error {
+func deployCompose(ctx context.Context, cl *dockerclient.Client, opts Deploy, config *composetypes.Config, recipeName string) error {
 	namespace := convert.NewNamespace(opts.Namespace)
 
 	if opts.Prune {
@@ -224,7 +224,7 @@ func deployCompose(ctx context.Context, cl *dockerclient.Client, opts Deploy, co
 		return err
 	}
 
-	return deployServices(ctx, cl, services, namespace, opts.SendRegistryAuth, opts.ResolveImage)
+	return deployServices(ctx, cl, services, namespace, opts.SendRegistryAuth, opts.ResolveImage, recipeName)
 }
 
 func getServicesDeclaredNetworks(serviceConfigs []composetypes.ServiceConfig) map[string]struct{} {
@@ -339,7 +339,8 @@ func deployServices(
 	services map[string]swarm.ServiceSpec,
 	namespace convert.Namespace,
 	sendAuth bool,
-	resolveImage string) error {
+	resolveImage string,
+	recipeName string) error {
 	existingServices, err := GetStackServices(ctx, cl, namespace.Name())
 	if err != nil {
 		return err
@@ -443,9 +444,9 @@ func deployServices(
 	ch := make(chan error, len(serviceIDs))
 	for serviceID, serviceName := range serviceIDs {
 		logrus.Debugf("waiting on %s to converge", serviceName)
-		go func(s string) {
+		go func(sID, sName, rName string) {
-			ch <- waitOnService(ctx, cl, s)
+			ch <- waitOnService(ctx, cl, sID, sName, rName)
-		}(serviceID)
+		}(serviceID, serviceName, recipeName)
 	}
 
 	for _, serviceID := range serviceIDs {
@@ -475,7 +476,7 @@ func getStackConfigs(ctx context.Context, dockerclient client.APIClient, namespa
 
 // https://github.com/docker/cli/blob/master/cli/command/service/helpers.go
 // https://github.com/docker/cli/blob/master/cli/command/service/progress/progress.go
-func waitOnService(ctx context.Context, cl *dockerclient.Client, serviceID string) error {
+func waitOnService(ctx context.Context, cl *dockerclient.Client, serviceID, serviceName, recipeName string) error {
 	errChan := make(chan error, 1)
 	pipeReader, pipeWriter := io.Pipe()
 
@@ -491,6 +492,21 @@ func waitOnService(ctx context.Context, cl *dockerclient.Client, serviceID strin
 	case err := <-errChan:
 		return err
 	case <-time.After(timeout):
-		return fmt.Errorf("%s has still not converged (%s second timeout)?", serviceID, timeout)
+		return fmt.Errorf(fmt.Sprintf(`
+%s has still not converged (%s second timeout reached)
+
+This does not necessarily mean your deployment has failed, it may just be that
+the app is taking longer to deploy based on your server resources or network
+latency. Please run the following the inspect the logs of your deployed app:
+
+    abra app logs %s
+
+If a service is failing to even start (run "abra app ps %s" to see what
+services are running) there could be a few things. The follow command will
+try to smoke those out for you:
+
+    abra app errors %s
+
+`, recipeName, timeout, recipeName, recipeName, recipeName))
 	}
 }