stegasoo/INSTALL.md

Stegasoo Installation Guide

Complete installation instructions for all platforms and deployment methods.

Table of Contents

• Requirements
• Quick Install
• Installation Methods
  • From Source (Development)
  • From PyPI
  • Docker
  • Docker Compose
• Optional Dependencies
  • DCT Steganography (scipy + jpegio)
  • Compression (lz4)
• Platform-Specific Notes
• Verification
• Troubleshooting

---

Requirements

Minimum Requirements

Requirement	Version
Python	3.10+
RAM	512 MB minimum (256MB for Argon2)
Disk	~100 MB

System Dependencies

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install -y \
  python3 \
  python3-pip \
  python3-dev \
  libzbar0 \
  libjpeg-dev \
  build-essential

macOS:

brew install python@3.11 zbar jpeg
xcode-select --install  # For compilation

Windows:

• Install Python 3.10+ from python.org
• Install Visual Studio Build Tools for compilation

---

Quick Install

# Clone and install everything
git clone https://github.com/adlee-was-taken/stegasoo.git
cd stegasoo
pip install -e ".[all]"

# Verify
stegasoo --version

---

Installation Methods

From Source (Development)

Best for development or customization.

# Clone the repository
git clone https://github.com/adlee-was-taken/stegasoo.git
cd stegasoo

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Linux/macOS
# or: venv\Scripts\activate  # Windows

# Install core library only
pip install -e .

# Install with specific extras
pip install -e ".[cli]"       # Command-line interface
pip install -e ".[web]"       # Flask web UI + DCT support
pip install -e ".[api]"       # FastAPI REST API + DCT support
pip install -e ".[dct]"       # DCT steganography only
pip install -e ".[compression]"  # LZ4 compression

# Install everything
pip install -e ".[all]"

# Install with development tools
pip install -e ".[dev]"

From PyPI

# Core only
pip install stegasoo

# With extras
pip install stegasoo[cli]
pip install stegasoo[web]
pip install stegasoo[api]
pip install stegasoo[all]

Docker

Build and run individual containers.

Build Images

# Build all targets
docker build -t stegasoo-web --target web .
docker build -t stegasoo-api --target api .
docker build -t stegasoo-cli --target cli .

Run Web UI

docker run -d \
  --name stegasoo-web \
  -p 5000:5000 \
  --memory=768m \
  stegasoo-web

# Visit http://localhost:5000

Run REST API

docker run -d \
  --name stegasoo-api \
  -p 8000:8000 \
  --memory=768m \
  stegasoo-api

# Docs at http://localhost:8000/docs

Run CLI

# Interactive shell
docker run -it --rm stegasoo-cli /bin/bash

# Run commands directly
docker run --rm stegasoo-cli --help
docker run --rm stegasoo-cli generate --pin --words 3

# With volume for files
docker run --rm \
  -v $(pwd)/images:/data \
  stegasoo-cli encode \
    -r /data/ref.jpg \
    -c /data/carrier.png \
    -p "phrase words here" \
    --pin 123456 \
    -m "Secret message" \
    -o /data/stego.png

Docker Compose

The easiest way to run all services.

Start All Services

# Start in background
docker-compose up -d

# Start specific service
docker-compose up -d web
docker-compose up -d api

# View logs
docker-compose logs -f

# Stop all
docker-compose down

Services

Service	URL	Description
web	http://localhost:5000	Flask Web UI
api	http://localhost:8000	FastAPI REST API

Build and Start

# Build images and start
docker-compose up -d --build

# Force rebuild (no cache)
docker-compose build --no-cache
docker-compose up -d

Resource Configuration

The docker-compose.yml includes resource limits:

services:
  web:
    deploy:
      resources:
        limits:
          memory: 768M    # For Argon2 + scipy
        reservations:
          memory: 384M

Adjust based on your available RAM:

Available RAM	Recommended Limit	Workers
2 GB	768M	2
4 GB	1G	3
8 GB+	1.5G	4

Development Mode

For development with hot-reload:

