checkId: check.core.env.diskspace plugin: stellaops.doctor.core severity: fail tags: [quick, environment, resources]

Disk Space

Doctor check check.core.env.diskspace — for operators confirming a Stella Ops host has enough free disk for logs, evidence, SBOMs, and scan artifacts before low space starts dropping writes.

What It Checks

Verifies sufficient disk space is available on the drive where the application is running. The check reads the drive information for the current working directory and applies two thresholds:

Evidence collected includes: drive name, free space, total space, and used percentage.

Why It Matters

Stella Ops services write logs, evidence files, SBOM data, scan results, and temporary processing artifacts to disk. When disk space is critically low:

• Database writes fail (PostgreSQL requires WAL space).
• Container images cannot be pulled or built.
• Log files cannot be written, causing silent data loss.
• Evidence locker writes fail, breaking the audit trail.
• Temporary scan artifacts fill up, causing scanner crashes.

Common Causes

• Log files consuming disk space without rotation
• Temporary files not cleaned up after processing
• Application data growth (evidence locker, SBOM storage, scan results)
• Docker images and volumes consuming space on the same partition
• Database WAL files growing due to long-running transactions

How to Fix

Docker Compose

Check disk usage and clean up:

# Check overall disk usage
df -h

# Find large files
du -sh /var/lib/docker/* | sort -hr | head -20

# Clean Docker artifacts
docker system prune -a --volumes

# Clean application temp files
docker compose exec <service> rm -rf /tmp/*

# Set up log rotation in compose
# Add to your service definition:
logging:
  driver: json-file
  options:
    max-size: "10m"
    max-file: "3"

Bare Metal / systemd

# Find large files
du -sh /* | sort -hr | head -20

# Clean temp files
rm -rf /tmp/*

# Rotate logs
sudo logrotate -f /etc/logrotate.conf

# Check and clean old journal logs
sudo journalctl --vacuum-size=100M

Kubernetes / Helm

# Check node disk usage
kubectl top nodes

# Check PVC usage
kubectl exec -it <pod> -- df -h

# Set ephemeral storage limits in Helm values:
resources:
  limits:
    ephemeral-storage: "2Gi"
  requests:
    ephemeral-storage: "1Gi"

Verification

stella doctor run --check check.core.env.diskspace

Related Checks

• check.docker.storage — checks Docker-specific storage driver and disk usage
• check.core.env.memory — checks process memory usage

See the Doctor reference for the full check catalog, CLI usage, and export bundles.