🎮 SharewareZ v2.9.7

SharewareZ transforms any game folder into a searchable library with IGDB integration, adding cover images, screenshots, and metadata for enhanced filtering. Invite your friends securely and share your favorite games!

📢 Important Notes

• 🔄 Updating from older versions: Automatic update supported - simply overwrite files and run 'pip install -r requirements.txt' again.
• ⚠️ For versions below 2.0: Database reset required
• Run ./startweb.sh --force-setup to recreate database and run setup wizard
• ⚖️ SharewareZ promotes and encourages the legal use of software. We do not condone or support any unauthorized distribution or use of copyrighted material.
• 📝 You must install version >2.5.2 before August 2025 or lose the ability to connect to IGDB for any lookups.

✨ Core Features

📚 Game Library Management

• 🔍 Smart folder scanning & cataloging with multi-threaded processing (4 threads by default)
• ⚡ Multi-threaded image downloading and processing for faster library building
• 🖼️ Steam-style popup with screenshot galleries
• 🏷️ Advanced filtering (genre, rating, gameplay modes)
• 📁 Support for 'updates' and 'extras' folders
• 🎯 Discovery page to find new gems:
  • 🆕 Latest additions
  • ⭐ Top downloads
  • ❤️ Most favorited
  • 🏆 Highly rated games
• 🚀 Ability to play ROM files directly in browser
• 💬 Discord webhook integration (bot posts in your channel when there is a new game)

💾 Download Features

• 📦 Streaming ZIP downloads for multi-file folders (no disk storage required)
• 📄 NFO file indexing with viewer
• ⚡ Multi-threaded download processing with configurable thread count

👥 User Management

• 🛡️ Role-based access control
• 📨 Invitation system (admin-controlled)
• 🔑 Self-service password reset (requires SMTP)

⚡ Performance Features

• 🚀 Multi-threaded game scanning (4 threads by default, configurable)
• 📥 Multi-threaded image downloading (8 threads by default, configurable)
• 🔄 Chunked streaming downloads for large files
• 🌐 ASGI-based web server with uvicorn and multiple workers

🚀 Installation Guide

⚡ Install Script Method (Linux Only)

One-Command Installation:

git clone --depth 1 https://github.com/axewater/sharewarez.git
cd sharewarez
# IMPORTANT: Make install script executable first
chmod +x install-linux.sh
./install-linux.sh

The auto-installer will:

• ✅ Detect your Linux distribution automatically
• ✅ Install all prerequisites (Python, PostgreSQL, Git)
• ✅ Set up database with secure credentials
• ✅ Configure the application automatically
• ✅ Generate secure encryption keys
• ✅ Start the application when ready

Advanced Options:

# Specify custom games directory
./install-linux.sh --games-dir /path/to/games

# Development setup with extra tools including unit testing
./install-linux.sh --dev

# Skip database setup (use existing)
./install-linux.sh --no-db

# Override existing installation
./install-linux.sh --force

---

🐧 Linux Manual Install

If you prefer manual setup or the auto-installer doesn't work:

Step 1: Install Prerequisites

# Update package list
sudo apt update

# Install Python 3.11+ and pip
sudo apt install python3 python3-pip python3-venv

# Install git
sudo apt install git

# Install PostgreSQL database server
sudo apt install postgresql postgresql-contrib

# Verify installations
python3 --version
python3 -m pip --version
git --version

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

Step 2: Set up PostgreSQL

# Switch to postgres user and create database
sudo -u postgres psql

-- In PostgreSQL shell, create database and user
CREATE DATABASE sharewarez;
CREATE USER sharewarezuser WITH ENCRYPTED PASSWORD 'your_password_here';
GRANT ALL PRIVILEGES ON DATABASE sharewarez TO sharewarezuser;
\q

Step 3: Clone and Set up SharewareZ

# Clone the repository
git clone --depth 1 https://github.com/axewater/sharewarez.git
cd sharewarez

# IMPORTANT: Make shell scripts executable first
chmod +x *.sh

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
python3 -m pip install -r requirements.txt

Step 4: Configure Application

# Copy configuration files
cp config.py.example config.py
cp .env.example .env

# Edit the .env file with your settings
nano .env

Important: Update these values in your .env file:

• DATABASE_URL=postgresql://sharewarezuser:your_password_here@localhost:5432/sharewarez
• DATA_FOLDER_WAREZ=/path/to/your/games/folder
• SECRET_KEY=your_secure_random_key_here

Step 5: Start SharewareZ

