Add logo, rename start-media-server.sh, first release!

2026-02-03 17:12:55 -05:00 · 2026-02-03 17:12:55 -05:00 · ac34431a12
commit ac34431a12
parent 829b8990a1
4 changed files with 299 additions and 6 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,292 @@
+# FREAX Web Media Player
+
+![freaxlogo](freaxlogo.png)
+
+**FREAX** is a lightweight, self-hosted web media player built with PHP and FrankenPHP.
+
+It is designed to be:
+
+- Minimal
+- Dependency-light
+- Filesystem-native
+- Streaming-friendly
+- LAN-first with WAN support via HTTPS
+
+FREAX intentionally avoids metadata scraping, database backends, and transcoding pipelines. It simply enumerates directories, validates media types, and streams files directly.
+
+This makes it ideal for:
+
+- Pre-encoded MP4 media libraries
+- DVD rips
+- YouTube archive collections
+- Home NAS mounts
+- CIFS / NFS mounted media shares
+
+---
+
+## Philosophy
+
+FREAX follows classic Unix design principles:
+
+- Use filesystem primitives
+- Avoid unnecessary services
+- Prefer explicit configuration
+- No database dependency
+- No background daemons
+- No metadata scraping
+- No automatic transcoding
+
+If your files already play in a browser, FREAX will stream them.
+
+---
+
+## Requirements
+
+### Server
+
+- Linux (recommended)
+- FrankenPHP
+- PHP CLI or FrankenPHP php-cli (for password hashing)
+- Bash (for startup script)
+
+### Media Format
+
+Recommended formats:
+
+- MP4 (H.264 / H.265)
+- AAC / MP3 audio
+- Web-compatible containers
+
+FREAX does **not** transcode. You should pre-encode media using tools such as:
+
+- ffmpeg
+- HandBrake
+
+---
+
+## Directory Layout
+
+Your media root should contain:
+
+```
+
+MEDIA_ROOT/
+├── Videos/
+│   ├── TV/
+│   └── Movies/
+└── Music/
+    ├── Artist/
+        └── Albums/
+
+```
+
+These are enumerated directly from disk.
+
+No database indexing is used.
+
+---
+
+## Starting the Server
+
+FREAX ships with a Bash launcher that:
+
+- Sets credentials via environment variables
+- Hashes passwords using bcrypt
+- Starts FrankenPHP
+- Avoids storing secrets on disk
+
+### Script
+
+Use:
+
+```
+
+start-media-server.sh
+
+````
+
+### Example (Prompt for Password)
+
+```bash
+./start-media-server.sh \
+  --user admin \
+  --prompt \
+  --media-root /mnt/media \
+  --port 9000 
+````
+
+---
+
+## Environment Variables
+
+The launcher exports:
+
+| Variable        | Purpose                                      |
+| --------------- | -------------------------------------------- |
+| MEDIA_USER      | Login username                               |
+| MEDIA_PASS_HASH | bcrypt password hash                         |
+| MEDIA_ROOT      | Base directory containing Videos/ and Music/ |
+
+Credentials are **not stored on disk**.
+
+They exist only in the running server environment.
+
+---
+
+## LAN Usage
+
+For local network usage:
+
+```
+http://server-ip:9000
+```
+
+This works for testing and LAN streaming.
+
+---
+
+## WAN Usage (HTTPS Required)
+
+When exposing FREAX over the internet, **HTTPS is mandatory**.
+
+Authentication cookies are issued with:
+
+* `'secure'   => true`
+* Scoped cookie path
+
+Browsers will refuse to store session cookies over plain HTTP.
+
+This prevents:
+
+* Credential leakage
+* Session hijacking
+* Insecure deployments
+
+This behavior is intentional.
+
+---
+
+## Reverse Proxy Example (Apache HTTPS)
+
+If exposing FREAX publicly, terminate TLS at Apache (or another proxy/webserver):
+
+```apache
+ProxyPass        /mediaserv/  http://youriphere:9000/
+ProxyPassReverse /mediaserv/  http://youriphere:9000/
+
+RequestHeader set X-Forwarded-Proto "https"
+RequestHeader set X-Forwarded-Ssl on
+```
+
+This ensures:
+
+* HTTPS detection works correctly
+* Secure cookies are accepted
+* Sessions persist properly
+
+---
+
+## Cookie Configuration
+
+Cookie behavior is configured in:
+
+```
+auth.php
+```
+
+Defaults:
+
+* Secure cookies enabled
+* `/` cookie path
+* Session-based authentication
+
+You **can** disable secure cookies for LAN testing, but this is strongly discouraged for WAN deployments.
+
+FREAX is secure-by-default.
+
+---
+
+## Playback Features
+
+Current features:
+
+* Folder-based browsing
+* Automatic episode ordering
+* Continuous playback (auto-play next file)
+* HTML5 audio/video playback
+* Lightweight UI
+* Keyboard / remote-friendly controls
+
+---
+
+## Security Model
+
+FREAX intentionally minimizes attack surface:
+
+* No SQL backend
+* No upload endpoints
+* No file writes
+* No user content creation
+* No dynamic code execution
+* Strict base directory enforcement
+* MIME validation
+* Extension filtering
+* Realpath containment checks
+
+Media access is read-only and authenticated.
+
+---
+
+## Why FREAX Instead of Plex/Jellyfin?
+
+FREAX avoids:
+
+* Metadata matching failures
+* Transcoding overhead
+* Database maintenance
+* Framework dependency chains
+* Heavy background services
+* Cloud integration requirements
+
+It is designed for users who:
+
+* Control their own encoding pipeline
+* Understand filesystem mounts
+* Want predictable behavior
+* Prefer minimal infrastructure
+
+---
+
+## Name Origin
+
+**FREAX** is a playful nod to:
+
+* Linus Torvalds' original Linux codename ("Freax")
+* "Free" software philosophy
+* A lightweight alternative to Plex-style platforms
+
+---
+
+## License
+
+Open source.
+
+Use it, fork it, modify it, self-host it.
+
+---
+
+## Disclaimer
+
+FREAX is intended for personal media servers.
+
+You are responsible for:
+
+* Network exposure
+* Firewall rules
+* TLS configuration
+* Legal compliance for your hosted media, this isn't a piracy site kit, so don't ask for help for that. 
+
+---
+
+Happy hacking.
+