File size: 8,958 Bytes
4fd1f10
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
66a1a95
4fd1f10
66a1a95
4fd1f10
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
# πŸ—οΈ HearthNet Multi-Platform Build Guide

**Latest Update**: June 11, 2026  
**Script**: `build/quickstart.py` (Auto-builds EXE, AppImage, DMG, Docker)  
**Status**: βœ… Production Ready

---

## πŸ“‹ Quick Start

### Build for Your Platform Only
```bash
python build/quickstart.py
```

### Build Specific Target
```bash
# 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
```bash
python build/quickstart.py windows
```

### Run Standalone EXE
```cmd
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
```bash
python build/quickstart.py linux
```

### Run AppImage
```bash
./dist/HearthNet-*.AppImage
```

**Then open**: `http://localhost:7860`

### Install to Applications Menu
```bash
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
```bash
python build/quickstart.py macos
```

### Run App Bundle
```bash
# 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
```bash
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
```bash
python build/quickstart.py docker
```

### Run Docker Image
```bash
docker run -p 7860:7860 hearthnet:latest
```

**Then open**: `http://localhost:7860`

### Deploy to Server
```bash
# 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:**

1. **On your computer:**
   ```bash
   python app.py
   ```

2. **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
```bash
rm -rf dist/build/            # Linux/macOS
rmdir /s dist\build           # Windows
```

---

## πŸ”§ Advanced Build Options

### Custom Python Path
```bash
/path/to/python3 build/quickstart.py windows
```

### Verbose Build Output
```bash
python build/quickstart.py windows 2>&1 | less
```

### Parallel Multi-Platform Build (macOS/Linux only)
```bash
# 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
```bash
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
```bash
python -m pip install pyinstaller --upgrade
```

### Docker Not Running
```
[SKIP] Docker not available
```
**Fix**: Start Docker daemon
```bash
# 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
```bash
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
```bash
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)
1. **Quick Demo**: β†’ PWA (5 min)
2. **Native App**: β†’ EXE / AppImage / .app (20 min build)
3. **Server Deployment**: β†’ Docker (30 min first-time)

### Mobile Users (Android)
1. **Quick Start**: β†’ PWA (5 min, no build!)
2. **Offline App**: β†’ Build APK in `build/android/`
3. **Play Store**: β†’ Sign + upload (requires keystore)

### Enterprise Deployment
1. **Self-Hosted**: β†’ Docker compose or Kubernetes
2. **Cloud**: β†’ Docker image to AWS/GCP/Azure
3. **CI/CD**: β†’ GitHub Actions + automated builds

---

## πŸ“ Build Script Internals

### What `build/quickstart.py` Does

1. **Checks Environment**
   - Verifies Python 3.10+
   - Detects OS type
   - Confirms HearthNet source present

2. **Installs Dependencies**
   - PyInstaller (all platforms)
   - linuxdeploy (Linux only)
   - Platform-specific build tools

3. **Creates Package**
   - Single executable (Windows: `--onefile`)
   - AppImage bundle (Linux: `--onedir` + linuxdeploy)
   - macOS app bundle (macOS: `--onedir` + code signing)
   - Docker image (all platforms)

4. **Bundles Assets**
   - UI files (`hearthnet/ui/`)
   - Documentation (`docs/`)
   - Hidden imports for dependencies

5. **Reports Success**
   - Lists output locations
   - Shows installation instructions
   - Provides next steps

---

## πŸ” Code Signing (Optional)

### Windows Code Signing
```bash
# Generate self-signed certificate (for testing)
# Production: Use Authenticode certificate from trusted CA

# Then rebuild with signing in PyInstaller
```

### macOS Code Signing
```bash
# Automatically attempted during build
# Requires Apple Developer account for distribution

# Check signature
codesign -v dist/HearthNet.app
```

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

---

## πŸ“š Related Documentation

- [BUILD_STATUS.md](BUILD_STATUS.md) - Current artifact inventory
- [ANDROID_DEPLOYMENT_GUIDE.md](ANDROID_DEPLOYMENT_GUIDE.md) - APK + PWA setup
- [README.md](../README.md) - Main project readme
- [Cordova Guide](../../build/android/CORDOVA_BUILD_GUIDE.md) - Android native build

---

## 🀝 Contributing

To improve the build system:

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

---

## πŸ“ž Support

**Build failed?** Check:
1. βœ… Python version: `python --version`
2. βœ… Disk space: `df -h` (need 200+ MB)
3. βœ… Dependencies: `pip list | grep -i pyinstaller`
4. βœ… 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