# Create docker-compose.override.yml
cat > docker-compose.override.yml << 'EOF'
version: '3.8'
services:
  web:
    volumes:
      - ./src:/app/src:ro
      - ./frontends/web:/app/frontends/web:ro
    environment:
      - FLASK_ENV=development
    command: ["python", "app.py"]
  api:
    volumes:
      - ./src:/app/src:ro
      - ./frontends/api:/app/frontends/api:ro
    command: ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
EOF

# Start with override
docker-compose up

Production with Nginx

For production deployment with SSL:

# docker-compose.prod.yml
version: '3.8'

services:
  web:
    build:
      context: .
      target: web
    expose:
      - "5000"
    restart: always

  api:
    build:
      context: .
      target: api
    expose:
      - "8000"
    restart: always

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - web
      - api
    restart: always

Run with:

docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

---

Optional Dependencies

DCT Steganography (scipy + jpegio)

DCT mode enables JPEG-resilient steganography. It's automatically included with [web], [api], and [all] extras.

Install via pip

# scipy is straightforward
pip install scipy

# jpegio - try pip first
pip install jpegio

# If pip fails, build from source
pip install cython numpy
git clone https://github.com/dwgoon/jpegio.git
cd jpegio
python setup.py install

Linux Build Dependencies

sudo apt-get install -y \
  build-essential \
  python3-dev \
  libjpeg-dev \
  cython3

macOS Build Dependencies

brew install jpeg cython

Verify DCT Support

from stegasoo import has_dct_support
from stegasoo.dct_steganography import has_jpegio_support

print(f"DCT support (scipy): {has_dct_support()}")
print(f"JPEG native (jpegio): {has_jpegio_support()}")

Expected output:

DCT support (scipy): True
JPEG native (jpegio): True

Compression (lz4)

Optional LZ4 compression for messages:

pip install lz4

---

Platform-Specific Notes

Linux

Most straightforward installation. Use your package manager for system dependencies.

Ubuntu/Debian:

sudo apt-get install python3-dev libzbar0 libjpeg-dev
pip install stegasoo[all]

Fedora/RHEL:

sudo dnf install python3-devel zbar libjpeg-devel
pip install stegasoo[all]

Arch:

sudo pacman -S python zbar libjpeg-turbo
pip install stegasoo[all]

macOS

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.11 zbar jpeg

# Install Stegasoo
pip3 install stegasoo[all]

Apple Silicon (M1/M2/M3):

jpegio may need Rosetta or native compilation:

# Try native first
pip install jpegio

# If fails, ensure you have native Python
arch -arm64 brew install python@3.11
arch -arm64 pip3 install jpegio

Windows

1. Install Python 3.10+ from python.org
2. Install Visual Studio Build Tools
3. Install from pip:

pip install stegasoo[all]

For jpegio on Windows:

# May need pre-built wheel
pip install jpegio

# If fails, install build tools and compile
pip install cython numpy
git clone https://github.com/dwgoon/jpegio.git
cd jpegio
python setup.py install

Raspberry Pi

Stegasoo works on Raspberry Pi 4 (2GB+ RAM recommended):

# System dependencies
sudo apt-get install python3-dev libzbar0 libjpeg-dev

# Install (may take a while to compile)
pip install stegasoo[cli]

# For web/api, ensure enough RAM
pip install stegasoo[web]  # Needs ~768MB free

Note: Argon2 operations will be slower on Pi due to memory-hardness.

---

Verification

Check Installation

# CLI version
stegasoo --version

# Python import
python -c "import stegasoo; print(stegasoo.__version__)"

Check All Features

#!/usr/bin/env python3
"""Verify Stegasoo installation."""

def check_feature(name, check_fn):
    try:
        result = check_fn()
        status = "✓" if result else "✗"
        print(f"  {status} {name}: {result}")
        return result
    except Exception as e:
        print(f"  ✗ {name}: Error - {e}")
        return False

print("Stegasoo Installation Check")
print("=" * 40)

# Core
import stegasoo
print(f"\nVersion: {stegasoo.__version__}")

print("\nCore Features:")
check_feature("Argon2", lambda: stegasoo.has_argon2())
check_feature("Pillow", lambda: True)  # Required, would fail import

print("\nOptional Features:")
check_feature("DCT (scipy)", stegasoo.has_dct_support)

