adding phase 5 init framework, added deployment ease scripts

2025-11-18 13:10:53 -06:00
parent b2a3fc7832
commit 131e1f5a61
19 changed files with 2458 additions and 82 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -74,6 +74,31 @@ docker compose version

 For users who want to get started immediately with the web application:

+**Option 1: Automated Setup (Recommended)**
+
+```bash
+# 1. Clone the repository
+git clone <repository-url>
+cd SneakyScan
+
+# 2. Run the setup script
+./setup.sh
+
+# 3. Access the web interface
+# Open browser to: http://localhost:5000
+# Login with password from ./admin_password.txt or ./logs/admin_password.txt
+```
+
+The setup script automatically:
+- Generates secure random keys (SECRET_KEY, ENCRYPTION_KEY)
+- Prompts for password or generates a random one
+- Creates required directories
+- Builds Docker image
+- Starts the application
+- Auto-initializes database on first run
+
+**Option 2: Manual Setup**
+
 ```bash
 # 1. Clone the repository
 git clone <repository-url>
@@ -82,18 +107,17 @@ cd SneakyScan
 # 2. Create environment file
 cp .env.example .env
 # Edit .env and set SECRET_KEY and SNEAKYSCANNER_ENCRYPTION_KEY
+# Optionally set INITIAL_PASSWORD (leave blank for auto-generation)
 nano .env

-# 3. Build the Docker image
-docker compose build
+# 3. Build and start (database auto-initializes on first run)
+docker compose up --build -d

-# 4. Initialize the database and set password
-docker compose run --rm init-db --password "YourSecurePassword"
+# 4. Check logs for auto-generated password (if not set in .env)
+docker compose logs web | grep "Password"
+# Or check: ./logs/admin_password.txt

-# 5. Start the application
-docker compose up -d
-
-# 6. Access the web interface
+# 5. Access the web interface
 # Open browser to: http://localhost:5000
 ```

@@ -126,7 +150,10 @@ SneakyScanner is configured via environment variables. The recommended approach
 cp .env.example .env

 # Generate secure keys
+# SECRET_KEY: Flask session secret (64-character hex string)
 python3 -c "import secrets; print('SECRET_KEY=' + secrets.token_hex(32))" >> .env
+
+# SNEAKYSCANNER_ENCRYPTION_KEY: Fernet key for database encryption (32 url-safe base64 bytes)
 python3 -c "from cryptography.fernet import Fernet; print('SNEAKYSCANNER_ENCRYPTION_KEY=' + Fernet.generate_key().decode())" >> .env

 # Edit other settings as needed
@@ -142,6 +169,7 @@ nano .env
 | `SECRET_KEY` | Flask session secret (change in production!) | `dev-secret-key-change-in-production` | **Yes** |
 | `SNEAKYSCANNER_ENCRYPTION_KEY` | Encryption key for sensitive settings | (empty) | **Yes** |
 | `DATABASE_URL` | SQLite database path | `sqlite:////app/data/sneakyscanner.db` | Yes |
+| `INITIAL_PASSWORD` | Password for first-run initialization (leave empty to auto-generate) | (empty) | No |
 | `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | `INFO` | No |
 | `SCHEDULER_EXECUTORS` | Number of concurrent scan threads | `2` | No |
 | `SCHEDULER_JOB_DEFAULTS_MAX_INSTANCES` | Max instances of same job | `3` | No |
@@ -223,28 +251,56 @@ docker images | grep sneakyscanner

 ### Step 4: Initialize Database

-The database must be initialized before first use. The init-db service uses a profile, so you need to explicitly run it:
+**Automatic Initialization (Recommended)**
+
+As of Phase 5, the database is automatically initialized on first run:
+
+```bash
+# Just start the application
+docker compose up -d
+
+# On first run, the entrypoint script will:
+# - Detect no existing database
+# - Generate a random password (if INITIAL_PASSWORD not set in .env)
+# - Save password to ./logs/admin_password.txt
+# - Initialize database schema
+# - Create default settings and alert rules
+# - Start the Flask application
+
+# Check logs to see the auto-generated password
+docker compose logs web | grep "Password"
+
+# Or view the password file
+cat logs/admin_password.txt
+```
+
+**Manual Initialization (Advanced)**
+
+You can still manually initialize the database if needed:

 ```bash
 # Initialize database and set application password
