Version 3.0.2 full expirimental DCT support, jpegio for better jpg manipulation, etc.
This commit is contained in:
Aaron D. Lee
712
INSTALL.md
Normal file
712
INSTALL.md
Normal file
@@ -0,0 +1,712 @@
|
||||
# Stegasoo Installation Guide
|
||||
|
||||
Complete installation instructions for all platforms and deployment methods.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Requirements](#requirements)
|
||||
- [Quick Install](#quick-install)
|
||||
- [Installation Methods](#installation-methods)
|
||||
- [From Source (Development)](#from-source-development)
|
||||
- [From PyPI](#from-pypi)
|
||||
- [Docker](#docker)
|
||||
- [Docker Compose](#docker-compose)
|
||||
- [Optional Dependencies](#optional-dependencies)
|
||||
- [DCT Steganography (scipy + jpegio)](#dct-steganography-scipy--jpegio)
|
||||
- [Compression (lz4)](#compression-lz4)
|
||||
- [Platform-Specific Notes](#platform-specific-notes)
|
||||
- [Verification](#verification)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Minimum Requirements
|
||||
|
||||
| Requirement | Version |
|
||||
|-------------|---------|
|
||||
| Python | 3.10+ |
|
||||
| RAM | 512 MB minimum (256MB for Argon2) |
|
||||
| Disk | ~100 MB |
|
||||
|
||||
### System Dependencies
|
||||
|
||||
**Linux (Debian/Ubuntu):**
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y \
|
||||
python3 \
|
||||
python3-pip \
|
||||
python3-dev \
|
||||
libzbar0 \
|
||||
libjpeg-dev \
|
||||
build-essential
|
||||
```
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
brew install python@3.11 zbar jpeg
|
||||
xcode-select --install # For compilation
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
- Install Python 3.10+ from [python.org](https://python.org)
|
||||
- Install Visual Studio Build Tools for compilation
|
||||
|
||||
---
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name stegasoo-web \
|
||||
-p 5000:5000 \
|
||||
--memory=768m \
|
||||
stegasoo-web
|
||||
|
||||
# Visit http://localhost:5000
|
||||
```
|
||||
|
||||
#### Run REST API
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name stegasoo-api \
|
||||
-p 8000:8000 \
|
||||
--memory=768m \
|
||||
stegasoo-api
|
||||
|
||||
# Docs at http://localhost:8000/docs
|
||||
```
|
||||
|
||||
#### Run CLI
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# 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:
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
sudo apt-get install -y \
|
||||
build-essential \
|
||||
python3-dev \
|
||||
libjpeg-dev \
|
||||
cython3
|
||||
```
|
||||
|
||||
#### macOS Build Dependencies
|
||||
|
||||
```bash
|
||||
brew install jpeg cython
|
||||
```
|
||||
|
||||
#### Verify DCT Support
|
||||
|
||||
```python
|
||||
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:
|
||||
|
||||
```bash
|
||||
pip install lz4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Notes
|
||||
|
||||
### Linux
|
||||
|
||||
Most straightforward installation. Use your package manager for system dependencies.
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
sudo apt-get install python3-dev libzbar0 libjpeg-dev
|
||||
pip install stegasoo[all]
|
||||
```
|
||||
|
||||
**Fedora/RHEL:**
|
||||
```bash
|
||||
sudo dnf install python3-devel zbar libjpeg-devel
|
||||
pip install stegasoo[all]
|
||||
```
|
||||
|
||||
**Arch:**
|
||||
```bash
|
||||
sudo pacman -S python zbar libjpeg-turbo
|
||||
pip install stegasoo[all]
|
||||
```
|
||||
|
||||
### macOS
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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](https://python.org)
|
||||
2. Install Visual Studio Build Tools
|
||||
3. Install from pip:
|
||||
|
||||
```powershell
|
||||
pip install stegasoo[all]
|
||||
```
|
||||
|
||||
**For jpegio on Windows:**
|
||||
```powershell
|
||||
# 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):
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# CLI version
|
||||
stegasoo --version
|
||||
|
||||
# Python import
|
||||
python -c "import stegasoo; print(stegasoo.__version__)"
|
||||
```
|
||||
|
||||
### Check All Features
|
||||
|
||||
```python
|
||||
#!/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:
|
||||
```bash
|
||||
python check_install.py
|
||||
```
|
||||
|
||||
### Test Encoding/Decoding
|
||||
|
||||
```bash
|
||||
# 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'"
|
||||
|
||||
```bash
|
||||
# Ensure you're in the right environment
|
||||
which python
|
||||
pip list | grep stegasoo
|
||||
|
||||
# Reinstall
|
||||
pip install -e ".[all]"
|
||||
```
|
||||
|
||||
#### "Argon2 not available"
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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](README.md)
|
||||
- [CLI.md](CLI.md)
|
||||
- [API.md](API.md)
|
||||
- [WEB_UI.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](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! 🦕
|
||||
Reference in New Issue
Block a user