TSYSDevStack/toolbox-docs/documentation/TROUBLESHOOTING.md

Troubleshooting Guide - TSYS Dev Stack Docs Toolbox

Table of Contents

• Common Issues
• Docker-related Issues
• Tool-specific Issues
• Performance Issues
• Security Considerations

Common Issues

Container Won't Start

Problem: The container fails to start with an error.

Solution:

1. Check if Docker is running:

   docker info
   

2. Check if the image exists:

   docker images | grep tsysdevstack/toolbox-docs
   

3. If the image doesn't exist, build it:

   ./build.sh
   

Permission Issues

Problem: Getting permission errors when accessing files.

Solution: The container runs as the tsysdevstack user. Ensure your host files have appropriate permissions:

# Change ownership to match the container user (UID 1000)
sudo chown -R 1000:1000 ./docs ./output

Tools Not Found

Problem: Commands like pandoc, mdbook, etc. are not found.

Solution: Ensure you're running inside the container:

# Run the container interactively to use the tools
./run.sh
# Then run your command inside the container
pandoc --version

Docker-related Issues

Image Build Fails

Problem: Building the image fails with errors.

Solution:

1. Make sure you're using the latest version of Docker
2. Increase Docker's memory allocation if building fails
3. Clear Docker build cache:

   docker builder prune
   

Large Image Size

Problem: The image is very large due to TeXLive and other tools.

Solution: The image is intentionally comprehensive for document generation. You can create a custom minimal image if needed, but this full image provides the most functionality.

Multi-platform Build Issues

Problem: Build fails when targeting specific platforms.

Solution:

# Try building for your current platform only
./build.sh -p $(docker buildx imagetools inspect --format '{{json .Manifest}}' hello-world | jq -r '.platform.architecture')

Tool-specific Issues

Pandoc Issues

Problem: Pandoc fails when converting documents.

Solution:

• Check if your input file is properly formatted
• For PDF output, ensure TeXLive is properly installed (it should be in this container)
• For custom templates, ensure the template file is available in the container:

  # Check if template exists
  ls -la /home/tsysdevstack/.pandoc/templates/
  

MdBook Issues

Problem: MdBook fails to build or serve books.

Solution:

• Verify that your SUMMARY.md and book.toml files are properly formatted
• Check that all referenced files exist in your book directory
• Make sure you're running mdbook from the book's root directory (where book.toml is)

Typst Issues

Problem: Typst fails to compile documents.

Solution:

• Check if your Typst syntax is correct
• Ensure you have fonts available in the container
• Look at the error message for specific file or syntax issues

Marp Issues

Problem: Marp doesn't generate PDFs correctly.

Solution:

• Make sure your markdown uses correct Marp slide delimiters
• Check for any custom CSS that might be causing rendering issues
• Ensure the container has internet access for downloading themes (if needed)

Quarto Issues

Problem: Quarto fails to render documents.

Solution:

• Verify that required dependencies (like Python, R, etc.) are properly available
• Check if extensions are properly installed
• Look for environment-specific issues that might affect rendering

Performance Issues

Slow Document Generation

Problem: Converting documents takes a very long time.

Solution:

• For PDF generation, TeXLive compilation is naturally slower than other formats
• Consider using HTML output for faster preview during editing
• For large documents, consider breaking them into smaller sections

High Memory Usage

Problem: Container uses excessive memory.

Solution: For resource-intensive operations like full TeXLive compilation, ensure Docker has sufficient memory allocated (at least 4GB recommended).

Security Considerations

Root Access

Problem: Concerned about running with root access.

Solution: This container is designed to run as the tsysdevstack user with no root access at runtime. The only root usage is during the build process for installing system packages.

Network Security

Problem: Need to run without network access.

Solution: The container can run offline once built. It can perform all document generation tasks without network access, though some features like fetching remote templates or themes would be unavailable.

File Access

Problem: Container can access files it shouldn't.

Solution: The container only has access to files in the /docs and /output directories that you explicitly mount. Files outside these directories are not accessible.