-docker compose -f docker-compose.yml run --rm init-db --password "YourSecurePassword"
+docker compose run --rm init-db --password "YourSecurePassword" --force

 # The init-db command will:
 # - Create database schema
-# - Run all Alembic migrations
 # - Set the application password (bcrypt hashed)
 # - Create default settings with encryption
+# - Create default alert rules

 # Verify database was created
 ls -lh data/sneakyscanner.db
 ```

-**Password Requirements:**
+**Password Management:**
+- Leave `INITIAL_PASSWORD` blank in `.env` for auto-generation
+- Auto-generated passwords are saved to `./logs/admin_password.txt`
+- For custom password, set `INITIAL_PASSWORD` in `.env`
 - Minimum 8 characters recommended
 - Use a strong, unique password
 - Store securely (password manager)

-**Note**: The init-db service is defined with `profiles: [tools]` in docker-compose.yml, which means it won't start automatically with `docker compose up`.
+**Note**: The init-db service is defined with `profiles: [tools]` in docker-compose.yml, which means it won't start automatically with `docker compose up`. However, the web service now handles initialization automatically via the entrypoint script.

 ### Step 5: Verify Configuration

@@ -699,17 +755,25 @@ tail -f logs/sneakyscanner.log

 ```bash
 # Check logs for errors
-docker compose -f docker-compose.yml logs web
+docker compose logs web

 # Common issues:
-# 1. Database not initialized - run init-db first
-# 2. Permission issues with volumes - check directory ownership
-# 3. Port 5000 already in use - change FLASK_PORT or stop conflicting service
+# 1. Permission issues with volumes - check directory ownership
+# 2. Port 5000 already in use - change FLASK_PORT or stop conflicting service
+# 3. Database initialization failed - check logs for specific error
+
+# Check if database initialization is stuck
+docker compose logs web | grep -A 20 "First Run Detected"
+
+# If initialization failed, clean up and retry
+docker compose down
+rm -rf data/.db_initialized  # Remove marker file
+docker compose up -d
 ```

 ### Database Initialization Fails

-**Problem**: `init_db.py` fails with errors
+**Problem**: Automatic database initialization fails on first run

 ```bash
 # Check database directory permissions
@@ -718,12 +782,37 @@ ls -la data/
 # Fix permissions if needed
 sudo chown -R $USER:$USER data/

-# Verify SQLite is accessible
-sqlite3 data/sneakyscanner.db "SELECT 1;" 2>&1
+# View initialization logs
+docker compose logs web | grep -A 50 "Initializing database"

-# Remove corrupted database and reinitialize
-rm data/sneakyscanner.db
-docker compose -f docker-compose.yml run --rm init-db --password "YourPassword"
+# Clean up and retry initialization
+docker compose down
+rm -rf data/sneakyscanner.db data/.db_initialized
+docker compose up -d
+
+# Or manually initialize with specific password
+docker compose down
+rm -rf data/sneakyscanner.db data/.db_initialized
+docker compose run --rm init-db --password "YourPassword" --force
+docker compose up -d
+```
+
+**Can't Find Password File**
+
+**Problem**: Password file not created or can't be found
+
+```bash
+# Check both possible locations
+cat admin_password.txt      # Created by setup.sh
+cat logs/admin_password.txt  # Created by Docker entrypoint
+
+# Check container logs for password
+docker compose logs web | grep -i password
+
+# If password file is missing, manually set one
+docker compose down
+docker compose run --rm init-db --password "YourNewPassword" --force
+docker compose up -d
 ```

 ### Scans Fail with "Permission Denied"