gh-rknall-claude-skills-stack-validator/common-issues.md

Common Stack Validation Issues

This guide documents common issues found during stack validation, their causes, impacts, and remediation guidance.

Table of Contents

1. Critical Issues
2. Security Issues
3. Configuration Issues
4. Structural Issues
5. Docker Issues
6. Ownership Issues

---

Critical Issues

1. Missing .env.example File

Issue: .env file exists but .env.example is missing

Impact:

• New developers don't know which environment variables are required
• No template for setting up new environments
• Difficult to understand configuration requirements
• Potential for missing critical variables in deployments

Detection:

❌ Environment Variables: CRITICAL
   - .env.example file not found
   - Required for documenting environment configuration

Why This Matters: The .env.example file serves as documentation and a template for all required environment variables. Without it, setting up the stack in a new environment is error-prone.

Remediation: Use stack-creator skill to generate .env.example from current .env file:

• claude "Use stack-creator to add .env.example"
• Or manually create .env.example with all variables from .env

---

2. .env and .env.example Out of Sync

Issue: Variables in .env don't match .env.example

Impact:

• Deployments may fail due to missing variables
• Documentation is inaccurate
• Team members may have different configurations
• Difficult to identify required vs optional variables

Detection:

❌ Environment Variables: CRITICAL
   - Variables in .env but NOT in .env.example:
     * API_TIMEOUT
     * MAX_CONNECTIONS
   - Variables in .env.example but NOT in .env:
     * CACHE_TTL

Why This Matters: The two files MUST be synchronized. .env.example is the source of truth for required variables.

Remediation:

1. Manually sync the files - add missing variables
2. Use stack-creator to regenerate .env.example
3. Review if any variables should be removed

---

3. Secrets in .env File

Issue: Passwords, API keys, or tokens in .env

Impact:

• Security risk if .env is accidentally committed
• Secrets not properly isolated
• Violates security best practices
• Difficult to rotate secrets

Detection:

❌ Environment Variables: CRITICAL
   - Potential secrets detected in .env:
     * DB_PASSWORD (contains password pattern)
     * API_KEY (contains key pattern)
     * JWT_SECRET (contains secret pattern)

Why This Matters: Secrets should NEVER be in .env files. They should be in ./secrets and managed via Docker secrets.

Remediation: Use secrets-manager skill to properly configure secrets:

1. Move secrets to ./secrets directory
2. Update docker-compose.yml to use Docker secrets
3. Remove secrets from .env
4. Update applications to read from /run/secrets/

---

Security Issues

4. ./secrets Directory Not in .gitignore

Issue: Secrets directory not excluded from git

Impact:

• CRITICAL SECURITY RISK: Secrets may be committed to git
• Secret exposure in version control
• Compliance violations
• Potential data breach

Detection:

❌ Directory Structure: CRITICAL
   - ./secrets not found in .gitignore
   - Risk of committing secrets to version control

Why This Matters: Once secrets are committed to git, they remain in history forever, even after removal.

Remediation:

