Spaces:

build-small-hackathon
/

HearthNet

Paused

# Windows EXE
python build/quickstart.py windows

# Linux AppImage
python build/quickstart.py linux

# macOS .app Bundle
python build/quickstart.py macos

# Docker Image
python build/quickstart.py docker

# All (for current platform + Docker)
python build/quickstart.py all

🖥️ Windows Build (EXE)

Output

dist/HearthNet.exe (~80 MB)

Requirements

Python 3.10+ (already installed)
PyInstaller (auto-installed by script)
200 MB disk space

Build

python build/quickstart.py windows

Run Standalone EXE

cd dist
HearthNet.exe

Then open: http://localhost:7860

🐧 Linux Build (AppImage)

Output

dist/HearthNet-*-x86_64.AppImage (~120 MB)

Requirements

Python 3.10+
linuxdeploy tool
300 MB disk space

Build

python build/quickstart.py linux

Run AppImage

./dist/HearthNet-*.AppImage

Then open: http://localhost:7860

Install to Applications Menu

chmod +x dist/HearthNet-*.AppImage
sudo cp dist/HearthNet-*.AppImage /opt/HearthNet
sudo ln -s /opt/HearthNet /usr/bin/hearthnet

🍎 macOS Build (.app Bundle)

Output

dist/HearthNet.app/ (app bundle)

Requirements

macOS 10.13+
Python 3.10+
PyInstaller (auto-installed by script)
300 MB disk space

Build

python build/quickstart.py macos

Run App Bundle

# Method 1: Double-click from Finder
dist/HearthNet.app

# Method 2: Terminal
open -a dist/HearthNet.app

# Method 3: Launch directly
./dist/HearthNet.app/Contents/MacOS/HearthNet

Then open: http://localhost:7860

Install to Applications

cp -r dist/HearthNet.app /Applications/
open /Applications/HearthNet.app

🐳 Docker Build

Output

docker image: hearthnet:0.1.0 (also tagged as hearthnet:latest)

Requirements

Docker installed and running
2 GB disk space

Build

python build/quickstart.py docker

Run Docker Image

docker run -p 7860:7860 hearthnet:latest

Then open: http://localhost:7860

Deploy to Server

# Push to Docker registry
docker tag hearthnet:0.1.0 your-registry/hearthnet:0.1.0
docker push your-registry/hearthnet:0.1.0

# Pull on server
docker pull your-registry/hearthnet:0.1.0
docker run -d -p 7860:7860 your-registry/hearthnet:0.1.0

📱 Android PWA (Instant - Recommended!)

No Build Needed! 🎉

Fastest way to deploy to Android:

On your computer:
```
python app.py
```
On Android device:
- Open Chrome/Firefox
- Go to http://YOUR_COMPUTER_IP:7860
- Tap menu → "Install app"
- App appears on home screen!

Advantages:

⚡ 5-minute setup
🔄 Instant updates (no rebuild)
📦 ~5 MB only
🌐 Works offline (Service Worker caching)

📦 Build Output Directory

After building, find artifacts in dist/:

dist/
├── HearthNet.exe              # Windows executable
├── HearthNet-*.AppImage       # Linux executable
├── HearthNet.app/             # macOS bundle
└── build/                     # Temporary build files (safe to delete)

Clean Up Build Artifacts

rm -rf dist/build/            # Linux/macOS
rmdir /s dist\build           # Windows

🔧 Advanced Build Options

Custom Python Path

/path/to/python3 build/quickstart.py windows

Verbose Build Output

python build/quickstart.py windows 2>&1 | less

Parallel Multi-Platform Build (macOS/Linux only)

# On macOS: build Docker + app simultaneously
python build/quickstart.py docker &
python build/quickstart.py macos

🐛 Troubleshooting

Python Version Error

[ERR] Python 3.10+ required

Fix: Ensure Python 3.10 or newer is in PATH

python --version
which python3.10  # or python3.11, 3.12, 3.13

PyInstaller Not Found

[ERR] No module named 'PyInstaller'

Fix: Run installation step first

python -m pip install pyinstaller --upgrade

Docker Not Running

[SKIP] Docker not available

Fix: Start Docker daemon

# Windows: Start Docker Desktop
# Linux: sudo systemctl start docker
# macOS: open /Applications/Docker.app

Out of Disk Space

[ERR] No space left on device

Fix: Clean up and retry

python build/quickstart.py     # Will skip building automatically
du -sh dist/                   # Check size
rm -rf dist/build/             # Remove temp files

Module Import Errors (on first run)

ModuleNotFoundError: No module named 'fastapi'

Fix: Install main dependencies first

pip install -r requirements.txt

📊 Platform Comparison