# IMPORTANT: Make all shell scripts executable first
chmod +x *.sh
./startweb.sh

Step 6: Complete Setup

1. Open your browser to http://localhost:5006
2. Complete the setup wizard and create your admin account

---

🪟 Windows Manual Install

Step 1: Install Prerequisites

1. Install Python 3.11+

   • Open PowerShell as Administrator, type python (opens Microsoft Store)
   • Install Python 3.11 or download from python.org
   • ✅ Check "Add Python to PATH" during installation

2. Install Git

   • Download from Git for Windows and install with default settings

3. Install Visual C++ Build Tools

   • Download Visual Studio Build Tools
   • Install "C++ build tools" workload

4. Install PostgreSQL

   • Download from PostgreSQL for Windows
   • Install with default settings and remember the postgres user password

Step 2: Set up PostgreSQL Open pgAdmin (installed with PostgreSQL):

1. Connect to your PostgreSQL server
2. Right-click "Databases" → "Create" → "Database"
3. Name: sharewarez → Click "Save"

Step 3: Clone and Set up SharewareZ Open PowerShell and run:

# Clone the repository
git clone --depth 1 https://github.com/axewater/sharewarez.git
cd sharewarez

# Create and activate virtual environment
python -m venv venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\venv\Scripts\Activate.ps1

# Install dependencies
python -m pip install -r requirements.txt

Step 4: Configure Application

# Copy configuration files and edit
copy config.py.example config.py
copy .env.example .env
notepad .env

Important: Update these values in your .env file:

• DATABASE_URL=postgresql://postgres:your_postgres_password@localhost:5432/sharewarez
• DATA_FOLDER_WAREZ=C:\Path\To\Your\Games\Folder
• SECRET_KEY=your_secure_random_key_here

Step 5: Start SharewareZ

# Start the application
.\startweb_windows.cmd

Step 6: Complete Setup

1. Open your browser to http://localhost:5006
2. Complete the setup wizard and create your admin account

---

🐳 Docker Install

Quick Docker Setup:

# Clone the repository
git clone https://github.com/axewater/sharewarez.git
cd sharewarez

# Copy and configure environment file
cp .env.docker.example .env
# Edit .env file with your game directory path:
# DATA_FOLDER_WAREZ=/path/to/your/games

# Start with Docker Compose
docker-compose up -d

What it includes:

• ✅ Complete PostgreSQL database setup
• ✅ Automatic application configuration
• ✅ Persistent data storage
• ✅ Ready-to-use on port 5006

Step-by-step:

1. Clone repository and navigate to folder
2. Copy .env.docker.example to .env
3. Edit .env file - set DATA_FOLDER_WAREZ to your games directory
4. Run docker-compose up -d
5. Open browser to http://localhost:5006
6. Complete setup wizard and create admin account

Management commands:

# View logs
docker-compose logs -f

# Stop containers
docker-compose down

# Update to latest version
git pull && docker-compose down && docker-compose up -d --build

# Reset database (if needed)
docker-compose exec web /app/startweb-docker.sh --force-setup

---

🔧 Post-Installation

Database Reset (if needed):

• Linux: ./startweb.sh --force-setup
• Windows: .\startweb_windows.cmd --force-setup

Updating SharewareZ:

1. Stop the application (Ctrl+C)
2. git pull → pip install -r requirements.txt
3. Restart with startup script

Troubleshooting:

• Port 5006 in use: Change port in startup script or set PORT environment variable
• Database errors: Check PostgreSQL is running and credentials are correct
• Linux permissions: Ensure read access to game directories

🔧 Additional Settings

• 🌐 Default port: 5006 (configurable via PORT environment variable)
• 👥 Go the admin dashboard for further configuration

🌐 Changing the Port Number

SharewareZ runs on port 5006 by default. To change this:

For Linux/Windows installations:

1. Edit your .env file
2. Add or modify: PORT=8080 (replace 8080 with your desired port)
3. Restart SharewareZ

For Docker installations:

• Docker containers always use port 5006 internally
• The external port is mapped via docker-compose.yml (also defaults to 5006)
• To change external port, edit the ports section in docker-compose.yml

Examples:

# In .env file - run on port 8080
PORT=8080

# In .env file - run on port 3000
PORT=3000

🔧 Supported platforms to play in browser

• Most 8, 16 and 32 bit retro consoles work, see webretro repo for more full list
• PSX, Sega MS, Sega 32x not working at the moment
• Sega Saturn working on single file games and some audio issues
• Files must be unzipped. ZIP, 7z and RAR are not (yet)