# Troubleshooting Guide - TSYS Dev Stack Docs Toolbox

## Table of Contents
- [Common Issues](#common-issues)
- [Docker-related Issues](#docker-related-issues)
- [Tool-specific Issues](#tool-specific-issues)
- [Performance Issues](#performance-issues)
- [Security Considerations](#security-considerations)

## Common Issues

### Container Won't Start
**Problem**: The container fails to start with an error.

**Solution**: 
1. Check if Docker is running:
   ```bash
   docker info
   ```
2. Check if the image exists:
   ```bash
   docker images | grep tsysdevstack/toolbox-docs
   ```
3. If the image doesn't exist, build it:
   ```bash
   ./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:
```bash
# 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:
```bash
# 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:
   ```bash
   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**: 
```bash
# 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:
  ```bash
  # 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.