try:
    from stegasoo.dct_steganography import has_jpegio_support
    check_feature("JPEG native (jpegio)", has_jpegio_support)
except ImportError:
    print("  ✗ JPEG native (jpegio): Not installed")

try:
    import lz4
    check_feature("Compression (lz4)", lambda: True)
except ImportError:
    print("  - Compression (lz4): Not installed (optional)")

try:
    import pyzbar
    check_feature("QR codes (pyzbar)", lambda: True)
except ImportError:
    print("  - QR codes (pyzbar): Not installed (optional)")

print("\nInterfaces:")
try:
    import click
    check_feature("CLI", lambda: True)
except ImportError:
    print("  ✗ CLI: Not installed")

try:
    import flask
    check_feature("Web UI", lambda: True)
except ImportError:
    print("  - Web UI: Not installed")

try:
    import fastapi
    check_feature("REST API", lambda: True)
except ImportError:
    print("  - REST API: Not installed")

print("\n" + "=" * 40)
print("Installation check complete!")

Save as check_install.py and run:

python check_install.py

Test Encoding/Decoding

# Quick test with CLI
stegasoo generate --pin --words 3 --json > /tmp/creds.json

# Create test image
python -c "
from PIL import Image
img = Image.new('RGB', (256, 256), 'blue')
img.save('/tmp/test_carrier.png')
img.save('/tmp/test_ref.jpg')
"

# Encode
stegasoo encode \
  -r /tmp/test_ref.jpg \
  -c /tmp/test_carrier.png \
  -p "test phrase words" \
  --pin 123456 \
  -m "Hello, Stegasoo!" \
  -o /tmp/test_stego.png

# Decode
stegasoo decode \
  -r /tmp/test_ref.jpg \
  -s /tmp/test_stego.png \
  -p "test phrase words" \
  --pin 123456

---

Troubleshooting

Common Issues

"No module named 'stegasoo'"

# Ensure you're in the right environment
which python
pip list | grep stegasoo

# Reinstall
pip install -e ".[all]"

"Argon2 not available"

# Install argon2-cffi
pip install argon2-cffi

# On Linux, may need:
sudo apt-get install libffi-dev
pip install --force-reinstall argon2-cffi

"jpegio not available" / DCT JPEG fails

# Install build dependencies first
sudo apt-get install libjpeg-dev  # Linux
brew install jpeg                  # macOS

# Then install jpegio
pip install cython numpy
pip install jpegio

# If still fails, build from source
git clone https://github.com/dwgoon/jpegio.git
cd jpegio
python setup.py install

"libzbar not found" (QR codes)

# Linux
sudo apt-get install libzbar0

# macOS
brew install zbar

# Then reinstall pyzbar
pip install --force-reinstall pyzbar

Docker: "Cannot allocate memory"

Argon2 needs 256MB per operation. Increase container memory:

# Docker run
docker run --memory=768m ...

# Docker Compose - edit docker-compose.yml
deploy:
  resources:
    limits:
      memory: 768M

Docker: Build fails on jpegio

The Dockerfile includes jpegio build dependencies. If still failing:

# Rebuild without cache
docker-compose build --no-cache

# Or build manually
docker build --no-cache -t stegasoo-web --target web .

Slow performance

• Argon2 is intentionally slow - This is a security feature
• Expected encode/decode time: 2-5 seconds
• DCT mode adds ~1-2 seconds for transforms

"Carrier image too small"

• LSB needs ~3 bits per pixel
• DCT needs ~0.25 bits per pixel
• For 50KB message: LSB needs ~136K pixels, DCT needs ~1.6M pixels
• Use larger carrier images or shorter messages

Getting Help

1. Check the documentation:

   • README.md
   • CLI.md
   • API.md
   • WEB_UI.md

2. Check existing issues on GitHub

3. Open a new issue with:

   • Python version (python --version)
   • OS and version
   • Installation method
   • Full error message
   • Steps to reproduce

---

Next Steps

After installation:

1. Generate credentials: stegasoo generate --pin --words 3
2. Read the CLI docs: CLI.md
3. Try the Web UI: cd frontends/web && python app.py
4. Explore the API: cd frontends/api && python main.py

Happy steganography! 🦕