Build and Runtime Logs: Debug Dockup Deployments

Build and runtime logs answer different questions. Build logs explain how source code became an image and why that process failed. Runtime logs explain what the built application did after the container or Kubernetes workload started.

Reading the wrong stream wastes time. A missing dependency during image construction will never appear in runtime logs, while a successful image that crashes on startup may have perfectly clean build output.

What is the difference between build and runtime logs?

Use the deployment stage to choose the stream:

Stage	Typical status	Correct log	Common failures
Clone	cloning	Build	Repository access, branch
Dependency install	building	Build	Lockfile, registry, package
Compile/bundle	building	Build	Type errors, memory, missing files
Image start	deploying	Runtime and health	Start command, port, permissions
Running service	running	Runtime	Exceptions, dependency outages
Readiness gate	deploying	Runtime plus health config	Wrong path, slow startup

Read the latest build output:

dockup logs production/api --build --json

Read runtime output from the running service:

dockup logs production/api --json

Request more runtime lines when the relevant event is older:

dockup logs production/api -n 500 --json

The JSON response identifies the target and log type, which helps an agent avoid merging unrelated streams.

How does dockup logs --build --follow work?

Follow mode streams new lines by polling the current snapshot:

dockup logs production/api --build -f --json

In JSON mode, output is NDJSON: one object per line and per batch. A consumer can process each line incrementally.

A final batch marks the terminal build result. The command stops on its own when the deployment succeeds or fails and exits non-zero for failure. This makes it suitable for an agent or CI job without a hand-written status loop.

Runtime follow works similarly:

dockup logs production/api -f --json

Each batch includes restarted. When restarted:true, the container restarted or the retained log buffer rolled, so Dockup re-emits the whole current snapshot rather than silently dropping lines.

The default polling interval is 2 seconds. Use the documented --interval only when there is a specific need to change the cadence.

How do you diagnose a failed build?

Begin with the terminal deployment result:

dockup deploy production/api --wait --json

When it exits with deploy_failed, retrieve the build log and find the first causal error, not the last cascade message.

A useful sequence is:

1. Confirm target and deployment ID.
2. Identify clone, install, compile, or image stage.
3. Find the first non-retryable error.
4. Compare the build method with repository intent.
5. Reproduce from a clean clone if possible.
6. Make one focused change.
7. Redeploy with --wait.

Common Nixpacks failures include an unrecognized project root, missing lockfile, absent conventional start script, or native package requirement. Common Dockerfile failures include an incorrect build context, missing copied artifact, unavailable base image, or failing RUN instruction.

The Nixpacks vs Dockerfile guide provides a build-system decision map.

Avoid fixing a deterministic build error by increasing the 900-second timeout. A timeout change helps a legitimate long build; it does not repair a command that exited with an error.

How do you diagnose a runtime crash or health failure?

A successful image can still fail before traffic cutover. Inspect service state and runtime output:

dockup status production/api --json
dockup logs production/api --json
dockup health production/api --json

Look for:

• Process exits immediately after start.
• Application binds the wrong port.
• Application listens on 127.0.0.1 instead of all interfaces.
• Required environment key is missing.
• Database or Redis connection fails.
• File permissions block startup.
• Health path returns a non-success status.
• Startup takes longer than the configured retries permit.
• A migration fails or runs concurrently.

Health configuration can be inspected or updated:

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

Do not weaken the health gate simply to make a broken release pass. If startup legitimately needs more time, change the policy with evidence and retain an endpoint that still proves readiness.

Environment changes require redeployment. If a missing secret is fixed, deploy again and wait; restarting the old container does not apply the new desired environment.

How should agents parse NDJSON without losing the exit code?

An agent or script should read each JSON line while preserving the process status. Avoid piping into a command that masks the original exit without pipefail.

set -o pipefail
dockup logs production/api --build -f --json \
  | tee build-stream.ndjson

With pipefail, a failed Dockup command keeps the pipeline non-zero even though tee completed successfully.

A consumer can inspect each object independently:

while IFS= read -r line; do
  printf '%s\n' "$line" | jq -r '.lines[]?'
done < build-stream.ndjson

Keep the raw NDJSON artifact. A human-readable excerpt is useful for a pull request or incident, but the original fields preserve restart markers, status, and completion signals.

The general machine-interface principles are explained in AI agent CLI design.

What is a repeatable deployment debugging runbook?