Feature	Windows EXE	Linux AppImage	macOS .app	Docker	PWA
Size	~80 MB	~120 MB	~200 MB	2 GB image	~5 MB
Setup Time	15 min	20 min	20 min	30 min	5 min ⭐
Installation	Copy & run	Make executable	Drag to Applications	`docker run`	Click link
Offline Support	Full	Full	Full	Full	Full (Service Worker)
Cross-Platform	Windows only	Linux only	macOS only	Any (Docker)	Any (Browser)
Desktop Integration	Native	Native	Native	Container	Web app
Automatic Updates	❌	❌	❌	❌ (manual rebuild)	✅ (live updates)
Play Store Ready	❌	❌	❌	❌	❌ (needs signing)
Development	✅ Easy	✅ Easy	✅ Easy	✅ Easy	✅ Easy

🚀 Distribution Paths

Desktop Users (Recommended)

Quick Demo: → PWA (5 min)
Native App: → EXE / AppImage / .app (20 min build)
Server Deployment: → Docker (30 min first-time)

Mobile Users (Android)

Quick Start: → PWA (5 min, no build!)
Offline App: → Build APK in build/android/
Play Store: → Sign + upload (requires keystore)

Enterprise Deployment

Self-Hosted: → Docker compose or Kubernetes
Cloud: → Docker image to AWS/GCP/Azure
CI/CD: → GitHub Actions + automated builds

📝 Build Script Internals

What `build/quickstart.py` Does

Checks Environment
- Verifies Python 3.10+
- Detects OS type
- Confirms HearthNet source present
Installs Dependencies
- PyInstaller (all platforms)
- linuxdeploy (Linux only)
- Platform-specific build tools
Creates Package
- Single executable (Windows: --onefile)
- AppImage bundle (Linux: --onedir + linuxdeploy)
- macOS app bundle (macOS: --onedir + code signing)
- Docker image (all platforms)
Bundles Assets
- UI files (hearthnet/ui/)
- Documentation (docs/)
- Hidden imports for dependencies
Reports Success
- Lists output locations
- Shows installation instructions
- Provides next steps

🔐 Code Signing (Optional)

Windows Code Signing

# Generate self-signed certificate (for testing)
# Production: Use Authenticode certificate from trusted CA

# Then rebuild with signing in PyInstaller

macOS Code Signing

# Automatically attempted during build
# Requires Apple Developer account for distribution

# Check signature
codesign -v dist/HearthNet.app

Linux AppImage Signing

# Sign with GPG
gpg --detach-sign dist/HearthNet-*.AppImage
gpg --verify dist/HearthNet-*.AppImage.sig

📚 Related Documentation

BUILD_STATUS.md - Current artifact inventory
ANDROID_DEPLOYMENT_GUIDE.md - APK + PWA setup
README.md - Main project readme
Cordova Guide - Android native build

🤝 Contributing

To improve the build system:

Test locally on your platform
Report issues with: python build/quickstart.py [target] 2>&1 | tee build.log
Submit improvements to build scripts
Document platform-specific issues

📞 Support

Build failed? Check:

✅ Python version: python --version
✅ Disk space: df -h (need 200+ MB)
✅ Dependencies: pip list | grep -i pyinstaller
✅ Logs: Output from script shows exact error

Have suggestions? Open an issue with:

Platform (Windows/Linux/macOS)
Python version
Error message
Output of: python build/quickstart.py [target] 2>&1

Status: ✅ All platforms supported
Last Tested: June 11, 2026
Maintainer: HearthNet Build System
License: Apache 2.0

🏗️ HearthNet Multi-Platform Build Guide

📋 Quick Start

Build for Your Platform Only

Build Specific Target

🖥️ Windows Build (EXE)

Output

Requirements

Build

Run Standalone EXE

🐧 Linux Build (AppImage)

Output

Requirements

Build

Run AppImage

Install to Applications Menu

🍎 macOS Build (.app Bundle)

Output

Requirements

Build

Run App Bundle

Install to Applications

🐳 Docker Build

Output

Requirements

Build

Run Docker Image

Deploy to Server

📱 Android PWA (Instant - Recommended!)

No Build Needed! 🎉

📦 Build Output Directory

Clean Up Build Artifacts

🔧 Advanced Build Options

Custom Python Path

Verbose Build Output

Parallel Multi-Platform Build (macOS/Linux only)

🐛 Troubleshooting

Python Version Error

PyInstaller Not Found

Docker Not Running

Out of Disk Space

Module Import Errors (on first run)

📊 Platform Comparison

🚀 Distribution Paths

Desktop Users (Recommended)

Mobile Users (Android)

Enterprise Deployment

📝 Build Script Internals

What build/quickstart.py Does

🔐 Code Signing (Optional)

Windows Code Signing

macOS Code Signing

Linux AppImage Signing

📚 Related Documentation

🤝 Contributing

📞 Support

What `build/quickstart.py` Does