TSYSDevStack/Toolbox/docs/documentation/TROUBLESHOOTING.md

Troubleshooting

This guide addresses common issues you might encounter when using the documentation toolchain container.

🔧 Common Issues

Container Won't Start

Problem: Container fails to start with permission errors.

Solution: Ensure your Docker installation is properly configured and you're running as a user with Docker permissions:

# Add current user to docker group
sudo usermod -aG docker $USER

# Then log out and log back in, or run:
newgrp docker

Pandoc PDF Generation Fails

Problem: PDF generation fails with font or LaTeX errors.

Solution: Ensure you're using the full texlive distribution. The container includes texlive-full, but if custom templates are used, they might require additional packages.

For font errors:

# Inside the container, list available fonts
fc-list

For LaTeX package errors:

# Install additional packages in the container (temporary fix)
tlmgr install package-name

Missing Tools

Problem: Command not found errors for expected tools.

Solution: Verify the container build completed successfully:

# Check if tools are accessible
docker run --rm tsysdevstack-toolboxes-docs which pandoc
docker run --rm tsysdevstack-toolboxes-docs which mdbook
docker run --rm tsysdevstack-toolboxes-docs which typst

File Permission Issues

Problem: Cannot write output files or access mounted volumes.

Solution: The container runs as user tsysdevstack (UID 1001). Ensure mounted volumes have appropriate permissions:

# Option 1: Change ownership to match container user
sudo chown -R 1001:1001 ./output

# Option 2: Use user namespace mapping
docker run --rm --userns=keep-id -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs

🐞 Debugging Steps

Verify Container Status

# Check if container is running properly
docker run --rm -it tsysdevstack-toolboxes-docs whoami
docker run --rm -it tsysdevstack-toolboxes-docs id

Check Tool Versions

# Verify all tools are accessible and working
docker run --rm tsysdevstack-toolboxes-docs bash -c "pandoc --version && mdbook --version && typst --version"

Validate Volume Mounts

# Check if files are properly mounted
docker run --rm -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs ls -la /home/tsysdevstack/docs

Run Diagnostic Script

# Execute a comprehensive check of all tools
docker run --rm tsysdevstack-toolboxes-docs bash -c "
echo 'Checking pandoc...'
pandoc --version
echo 'Checking mdbook...'
mdbook --version
echo 'Checking typst...'
typst --version
echo 'Checking marp...'
npx --package @marp-team/marp-cli marp --version
echo 'Checking quarto...'
quarto --version
"

🧪 Testing Issues

Test Script Fails

Problem: ./output/test.sh fails with errors.

Solution: Run tests individually to identify the specific issue:

1. Check if the image was built successfully: docker images | grep tsysdevstack-toolboxes-docs
2. Run individual validation commands:

# QA tool validation
docker run --rm -i hadolint/hadolint:latest < output/Dockerfile
docker run --rm -v "$(pwd)":/mnt koalaman/shellcheck:stable /mnt/output/build.sh

Docker Build Fails

Problem: ./output/build.sh fails during build process.

Solution:

1. Ensure Docker Buildx is properly configured:

docker buildx ls

2. Create a new builder if needed:

docker buildx create --name container-builder --use --bootstrap

3. Check available disk space and clear Docker cache if needed:

docker system prune -a

🌐 Network Issues

Tool Downloads Fail

Problem: External resources fail to download during build or runtime.

Solution: Check network connectivity and proxy settings:

# Inside the container
docker run --rm tsysdevstack-toolboxes-docs curl -I https://github.com

For corporate networks with proxies:

# Build with proxy settings
docker buildx build --build-arg HTTP_PROXY=http://proxy.company.com:port --build-arg HTTPS_PROXY=http://proxy.company.com:port ...

Container Can't Access Host Files

Problem: Files in mounted volumes are not accessible from within the container.

Solution:

1. Ensure the volume path is correct
2. Check file permissions on the host system
3. Verify the Docker daemon is running properly

🛠️ Mise (Runtime Manager) Issues

Language Version Not Available

Problem: Mise can't install a specific version of Node.js, Python, etc.

Solution: Check available versions:

# Inside the container
mise list-all python
mise list-all node

Then install the closest available version:

mise install python@3.12.x  # where x is the latest patch

Tools Installed via Mise Not Available

Problem: Tools installed via npm, pip, cargo, etc. are not accessible.

Solution: Use mise exec to run commands with the correct environment:

# Instead of running directly
npx create-react-app my-app

# Use mise exec
mise exec node -- npx create-react-app my-app

📋 Reporting Issues

When reporting issues, please include:

1. Docker version: docker --version
2. OS information: uname -a
3. Command that failed
4. Full error message
5. Expected behavior