Use this decision path:

dockup status production/api --json
dockup deployments production/api -n 5 --json
dockup logs production/api --build --json
dockup logs production/api --json

Then classify the incident:

Classification	Evidence	Next action
Source/build	Build log error	Fix repository or build definition
Configuration	Missing/wrong env or port	Correct config and redeploy
Readiness	App runs, health fails	Fix endpoint or justified timing
Runtime dependency	Connection exception	Check database/network/credential
Regression	Previous version worked	Consider known-ID rollback
Platform uncertainty	Timeout, no terminal state	Inspect status before retry

Roll back only after identifying a known previous deployment:

dockup rollback <deploymentId> production/api --json

Preserve the failed deployment ID and logs first. A rollback restores service availability; it does not explain the root cause.

The zero-downtime deployments article explains why a failed readiness gate can protect live traffic.

How should production logs be made useful?

Dockup can retrieve output, but the application controls log quality. Prefer structured, single-event records with timestamps, severity, request or trace IDs, component name, and a safe error description.

Never log access tokens, database URLs, passwords, full authorization headers, or personal data that is not necessary for operations. Secret masking in Dockup configuration does not redact arbitrary application output.

Log startup facts that are safe and diagnosable:

• Application version or commit.
• Environment name.
• Listening port.
• Enabled feature names without secret values.
• Database host class, not password.
• Migration version.
• Health endpoint readiness.

Incident timeline template

Record:

1. Deployment ID and source commit.
2. Deploy start and terminal timestamps.
3. First causal build or runtime error.
4. Health-gate result.
5. Recovery command and deployment ID.
6. User impact window.
7. Follow-up owner.

Uptime data adds minute-level availability and response time:

dockup uptime production/api --hours 24 --json

The result includes average and p95 response time. Combine it with build and runtime logs to distinguish a deployment incident from a longer performance regression.

Use the Dockup CLI reference for the current log flags and security best practices for safe application logging.

Correlate logs with deployment history

A line is useful only when it can be tied to the correct release. Store the deployment ID, commit hash, and start time next to the log artifact. When two releases happen close together, timestamps alone can be misleading.

dockup deployments production/api -n 20 --json

Deployment history establishes which source was active and which release reached a terminal state. An agent should not attribute a runtime exception to the latest commit until the service state confirms that commit was actually deployed.

Avoid log-driven secret exposure

A failed connection often tempts developers to print the full URL. Instead, log the protocol, masked host, database name, and error category. For tokens, log only a safe fingerprint generated before storage when the organization has a policy for it.

Review failed-build artifacts before sharing them outside the team. Package-manager and Docker output can contain private repository URLs, registry usernames, or command arguments even when Dockup correctly masks stored environment secrets.

This makes build and runtime logs safe enough for collaborative diagnosis.

Preserve a minimal evidence bundle

For every failed release, save the deployment result JSON, build log, relevant runtime excerpt, service status, and selected recovery deployment ID. This bundle is small enough for routine use and complete enough for a second operator to continue without rerunning uncertain mutations.

Confirm the fix, not only the new build

After the corrected deployment succeeds, repeat the failing request or startup condition and watch runtime output for recurrence. Close the incident only when the original symptom is absent, the health gate passes, and the expected production behavior is observed.

Close the loop

Document the verified fix.

Start with a verifiable deployment

Force one test build to fail, capture its NDJSON stream and exit code, then verify that your runbook selects the build log instead of the runtime log.

Start free at app.dockup.ai. The Free plan is $0 per month, includes $2.50 in starting credit, and supports one workspace, three databases, and three deployments.

FAQ

What is the difference between Dockup build logs and runtime logs?

Build logs cover cloning, dependency installation, compilation, and image creation. Runtime logs cover the started application container or pods.

How do I follow Dockup build logs live?

Use dockup logs with --build and --follow, or -f. With --json, the command emits NDJSON batches and ends at the deployment terminal state.

Why does build follow exit non-zero?

It preserves the deployment result. A failed build must fail the calling shell, CI job, or agent task instead of looking like a successful log stream.

What does restarted:true mean in runtime follow output?

It indicates that the container restarted or the retained buffer rolled, so Dockup emitted the current snapshot again rather than silently losing lines.

Should application logs contain environment secrets?

No. Dockup masks stored configuration reads, but it cannot make arbitrary secrets printed by the application safe. Redact credentials at the application logging layer.