.

Toolbox/docs/documentation/TROUBLESHOOTING.md

@@ -0,0 +1,199 @@
+# 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:
+```bash
+# 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:
+```bash
+# Inside the container, list available fonts
+fc-list
+```
+
+For LaTeX package errors:
+```bash
+# 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:
+```bash
+# 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:
+```bash
+# 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
+```bash
+# 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
+```bash
+# Verify all tools are accessible and working
+docker run --rm tsysdevstack-toolboxes-docs bash -c "pandoc --version && mdbook --version && typst --version"
+```
+
+### Validate Volume Mounts
+```bash
+# 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
+```bash
+# 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:
+```bash
+# 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:
+```bash
+docker buildx ls
+```
+2. Create a new builder if needed:
+```bash
+docker buildx create --name container-builder --use --bootstrap
+```
+3. Check available disk space and clear Docker cache if needed:
+```bash
+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:
+```bash
+# Inside the container
+docker run --rm tsysdevstack-toolboxes-docs curl -I https://github.com
+```
+
+For corporate networks with proxies:
+```bash
+# 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:
+```bash
+# Inside the container
+mise list-all python
+mise list-all node
+```
+
+Then install the closest available version:
+```bash
+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:
+```bash
+# 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