https://github.com/bleedingxiko/ghosthub
A real-time media browser with chat, view sync, and optional tunnel sharing — all in a single .exe.
https://github.com/bleedingxiko/ghosthub
cloudflare-tunnel flask local-server media-server no-database open-source privacy-first pwa python realtime-chat selfhosted streaming tiktok-style websocket
Last synced: 5 months ago
JSON representation
A real-time media browser with chat, view sync, and optional tunnel sharing — all in a single .exe.
- Host: GitHub
- URL: https://github.com/bleedingxiko/ghosthub
- Owner: BleedingXiko
- License: mit
- Created: 2025-04-19T17:26:12.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-23T04:44:30.000Z (5 months ago)
- Last Synced: 2025-04-24T00:58:28.183Z (5 months ago)
- Topics: cloudflare-tunnel, flask, local-server, media-server, no-database, open-source, privacy-first, pwa, python, realtime-chat, selfhosted, streaming, tiktok-style, websocket
- Language: Python
- Homepage:
- Size: 18.3 MB
- Stars: 73
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 👻 GhostHub
**GhostHub** is a zero-setup, mobile-first media server you can run instantly and share over the internet. No accounts. No config. Just swipe through your own folder like it’s TikTok.
Perfect for temporary sharing, personal libraries, or lightweight deployments with friends.
Runs as a **Python script**, **one-click Windows `.exe`**, or **Docker container** — no install, no accounts, no cloud.
## 📱 Preview Gallery
### Desktop View (Use arrow keys to navigate inside categories)
---
## 🚀 Features
- 📁 Add custom folders and browse your media
- 🎞️ TikTok-style swipe navigation for images & videos
- 🔁 Optional host sync — everyone sees the same media, watches at their own pace
- 💬 Built-in real-time chat (ephemeral, anonymous)
- 📱 Fully mobile and desktop optimized
- 🌐 Optional public sharing via Cloudflare Tunnel
- 🖥️ Portable `.exe` with no dependencies or setup
- 🐳 Docker support for cross-platform compatibility
- 💾 External config (`media_categories.json`) so you keep your folders
---
## ⚙️ How to Run GhostHub
### 🔧 Option 1: Standalone Executable (Windows)
The `.exe` contains everything — no setup needed.
1. Run `GhostHub.exe`
2. You'll be prompted:
- Whether to enable Cloudflare Tunnel
- The public link (if enabled) will auto-copy to clipboard
3. Open your browser and go to: [http://localhost:5000](http://localhost:5000) (manually — it doesn't auto-launch)
> 📌 `media_categories.json` is saved in the same folder — you can edit this to manage your categories.
>
> ✅ No need for `cloudflared.exe` — it's bundled inside the `.exe`
---
### 💻 Option 2: Python (Manual / Development Mode)
1. Install **Python 3.7+**
2. **Required:** Download and place this executable in the project root:
- [`cloudflared.exe`](https://github.com/cloudflare/cloudflared)
3. Install dependencies:
```bash
pip install -r requirements.txt
```
4. Start the server:
```bash
python media_server.py
```
Or use the helper:
```bash
bin/start_server.bat
```
5. Open your browser manually to: [http://localhost:5000](http://localhost:5000)
> 💡 Tunnel will prompt automatically if cloudflared.exe is present
---
### 🐳 Option 3: Docker (Cross-Platform)
Run GhostHub in a Docker container for easy deployment on any platform.
1. Install [Docker](https://www.docker.com/products/docker-desktop)
2. Add your media directories to `docker/docker-compose.yml`:
```yaml
volumes:
- ../instance:/app/instance
- ../media:/media
# Windows paths (Docker Desktop):
- C:/Users/username/Pictures:/media/pictures
- C:/Users/username/Videos:/media/videos
# Linux/macOS paths:
# - /home/user/Pictures:/media/pictures
# - /home/user/Videos:/media/videos
```
3. Build and start the container:
```bash
cd docker && docker-compose up
```
4. Open your browser to: [http://localhost:5000](http://localhost:5000)
> 📌 **Automatic Media Categories**: The Docker container automatically creates media categories for all directories mounted under `/media`. No need to manually add them in the UI!
>
> 📂 **Media Organization**: Mount your media directories as subdirectories of `/media` (e.g., `/media/pictures`, `/media/videos`) for better organization.
>
> 🌐 **Cloudflare Tunnel** is fully supported in the Docker container.
>
> ⚠️ **Windows Path Format**: When using Docker on Windows, make sure to use the correct path format:
> - Docker Desktop: `C:/Users/username/path:/media/category`
> - WSL2/Git Bash: `/c/Users/username/path:/media/category`
#### Docker Commands
```bash
# Start the container
cd docker && docker-compose up
# Stop the container
cd docker && docker-compose down
# View logs
cd docker && docker-compose logs -f
# Rebuild the container (after changes)
cd docker && docker-compose build
# Enable Cloudflare Tunnel
# Edit docker/docker-compose.yml and set USE_CLOUDFLARE_TUNNEL=y
```
#### Docker Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Port to run the server on | 5000 |
| FLASK_CONFIG | Flask configuration (development/production) | development |
| USE_CLOUDFLARE_TUNNEL | Enable Cloudflare Tunnel (y/n) | n |
---
## 🛠️ Building the Executable
Use `bin/build_exe.bat` to automate the process.
📦 What it does:
- Checks for Python and PyInstaller
- Installs any missing packages (including dnspython for eventlet)
- Asks if you want debug mode
- Builds a clean .exe using ghosthub.spec
Build Instructions:
```bash
bin/build_exe.bat
```
Output appears in the `/dist` folder as `GhostHub.exe`
---
## 📁 Media Categories
1. Click "Add Category" in the UI
2. Name it and select a folder path
3. It will persist in media_categories.json
---
## 🎥 Supported Formats
**Images**: jpg, jpeg, png, gif, bmp, tiff, svg, webp, heic, raw, psd, xcf, etc.
**Videos**: mp4, webm, mov, avi, mkv, wmv, flv, m4v, ts, mpg, ogv, etc.
---
## 🧪 Troubleshooting
- Media not loading? Check your paths and file types
- Tunnel not starting? Ensure cloudflared.exe is present (for .bat/Python mode)
- Chat or sync buggy? Refresh — GhostHub is resilient and stateless
- Crashes? Run from terminal for logs:
```bash
cd dist
GhostHub.exe
```
---
## ⚠️ Known Issues
- **Video Loading**: Very large video files may take a moment to buffer before playing smoothly.
- **Rapid Navigation**: Extremely rapid scrolling through videos (especially on mobile) may occasionally cause temporary UI glitches. Simply pause for a moment to allow the app to catch up. In rare cases, you may need to close and reopen the site.
- **Sync Button Glitch**: Enabling sync mode while actively viewing a category can cause the category view to glitch.Enable sync mode before entering a category or after backing out to the category view. A fix is on the roadmap.
## 💬 Final Notes
GhostHub is meant to be light, fast, and ephemeral — like a digital campfire. Spin it up, invite a few ghosts, and shut it down when you're done.
No setup. No tracking. No trace.
Ghost on, my friend. 👻