TSYSDevStack/documentation/TROUBLESHOOTING.md

TROUBLESHOOTING.md

TSYSDevStack - Toolboxes - DocsAndDiagrams

Troubleshooting Guide for the Document Production Workhorse Container

---

🐛 Common Issues and Solutions

Docker Container Won't Start

Issue: Container fails to start with permission errors

Solution:

# Check if Docker daemon is running
sudo systemctl status docker

# If not running, start it
sudo systemctl start docker

# Ensure your user is in the docker group
sudo usermod -aG docker $USER
# Then log out and log back in

Permission Denied Errors

Issue: Getting permission errors when accessing mounted volumes

Solution:

1. The container runs as user tsysdevstack with UID 1000
2. Ensure your host directory is writable by UID 1000:

   sudo chown -R 1000:1000 /path/to/local/directory
   

3. Or run the container with appropriate user mapping:

   docker run -u $(id -u):$(id -g) -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
   

Pandoc Fails with Font Errors

Issue: PDF generation fails with font-related errors

Solution:

1. The container includes Noto fonts, but you may need additional fonts:

   # Check available fonts
   fc-list
   
   # Install additional fonts by extending the container
   

Large Document Processing Issues

Issue: Container runs out of memory when processing large documents

Solution:

1. Increase Docker's memory allocation in Docker Desktop settings
2. Run with memory limits:

   docker run --memory="4g" -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs
   

TeXLive Compilation Fails

Issue: LaTeX compilation fails with missing packages

Solution:

1. The container includes a basic TeXLive installation with common packages
2. For additional packages, use tlmgr:

   docker run -it tsysdevstack/toolboxes-docs tlmgr install package-name
   

Missing Language Runtime Tools

Issue: Tools installed via npm/pip not working

Solution:

1. The container uses mise to manage language runtimes
2. Check if the runtime is properly configured:

   mise current
   

3. Install or activate the required version:

   mise use --global python@3.12.6  # or required version
   

Quarto Rendering Issues

Issue: Quarto fails with missing R or Python environments

Solution:

1. The container has a basic Python environment but may need extensions:

   # Install required Python packages
   pip3 install jupyter numpy pandas matplotlib
   

🔧 Diagnostic Commands

Check Container Information

# Check running containers
docker ps

# Check container logs
docker logs <container-name>

# Execute commands in running container
docker exec -it <container-name> /bin/bash

Verify Tool Availability

# Check all installed tools
docker run --rm tsysdevstack/toolboxes-docs which pandoc mdbook typst marp quarto jq yq

# Check Pandoc version and capabilities
docker run --rm tsysdevstack/toolboxes-docs pandoc --version

# Check TeXLive installation
docker run --rm tsysdevstack/toolboxes-docs xelatex --version

Check Storage and Paths

# Verify output directory exists and is writable
docker run --rm -v $(pwd)/output:/home/tsysdevstack/TSYSDevStack/Toolbox/docs/output tsysdevstack/toolboxes-docs ls -la /home/tsysdevstack/TSYSDevStack/Toolbox/docs/output

# Check if input files are accessible
docker run --rm -v $(pwd)/:/data tsysdevstack/toolboxes-docs ls -la /data

🔍 Debugging Steps

1. Check the error message carefully
2. Verify your input files exist and are accessible
3. Check that you have sufficient disk space
4. Try running a simple command first (e.g., pandoc --version)
5. Check container logs if running as a service
6. Verify volume mappings are correct
7. Test with a minimal document to isolate issues

📞 Support

If you encounter issues not covered in this guide:

1. Check the Usage Guide for correct command syntax
2. Review Cheat Sheet for common commands
3. Search the repository issues for similar problems
4. Create a new issue with:
   • Docker version
   • Host OS
   • Command used
   • Error message
   • Expected behavior