Debug App Failing to Stage

In this tutorial you debug an app that fails to stage. Staging failures can result from individual stagers or the staging coordinator not starting, problems mounting packages, errors in application code, and environment issues. You create a custom stager and use it to explore common staging failures. The custom stager you create runs a suite of rspec tests included in the app’s source code.


Complete the steps that follow.

1. Clone the Ruby staging pipeline to your default namespace.

cd sample-apps/demo-ruby-sinatra

NOTE: You can safely ignore the message "ruby-1.9.3-p392 is not installed" if you receive it.

apc staging pipeline clone /apcera::ruby

This command clones (copies) the system-provided Ruby staging pipeline to your /sandbox/<user-name>/ namespace. You need to do this so that you can customize the pipeline by adding a custom stager to it. You do not have permissions to do this on the sytem-provided default Ruby pipeline, nor would you want to.

2. Verify the cloned staging pipeline.

apc staging pipeline list

You should see that a cloned copy of the Ruby staging pipeline now exists in your namespace.

3. Create a custom rspec stager.

apc stager create my-rspec-stager --path rspec-stager --start-command ./rspec-stager --additive --allow-egress

This command creates a custom rspec stager from the bash script in the rspec-stager directory. After running this command you should see that the stager named my-rspec-stager is successfully created.

Run command apc package list to verify that the custom stager was created.

4. Append the rspec stager to your cloned Ruby staging pipeline.

apc staging pipeline append ruby my-rspec-stager

You should see that the ruby staging pipeline is successfully updated. Stagers run within staging pipelines. A staging pipeline is an ordered set of one or more stagers. You can change the order in which stagers run within a staging pipeline by adding one or more stagers to the beginning (prepend) or end (append) of the pipeline. Here you have appended the rspec-stager to the Ruby staging pipeline using the following syntax: apc staging pipeline append <pipeline-name> <stager-names> [...].

5. Create the demo-ruby-sinatra application.

apc app create my-ruby-app --start --staging ruby

As the app is created, Apcera will stage and run the rspec tests, which should all pass.

You can verify the app creation by navigating to the route URL ("App should be accessible at …" with your browser).

6. Change the app’s source code to break the rspec tests.

Now, let’s break the app you just created so we can troubleshoot it.

In demo-ruby-sinatra/spec/app_spec.rb, change the expectation at line 14 from ‘last_response.body.should == "Alive"’ to ‘last_response.body.should == "Dead"’.

Then, re-deploy the app:

apc app deploy my-ruby-app –staging ruby

Expected result:

The re-deploy should fail because you broke the rspec tests. The error message is "Error: Staging has failed." This shows how you can automate some features on your continuous integration suite as part of your deployment process.

Now, fix the source code, and re-deploy the app. It should succeed.

7. Update your rspec stager job to have a bad start command.

Stagers within Apcera are just jobs; they can fail like any other job. When stagers fail, Apcera exposes the failures to you in an intuitive way.

Issue the following command to update your rspec stager to have a bad start command:

apc job update my-rspec-stager --start-command "./bad"

Issue the following command to re-deploy your Ruby application:

apc app deploy my-ruby-app --staging ruby

The re-deploy should fail.

This indicates that the binary the bad start command is trying to run was not found, and as a result, we couldn’t start the stager. Then, we fail the package.

8. Clean up your work.

Delete the stager:

apc stager delete rspec --force

Delete the app:

apc app delete <app-name>

More information

In this tutorial you learned how to debug an app that fails to stage. See also debugging staging errors.