1. Add to .gitignore immediately:

   /secrets/
   /secrets/*
   

2. Check git status: git status - ensure no secrets staged
3. If secrets were committed, rotate all secrets immediately
4. Use BFG Repo-Cleaner to remove from git history (if needed)

---

5. Secrets in docker-compose.yml Environment Variables

Issue: Hardcoded secrets in environment variables

Impact:

• Secrets exposed in docker-compose.yml (may be in git)
• Violates security best practices
• Difficult to rotate secrets
• Potential compliance issues

Detection:

❌ Secrets Management: CRITICAL
   - Service 'app' has potential secrets in environment:
     * DB_PASSWORD=supersecret123 (hardcoded password)
   - Use Docker secrets instead

Why This Matters: docker-compose.yml is often committed to git. Any secrets in it are exposed.

Remediation: Use secrets-manager skill:

1. Move secrets to ./secrets/
2. Define in top-level secrets section
3. Reference via secrets key in services
4. Update app to read from /run/secrets/

---

6. Insecure ./secrets Directory Permissions

Issue: ./secrets directory readable by others (e.g., 755 instead of 700)

Impact:

• Other users on system can read secrets
• Security compliance violation
• Unnecessary exposure of sensitive data

Detection:

⚠️  Secrets Management: WARNING
   - ./secrets directory permissions: 755
   - Should be 700 (owner only)

Why This Matters: Secrets should only be readable by the user running the stack.

Remediation:

chmod 700 ./secrets/
chmod 600 ./secrets/*

---

7. .env File Tracked in Git

Issue: .env file is committed to version control

Impact:

• Configuration values exposed in git
• May contain secrets (critical if so)
• Environment-specific config in wrong place
• Difficult to manage per-environment settings

Detection:

❌ Directory Structure: CRITICAL
   - .env is tracked by git (run: git ls-files .env)
   - Must be added to .gitignore

Why This Matters: .env files often contain environment-specific and sensitive data.

Remediation:

1. Add .env to .gitignore
2. Remove from git: git rm --cached .env
3. Commit the removal
4. Review .env for any secrets - rotate if found

---

Configuration Issues

8. Docker Compose Version Field Present

Issue: docker-compose.yml includes version field

Impact:

• Using deprecated syntax
• May cause warnings in modern Docker
• Not following current best practices

Detection:

⚠️  Docker Configuration: WARNING
   - docker-compose.yml contains 'version' field
   - Modern Compose files should omit version

Why This Matters: Docker Compose Specification removed version field requirement. Modern files don't need it.

Remediation: Manually remove the version line:

# ❌ Remove this
version: '3.8'

# ✅ Start directly with services
services:
  app:
    ...

---

9. Secrets Defined but Files Missing

Issue: docker-compose.yml references secrets that don't exist

Impact:

• Stack will fail to start
• Docker will show "secret not found" errors
• Service initialization failures

Detection:

❌ Secrets Management: CRITICAL
   - Secret 'db_password' defined but file not found:
     Expected: ./secrets/db_password
   - Secret 'api_key' defined but file not found:
     Expected: ./secrets/api_key

Why This Matters: Docker requires all referenced secret files to exist before starting services.

Remediation: Use secrets-manager skill to create missing secrets:

1. Create secret files: echo -n "value" > ./secrets/db_password
2. Set proper permissions: chmod 600 ./secrets/db_password
3. Verify all secrets exist before starting stack

---

10. Undefined Secret References

Issue: Service references secret not defined in top-level secrets section

Impact:

• Docker Compose validation will fail
• Stack won't start
• Error messages: "service X references undefined secret"

Detection:

❌ Docker Configuration: CRITICAL
   - Service 'app' references undefined secret: jwt_secret
   - Secret must be defined in top-level 'secrets' section

Why This Matters: All secrets used by services must be declared in the top-level secrets section.

Remediation: Add secret definition to docker-compose.yml:

secrets:
  jwt_secret:
    file: ./secrets/jwt_secret

---

Structural Issues

11. Missing Required Directories

Issue: Required directories (./config, ./secrets, ./_temporary) don't exist

Impact:

• Stack may fail to start
• Volume mounts will fail
• Application errors
• Inconsistent structure

Detection:

❌ Directory Structure: CRITICAL
   - Required directory './secrets' not found
   - Required directory './_temporary' not found

Why This Matters: Standard stack architecture requires these directories for proper organization.

Remediation: Use stack-creator skill to create missing directories:

mkdir -p config secrets _temporary
chmod 700 secrets

---

12. Incomplete .gitignore

Issue: .gitignore doesn't exclude required paths

Impact:

• Risk of committing secrets or temporary files
• Large repository size
• Cluttered git status
• Security risks

Detection:

⚠️  Directory Structure: WARNING
   - .gitignore missing exclusion: /secrets/
   - .gitignore missing exclusion: /_temporary/
   - .gitignore missing exclusion: .env

Why This Matters: Without proper exclusions, sensitive files may be accidentally committed.

Remediation: Add to .gitignore:

# Secrets
/secrets/
/secrets/*

# Environment
.env

# Temporary
/_temporary/
/_temporary/*

---

13. ./_temporary Directory Not Empty

Issue: Temporary directory contains leftover files

Impact:

• Disk space waste
• Stale cached data
• Potential application issues
• Poor housekeeping

Detection:

⚠️  Temporary Directory: WARNING
   - ./_temporary is not empty:
     * cache/sessions/old_session.dat (modified 15 days ago)
     * uploads/temp_file.jpg (modified 3 days ago)
   - Should be cleaned after use

Why This Matters: Temporary directories should be cleaned regularly to avoid accumulating stale data.

Remediation: Manually clean the directory:

rm -rf ./_temporary/*

---

Docker Issues

14. Invalid docker-compose.yml Syntax

Issue: YAML syntax errors in docker-compose.yml

Impact:

• Stack cannot start
• Docker Compose validation fails
• Difficult to troubleshoot
• Deployment failures

Detection:

❌ Docker Configuration: CRITICAL
   - docker-compose.yml syntax error at line 23
   - Error: mapping values are not allowed here

Why This Matters: Invalid YAML prevents Docker Compose from parsing the file.

Remediation:

1. Fix YAML syntax errors
2. Validate with: docker compose config
3. Use YAML linter for complex files

---

15. Missing Service Dependencies

Issue: Services don't declare depends_on for required services

Impact:

• Services may start in wrong order
• Application errors on startup
• Race conditions
• Connection failures

Detection:

⚠️  Docker Configuration: WARNING
   - Service 'app' uses DB but doesn't declare depends_on: postgres
   - May cause startup ordering issues

Why This Matters: Docker doesn't guarantee service start order without depends_on.

Remediation: Add depends_on to service:

services:
  app:
    depends_on:
      - postgres
      - redis

---

16. No Restart Policy

Issue: Services missing restart policy

Impact:

• Services don't recover from crashes
• Manual intervention needed
• Poor reliability
• Downtime

Detection:

⚠️  Docker Configuration: WARNING
   - Service 'app' has no restart policy
   - Recommend: restart: unless-stopped

Why This Matters: Production services should automatically restart on failure.

Remediation: Add restart policy:

services:
  app:
    restart: unless-stopped

---

Ownership Issues

17. Root-Owned Configuration Files

Issue: Files in ./config owned by root

Impact:

• Cannot modify config without sudo
• Inconsistent permissions
• Potential deployment issues
• Bad practice

Detection:

❌ File Ownership: CRITICAL
   - Root-owned files found:
     * ./config/nginx/nginx.conf (owner: root)
     * ./config/app/settings.yml (owner: root)

Why This Matters: All stack files should be owned by the Docker user, not root.

Remediation: Fix ownership:

sudo chown -R $(id -u):$(id -g) ./config/

To prevent: Ensure containers don't run as root, or don't mount config as writable.

---

18. Root-Owned Files in _temporary

Issue: Files in ./_temporary created by containers as root

Impact:

• Cannot clean directory without sudo
• Disk space issues
• Permission problems

Detection:

⚠️  File Ownership: WARNING
   - Root-owned files in ./_temporary:
     * ./_temporary/cache/app_cache.db (owner: root)

Why This Matters: Temporary files should be cleanable by the user.

Remediation:

1. Fix current files: sudo chown -R $(id -u):$(id -g) ./_temporary/
2. Prevent future issues: Run containers as current user:

   services:
     app:
       user: "${UID}:${GID}"
   

---

19. Root-Owned Secret Files

Issue: Files in ./secrets owned by root

Impact:

• Cannot update secrets without sudo
• Security risk (root has access)
• Operational difficulties

Detection:

❌ File Ownership: CRITICAL
   - Root-owned files in ./secrets:
     * ./secrets/db_password (owner: root)

Why This Matters: Secret files should be owned by the Docker user with restricted permissions.

Remediation:

sudo chown $(id -u):$(id -g) ./secrets/*
chmod 600 ./secrets/*

---

Script Issues

20. Unnecessary docker-entrypoint.sh

Issue: docker-entrypoint.sh exists but container supports native secrets

Impact:

• Unnecessary complexity
• Maintenance overhead
• Potential bugs
• Not following best practices

Detection:

⚠️  Scripts: WARNING
   - docker-entrypoint.sh found for service 'postgres'
   - PostgreSQL supports native Docker secrets via *_FILE variables
   - Consider removing custom entrypoint

Why This Matters: Many modern containers support Docker secrets natively. Custom entrypoints add complexity.

Remediation:

1. Check if container supports *_FILE environment variables
2. If yes, remove docker-entrypoint.sh
3. Use native secret support:

   environment:
     POSTGRES_PASSWORD_FILE: /run/secrets/db_password
   

---

21. docker-entrypoint.sh Not Executable

Issue: Script exists but doesn't have execute permissions

Impact:

• Container will fail to start
• Permission denied errors
• Deployment failures

Detection:

❌ Scripts: CRITICAL
   - docker-entrypoint.sh is not executable
   - Current permissions: -rw-r--r--
   - Required: -rwxr-xr-x

Why This Matters: Docker needs execute permission to run entrypoint scripts.

Remediation:

chmod +x docker-entrypoint.sh

---

22. Hardcoded Secrets in Scripts

Issue: Secrets hardcoded in docker-entrypoint.sh or other scripts

Impact:

• CRITICAL SECURITY RISK
• Secrets exposed in git
• Difficult to rotate
• Compliance violations

Detection:

❌ Scripts: CRITICAL
   - Hardcoded secret detected in docker-entrypoint.sh:
     Line 15: export DB_PASSWORD="supersecret123"
   - Secrets must be read from /run/secrets/

Why This Matters: Scripts are often committed to git. Hardcoded secrets = exposed secrets.

Remediation: Read secrets from Docker secrets:

# ❌ BAD
export DB_PASSWORD="supersecret123"

# ✅ GOOD
export DB_PASSWORD=$(cat /run/secrets/db_password)

---

Summary: Issue Severity Levels

Critical (Must Fix Before Deployment)

• Missing .env.example
• .env/.env.example out of sync
• Secrets in .env
• ./secrets not in .gitignore
• Secrets in docker-compose.yml
• Missing secret files
• Root-owned files
• Invalid docker-compose.yml syntax

High (Fix Soon)

• .env tracked in git
• Insecure secrets permissions
• Missing required directories
• Hardcoded secrets in scripts

Medium (Should Fix)

• Docker Compose version field
• Missing restart policies
• Missing dependencies
• Incomplete .gitignore

Low (Nice to Fix)

• ./_temporary not empty
• Unnecessary docker-entrypoint.sh
• Suboptimal configurations

---

Quick Reference: Issue to Skill Mapping

Issue Category	Recommended Skill
Missing .env.example	stack-creator
Directory structure	stack-creator
Secrets management	secrets-manager
Docker configuration	docker-validation (auto-used)
File ownership	Manual fix (chown)
.gitignore issues	stack-creator
.env sync	Manual + stack-creator

---

This guide helps identify and understand common stack validation issues for faster remediation.