Debug Mode

This document describes the debug mode configuration capabilities for service stacks in Zerops, allowing developers to pause execution at specific points during build and runtime processes for debugging purposes.

Overview

Debug mode introduces control over two distinct phases of deployment:

• Build phase - When the buildCommands are executed
• Runtime prepare phase - When the prepareCommands are executed

For each phase, you can choose when to pause the execution:

• Disable - No pausing, execution proceeds normally
• Before first command - Execution stops before running any commands
• After last command - Execution stops after all commands complete
• On command fail - Execution stops when a command fails

Each phase can be configured with its own debug settings without affecting the other phase.

Important

The entire build process, including any time spent in debug mode, has a maximum duration of 60 minutes. After this time limit is reached, the build process is automatically cancelled.

Configuration

The debug mode configuration can be found in your service detail under the Pipelines & CI/CD settings.

Debug Control

When execution is paused in debug mode, you have several commands available to control the debugging process. Each command serves a specific purpose and affects the deployment process differently.

Debug Pause Points

There are three key points where execution can pause during deployment:

• ➠ Disable - Do not pause
• ↪ Before First Command - Paused before any commands run
• ✖ On Command Failure - Paused when a command fails
• ✔ After Last Command - Paused after all commands complete

Available Commands

Continuing Execution

To proceed with the normal deployment process, use:

zsc debug continue

Pause Point	Behavior
↪ Before First Command	Begins running commands for the current phase until next possible pause point
✖ On Command Failure	Skips the failed command and continues deployment
✔ After Last Command	Moves to the next phase (from build to runtime prepare) or completes deployment

Marking Success

To force a successful deployment status, use:

zsc debug success

Pause Point	Behavior
↪ Before First Command	Ends current phase without running any commands
✖ On Command Failure	Ignores the failure and ends current phase with success
✔ After Last Command	Concludes current phase with a successful status

Note

Requires valid deployFiles to work properly (fails otherwise).

Forcing Failure

To terminate the deployment with a failure status, use:

zsc debug fail

Pause Point	Behavior
↪ Before First Command	Marks current phase as failed without running commands
✖ On Command Failure	Ends deployment with original error
✔ After Last Command	Overwrites successful execution with failed status and ends deployment

Each phase can be configured independently to pause at any of the points described above, giving you precise control over your debugging workflow. The 60-minute timeout ensures deployments don't remain blocked indefinitely.

Usage Examples

Example 1: Debugging Build Failures

Build phase	✖ On Command Failure
Prepare runtime phase	➠ Disable

This configuration allows you to:

1. Inspect the container state after a failure
2. Make necessary adjustments
3. Use zsc debug continue to resume or zsc debug fail to abort

Example 2: Validating Runtime Setup

Build phase	➠ Disable
Prepare runtime phase	✔ After Last Command

Best Practices

Targeted Debugging

• Enable debug mode only for the specific phase you need to investigate
• This minimizes disruption to the deployment process
• Helps maintain clear debugging sessions

Clean Up

• Always remember to disable debug mode after completing your debugging session
• Set both phases to Disable
• Prevents unexpected pauses in future deployments

Production Consideration

• Be cautious when using debug mode in production environments
• Paused executions can block deployments
• Consider using separate development services for extended debugging sessions

Timeout Awareness

• Be mindful of the 60-minute maximum debug pause time (p)lan debugging sessions accordingly)

Technical Considerations

• Debug mode settings persist until explicitly changed
• Build phase and runtime prepare phase operate independently
• Debug commands are only available when execution is paused
• Success signals require valid deployFiles to proceed