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:
```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