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

.\build-docker.ps1

Linux/Mac (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

# 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	/home/piscaladmin/piscal_executable/piscal	Path to PISCAL executable

v1 Directory Layout (VM-compatible)

The image uses the v1 layout expected by the LeafWeb client:

/home/piscaladmin/
├── LeafWeb/                      # Scripts + project directories
│   ├── piscal_launcher.cfg
│   ├── piscal_launcher.sh
│   ├── piscal_manager.sh
│   ├── subdir_year.sh
│   ├── README.txt
│   └── <project_name>/            # Job dirs (e.g. 280_CinnamomumbodinieriLévl)
├── LeafWeb_storage/
│   ├── input/
│   └── output/
└── piscal_executable/
    └── piscal

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

Baking In a Production Password

To use a custom password without passing it on the command line:

Option 1: .piscal-build.env (recommended)

cp .piscal-build.env.example .piscal-build.env
# Edit .piscal-build.env and set: PISCAL_SSH_PASSWORD=your_secure_password
./build-docker.sh   # or .\build-docker.ps1

The build scripts automatically load .piscal-build.env (gitignored) and pass the password to the Docker build.

Option 2: Environment variable

export PISCAL_SSH_PASSWORD="your_secure_password"
./build-docker.sh

Option 3: Direct build-arg

docker build --build-arg SSH_PASSWORD=custompass -t piscal:custom .

Custom Storage Path

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

Mounting External Storage

Mount a host directory for persistent storage:

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"

# Solution: Ensure Docker daemon is running
docker ps

Problem: Git not found during build

# Solution: Install git or build without versioning
docker build -t piscal:latest .

Runtime Issues

Problem: Cannot SSH into container

# 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

# Verify ownership inside container
docker exec piscal-server ls -la /home/piscaladmin/LeafWeb_storage

Problem: Port conflict on 2222

# Use a different port
docker run -d -p 2223:22 --name piscal-server piscal:latest
ssh -p 2223 piscaladmin@localhost

Version Management

Listing Images

docker images | grep piscal

Removing Old Images

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

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

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

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

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

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

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
• Docker Security Best Practices
• SSH Hardening Guide

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