piscal/README-Docker.md

# PISCAL Docker Build Guide

This guide explains how to build and run PISCAL Docker images.

## Prerequisites

- Docker installed and running
- Git (for version tagging)
- PowerShell (Windows) or Bash (Linux/Mac)

## Building the Image

**Windows (PowerShell):**
```powershell
.\build-docker.ps1
```

**Linux/Mac (Bash):**
```bash
./build-docker.sh
```

The build script automatically creates a versioned image with:
- `piscal:YYYYMMDD-gitsha` (e.g., `piscal:20260316-216cd3f`)
- `piscal:latest`
- `piscal:dev`

## Default Credentials

The image is built with default credentials:

- **Username:** `piscaladmin`
- **Password:** `piscaladmin`
- **Storage Path:** `/home/piscaladmin/LeafWeb_storage`

**Security Note:** Change the password after deployment for production use. You can change it by:
- SSHing into the container and running: `passwd piscaladmin`
- Or rebuilding with custom credentials using Docker build arguments (see Advanced section)

## Running the Container

```bash
# Start container
docker run -d -p 2222:22 --name piscal-server piscal:latest

# SSH into container
ssh -p 2222 piscaladmin@localhost
# Password: piscaladmin

# Stop and remove
docker stop piscal-server
docker rm piscal-server
```

## Container Configuration

### Build Arguments

The Dockerfile accepts these build arguments if you need to customize:

| Argument | Default | Description |
|----------|---------|-------------|
| `SSH_USERNAME` | `piscaladmin` | SSH username for container access |
| `SSH_PASSWORD` | `piscaladmin` | SSH password for container access |
| `SSH_GROUP` | `piscaladmin` | Primary group for SSH user |
| `STORAGE_PATH` | `/home/piscaladmin/LeafWeb_storage` | Storage directory for PISCAL data |
| `PISCAL_EXECUTABLE` | `/srv/piscal` | Path to PISCAL executable |

### Storage Directory Structure

The storage directory is automatically created with:

```
/home/piscaladmin/LeafWeb_storage/
├── input/       # Input files for processing
└── output/      # Results from PISCAL processing
```

### Port Mapping

- Container exposes port `22` for SSH
- Map to host port as needed: `-p <host_port>:22`
- Default examples use port `2222` to avoid conflicts with host SSH

## Advanced Usage

### Custom Credentials at Build Time

If you need different credentials, use Docker build arguments:

```bash
docker build \
  --build-arg SSH_USERNAME=customuser \
  --build-arg SSH_PASSWORD=custompass \
  -t piscal:custom \
  .
```

### Custom Storage Path

```bash
docker build \
  --build-arg STORAGE_PATH=/data/piscal \
  -t piscal:custom \
  .
```

### Mounting External Storage

Mount a host directory for persistent storage:

```bash
docker run -d -p 2222:22 \
  -v /path/on/host:/home/piscaladmin/LeafWeb_storage \
  --name piscal-server \
  piscal:latest
```

## Troubleshooting

### Build Issues

**Problem:** Docker build fails with "permission denied"
```bash
# Solution: Ensure Docker daemon is running
docker ps
```

**Problem:** Git not found during build
```bash
# Solution: Install git or build without versioning
docker build -t piscal:latest .
```

### Runtime Issues

**Problem:** Cannot SSH into container
```bash
# Check if container is running
docker ps

# Check container logs
docker logs piscal-server

# Verify SSH service
docker exec piscal-server service ssh status
```

**Problem:** Storage directory permission errors
```bash
# Verify ownership inside container
docker exec piscal-server ls -la /home/piscaladmin/LeafWeb_storage
```

**Problem:** Port conflict on 2222
```bash
# Use a different port
docker run -d -p 2223:22 --name piscal-server piscal:latest
ssh -p 2223 piscaladmin@localhost
```

## Version Management

### Listing Images

```bash
docker images | grep piscal
```

### Removing Old Images

```bash
# Remove specific version
docker rmi piscal:20260316-216cd3f

# Remove all except latest
docker images | grep piscal | grep -v latest | awk '{print $3}' | xargs docker rmi
```

## Security Best Practices

### 1. Change Default Password

After deploying, always change the default password:

```bash
# SSH into container
ssh -p 2222 piscaladmin@localhost

# Change password
passwd piscaladmin
```

### 2. Use SSH Keys

For better security, disable password authentication and use SSH keys:

```bash
# Copy your public key to the container
ssh-copy-id -p 2222 piscaladmin@localhost

# Disable password authentication (optional)
docker exec piscal-server sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
docker exec piscal-server service ssh restart
```

### 3. Firewall Rules

Restrict SSH access with firewall rules:

```bash
# Example: Allow only from specific IP
iptables -A INPUT -p tcp -s 192.168.1.100 --dport 2222 -j ACCEPT
iptables -A INPUT -p tcp --dport 2222 -j DROP
```

### 4. Environment Variables for Secrets

Store credentials as environment variables instead of hardcoding:

```bash
export PISCAL_USER="piscaladmin"
export PISCAL_PASS="secure_password"

docker build \
  --build-arg SSH_USERNAME="$PISCAL_USER" \
  --build-arg SSH_PASSWORD="$PISCAL_PASS" \
  -t piscal:latest .
```

## Integration with CI/CD

### Example: GitHub Actions

```yaml
name: Build PISCAL Docker Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Build Docker image
        run: ./build-docker.sh

      - name: Push to registry
        run: |
          docker tag piscal:latest myregistry/piscal:latest
          docker push myregistry/piscal:latest
```

### Example: Jenkins

```groovy
pipeline {
    agent any

    stages {
        stage('Build') {
            steps {
                sh './build-docker.sh'
            }
        }

        stage('Deploy') {
            steps {
                sh 'docker tag piscal:latest myregistry/piscal:latest'
                sh 'docker push myregistry/piscal:latest'
            }
        }
    }
}
```

## Additional Resources

- [Docker Documentation](https://docs.docker.com/)
- [Docker Security Best Practices](https://docs.docker.com/engine/security/)
- [SSH Hardening Guide](https://www.ssh.com/academy/ssh/security)

## Support

For issues or questions:
1. Check the troubleshooting section above
2. Review container logs: `docker logs piscal-server`
3. Inspect container: `docker exec -it piscal-server /bin/bash`