This commit is contained in:
Henrik Jess Nielsen
528
scripts/test/USAGE.md
Normal file
528
scripts/test/USAGE.md
Normal file
@@ -0,0 +1,528 @@
|
||||
# Docker Configuration Testing - Quick Start Guide
|
||||
|
||||
## Overview
|
||||
|
||||
The `test-docker-config-local.sh` script provides comprehensive testing for Docker configuration volume mounts and environment variable overrides.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. **Docker**: Installed and running
|
||||
2. **Images**: Pre-built Docker images for testing
|
||||
3. **Ports**: 18100-18199 available for test containers
|
||||
4. **Utilities**: `bash`, `curl`, `docker` command-line tools
|
||||
|
||||
## Building Test Images
|
||||
|
||||
Before running tests, build the Docker images:
|
||||
|
||||
```bash
|
||||
cd .
|
||||
|
||||
# Build core variant
|
||||
docker build -f docker/Dockerfile.core -t kreuzberg:core .
|
||||
|
||||
# Build full variant
|
||||
docker build -f docker/Dockerfile.full -t kreuzberg:full .
|
||||
|
||||
# Or build both
|
||||
docker build -f docker/Dockerfile.core -t kreuzberg:core . && \
|
||||
docker build -f docker/Dockerfile.full -t kreuzberg:full .
|
||||
```
|
||||
|
||||
## Running Tests
|
||||
|
||||
### Basic Usage
|
||||
|
||||
Test all variants with default settings:
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh
|
||||
```
|
||||
|
||||
### Common Commands
|
||||
|
||||
**Test only core variant:**
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --variant core
|
||||
```
|
||||
|
||||
**Test only full variant:**
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --variant full
|
||||
```
|
||||
|
||||
**Enable verbose output:**
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --verbose
|
||||
```
|
||||
|
||||
**Keep containers after testing:**
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --keep-containers
|
||||
```
|
||||
|
||||
**Combine multiple options:**
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --variant full --verbose --keep-containers
|
||||
```
|
||||
|
||||
## Test Cases Explained
|
||||
|
||||
### 1. Volume Mount to /etc/kreuzberg/kreuzberg.toml
|
||||
|
||||
**What it tests**: System-wide configuration path (recommended)
|
||||
|
||||
**Docker command**:
|
||||
|
||||
```bash
|
||||
docker run -v /local/config.toml:/etc/kreuzberg/kreuzberg.toml:ro kreuzberg:full
|
||||
```
|
||||
|
||||
**Expected**: Container reads config from standard system location
|
||||
|
||||
---
|
||||
|
||||
### 2. Volume Mount to /app/.config/kreuzberg/config.toml
|
||||
|
||||
**What it tests**: User-level configuration path (alternative location)
|
||||
|
||||
**Docker command**:
|
||||
|
||||
```bash
|
||||
docker run -v /local/config.toml:/app/.config/kreuzberg/config.toml:ro kreuzberg:full
|
||||
```
|
||||
|
||||
**Expected**: Container reads config from user application directory
|
||||
|
||||
---
|
||||
|
||||
### 3. Custom Path with --config Flag
|
||||
|
||||
**What it tests**: Explicit configuration path specification
|
||||
|
||||
**Docker command**:
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-v /local/config.toml:/app/custom-config.toml:ro \
|
||||
--entrypoint "/app/kreuzberg" \
|
||||
kreuzberg:full \
|
||||
--config /app/custom-config.toml
|
||||
```
|
||||
|
||||
**Expected**: Container uses specified custom path
|
||||
|
||||
---
|
||||
|
||||
### 4. Environment Variable Overrides
|
||||
|
||||
**What it tests**: Environment variables override config file settings
|
||||
|
||||
**Docker command**:
|
||||
|
||||
```bash
|
||||
docker run \
|
||||
-v /local/config.toml:/etc/kreuzberg/kreuzberg.toml:ro \
|
||||
-e KREUZBERG_SERVER_PORT=8000 \
|
||||
kreuzberg:full
|
||||
```
|
||||
|
||||
**Expected**: Environment variable takes precedence over config file
|
||||
|
||||
---
|
||||
|
||||
### 5. TOML Format Support
|
||||
|
||||
**What it tests**: Configuration in TOML format
|
||||
|
||||
**Config file**:
|
||||
|
||||
```toml
|
||||
[server]
|
||||
host = "0.0.0.0"
|
||||
port = 8000
|
||||
max_upload_mb = 100
|
||||
|
||||
[ocr]
|
||||
backend = "tesseract"
|
||||
language = "eng"
|
||||
```
|
||||
|
||||
**Expected**: Container parses TOML correctly
|
||||
|
||||
---
|
||||
|
||||
### 6. YAML Format Support
|
||||
|
||||
**What it tests**: Configuration in YAML format
|
||||
|
||||
**Config file**:
|
||||
|
||||
```yaml
|
||||
server:
|
||||
host: "0.0.0.0"
|
||||
port: 8000
|
||||
max_upload_mb: 100
|
||||
|
||||
ocr:
|
||||
backend: "tesseract"
|
||||
language: "eng"
|
||||
```
|
||||
|
||||
**Expected**: Container parses YAML correctly
|
||||
|
||||
---
|
||||
|
||||
### 7. JSON Format Support
|
||||
|
||||
**What it tests**: Configuration in JSON format
|
||||
|
||||
**Config file**:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": {
|
||||
"host": "0.0.0.0",
|
||||
"port": 8000,
|
||||
"max_upload_mb": 100
|
||||
},
|
||||
"ocr": {
|
||||
"backend": "tesseract",
|
||||
"language": "eng"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected**: Container parses JSON correctly
|
||||
|
||||
---
|
||||
|
||||
### 8. Read-Only Mount
|
||||
|
||||
**What it tests**: Security of read-only mounted volumes
|
||||
|
||||
**Docker command**:
|
||||
|
||||
```bash
|
||||
docker run -v /local/config.toml:/etc/kreuzberg/kreuzberg.toml:ro kreuzberg:full
|
||||
```
|
||||
|
||||
**Expected**: Container works with read-only volumes, application doesn't attempt to modify config
|
||||
|
||||
---
|
||||
|
||||
## Understanding Output
|
||||
|
||||
### Success Output
|
||||
|
||||
```text
|
||||
╔════════════════════════════════════════════════════════╗
|
||||
║ Docker Configuration Volume Mount Test Suite ║
|
||||
╚════════════════════════════════════════════════════════╝
|
||||
|
||||
[INFO] Configuration:
|
||||
[INFO] Variant: all
|
||||
[INFO] Verbose: false
|
||||
[INFO] Keep Containers: false
|
||||
[INFO] Port Range: 18100-18199
|
||||
|
||||
[INFO] Docker is available
|
||||
|
||||
Test 01: Volume mount to /etc/kreuzberg/kreuzberg.toml (variant: core)
|
||||
[PASS] Test passed
|
||||
```
|
||||
|
||||
### Failure Output
|
||||
|
||||
```text
|
||||
Test 02: Custom path with --config flag (variant: core)
|
||||
[FAIL] Test failed: Failed to start container with custom --config flag
|
||||
[FAIL] Details: Container logs:
|
||||
/app/kreuzberg: line 123: syntax error: unexpected token
|
||||
```
|
||||
|
||||
### Summary
|
||||
|
||||
```text
|
||||
╔════════════════════════════════════════════════════════╗
|
||||
║ Test Summary ║
|
||||
╚════════════════════════════════════════════════════════╝
|
||||
|
||||
Total Tests: 16
|
||||
Passed Tests: 16
|
||||
Failed Tests: 0
|
||||
Pass Rate: 100%
|
||||
|
||||
Tested Variants:
|
||||
- kreuzberg:core
|
||||
- kreuzberg:full
|
||||
```
|
||||
|
||||
## Debugging Failed Tests
|
||||
|
||||
### Enable Verbose Output
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --variant core --verbose
|
||||
```
|
||||
|
||||
Verbose output shows:
|
||||
|
||||
- Container IDs
|
||||
- Docker arguments
|
||||
- Service startup timing
|
||||
- Health check attempts
|
||||
|
||||
### Keep Containers for Inspection
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --keep-containers
|
||||
```
|
||||
|
||||
Then inspect containers manually:
|
||||
|
||||
```bash
|
||||
# List test containers
|
||||
docker ps -a | grep kreuzberg-config-test
|
||||
|
||||
# View specific container logs
|
||||
docker logs kreuzberg-config-test-etc-core-12345
|
||||
|
||||
# Execute command in running container
|
||||
docker exec kreuzberg-config-test-etc-core-12345 cat /etc/kreuzberg/kreuzberg.toml
|
||||
|
||||
# Stop container manually
|
||||
docker stop kreuzberg-config-test-etc-core-12345
|
||||
docker rm kreuzberg-config-test-etc-core-12345
|
||||
```
|
||||
|
||||
### Check Health Endpoint Manually
|
||||
|
||||
```bash
|
||||
# Start container manually
|
||||
docker run -d \
|
||||
--name test-container \
|
||||
-p 8000:8000 \
|
||||
-v /path/to/config.toml:/etc/kreuzberg/kreuzberg.toml:ro \
|
||||
kreuzberg:full
|
||||
|
||||
# Wait for startup
|
||||
sleep 3
|
||||
|
||||
# Test health endpoint
|
||||
curl -v http://localhost:8000/health
|
||||
|
||||
# View logs
|
||||
docker logs test-container
|
||||
|
||||
# Cleanup
|
||||
docker stop test-container
|
||||
docker rm test-container
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Docker Not Found
|
||||
|
||||
```text
|
||||
[ERROR] Docker is not installed or not in PATH
|
||||
```
|
||||
|
||||
**Solution**: Install Docker or ensure it's in your PATH
|
||||
|
||||
```bash
|
||||
which docker
|
||||
export PATH=$PATH:/usr/local/bin # or wherever docker is installed
|
||||
```
|
||||
|
||||
### Docker Daemon Not Running
|
||||
|
||||
```text
|
||||
[ERROR] Docker daemon is not running or you don't have permissions
|
||||
```
|
||||
|
||||
**Solution**: Start Docker
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
open -a Docker
|
||||
|
||||
# Linux
|
||||
sudo systemctl start docker
|
||||
|
||||
# Check status
|
||||
docker ps
|
||||
```
|
||||
|
||||
### Image Not Found
|
||||
|
||||
```text
|
||||
[WARN] Skipping tests for variant: full (image not found)
|
||||
```
|
||||
|
||||
**Solution**: Build the image
|
||||
|
||||
```bash
|
||||
docker build -f docker/Dockerfile.full -t kreuzberg:full .
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```text
|
||||
[FAIL] Test failed: Failed to start container
|
||||
[FAIL] Details: port is already allocated
|
||||
```
|
||||
|
||||
**Solution**: Free the ports or wait for existing tests to finish
|
||||
|
||||
```bash
|
||||
# Find what's using the ports
|
||||
lsof -i :18100-18199
|
||||
|
||||
# Or just stop all test containers
|
||||
docker ps -a --filter "name=kreuzberg-config-test" --format "{{.Names}}" | \
|
||||
xargs -r docker stop
|
||||
```
|
||||
|
||||
### Health Check Timeout
|
||||
|
||||
```text
|
||||
[FAIL] Test failed: Service failed to start (health check timeout)
|
||||
```
|
||||
|
||||
**Debugging**:
|
||||
|
||||
1. Check container is still running:
|
||||
|
||||
```bash
|
||||
docker ps | grep kreuzberg-config-test
|
||||
```
|
||||
|
||||
2. View container logs:
|
||||
|
||||
```bash
|
||||
docker logs <container-name>
|
||||
```
|
||||
|
||||
3. Check if service is binding to port:
|
||||
|
||||
```bash
|
||||
docker exec <container-name> netstat -tuln | grep 8000
|
||||
```
|
||||
|
||||
4. Increase timeout (edit script):
|
||||
|
||||
```bash
|
||||
TIMEOUT_SECONDS=60 # Change from 30
|
||||
```
|
||||
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Docker Config Tests
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Build Docker images
|
||||
run: |
|
||||
docker build -f docker/Dockerfile.core -t kreuzberg:core .
|
||||
docker build -f docker/Dockerfile.full -t kreuzberg:full .
|
||||
|
||||
- name: Run configuration tests
|
||||
run: ./scripts/test/test-docker-config-local.sh --variant all
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
docker-config-tests:
|
||||
stage: test
|
||||
image: docker:latest
|
||||
services:
|
||||
- docker:dind
|
||||
script:
|
||||
- docker build -f docker/Dockerfile.core -t kreuzberg:core .
|
||||
- docker build -f docker/Dockerfile.full -t kreuzberg:full .
|
||||
- ./scripts/test/test-docker-config-local.sh --variant all
|
||||
```
|
||||
|
||||
## Performance Expectations
|
||||
|
||||
| Metric | Time |
|
||||
| ------------------------- | -------------- |
|
||||
| Single test | 2-5 seconds |
|
||||
| All 8 tests (1 variant) | 30-45 seconds |
|
||||
| All 16 tests (2 variants) | 60-90 seconds |
|
||||
| With verbose output | +10-20 seconds |
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | Meaning |
|
||||
| ---- | ---------------------------------------------- |
|
||||
| 0 | All tests passed |
|
||||
| 1 | One or more tests failed OR Docker unavailable |
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Environment Variables
|
||||
|
||||
```bash
|
||||
# Override variant via environment
|
||||
TEST_VARIANT=core ./scripts/test/test-docker-config-local.sh
|
||||
|
||||
# Override verbose via environment
|
||||
VERBOSE=true ./scripts/test/test-docker-config-local.sh
|
||||
```
|
||||
|
||||
### Modify Timeout
|
||||
|
||||
Edit the script to change timeout:
|
||||
|
||||
```bash
|
||||
TIMEOUT_SECONDS=60 # Line ~43, change from 30
|
||||
```
|
||||
|
||||
### Test Specific Scenarios
|
||||
|
||||
To test only one specific scenario, modify the `run_test_suite()` call in `main()`:
|
||||
|
||||
```bash
|
||||
# Comment out unwanted tests
|
||||
# test_etc_kreuzberg_mount "$variant"
|
||||
test_app_config_mount "$variant"
|
||||
# test_custom_path_with_flag "$variant"
|
||||
# ... etc
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
```bash
|
||||
./scripts/test/test-docker-config-local.sh --help
|
||||
```
|
||||
|
||||
For detailed documentation:
|
||||
|
||||
```bash
|
||||
cat ./scripts/test/README.md
|
||||
```
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Script**: `./scripts/test/test-docker-config-local.sh`
|
||||
- **Documentation**: `./scripts/test/README.md`
|
||||
- **This Guide**: `./scripts/test/USAGE.md`
|
||||
- **Docker Files**: `./docker/Dockerfile.core`
|
||||
- **Docker Files**: `./docker/Dockerfile.full`
|
||||
Reference in New Issue
Block a user