Skip to content

About

Turn any website into an installable app across iOS, Android, Windows, macOS and Linux, and generate a sharing link.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

AppBuilder

AppBuilder

Turn any website into an installable app — in seconds.

One link in, finished products out for Android · iPhone / iPad · Windows · macOS · Linux.

License: MIT Platforms Stack


AppBuilder — turn any website into an installable app

AppBuilder is the product name; the repository is still called WebToApp. Enter a URL and, seconds later, get a finished product you can install, share and use like an app. A single generated result covers Android, iPhone / iPad, Windows, macOS and Linux, and each one is only a few KB — so it downloads and installs almost instantly.

Open source · Free · No sign-up.


Features

  • Site analysis: fetches the target page and extracts the name, theme color and icon (with SSRF protection — private/loopback/metadata targets are refused).
  • Website Compatibility Scanner: scores how app-ready a site is (HTTPS, responsive, PWA manifest, service worker, installable meta) with per-check PASS / WARNING / FAIL detail before you build.
  • Build Preflight: an honest READY / WARNING / BLOCKED verdict run before every build — validates the app config, website reachability, icon, and the local Android toolchain so a build never fails silently.
  • Icon Quality Analyzer: inspects the detected/uploaded icon (resolution, format, squareness) and recommends the ideal 512×512 PNG.
  • Build Queue with real metrics: builds run through a bounded async queue with live position info, cancellation, and persisted real build durations.
  • Network / Offline screen + smart external-link handling (Android): generated apps show a friendly offline screen with retry, and external links open in the system browser while in-app navigation stays inside the WebView.
  • Multi-platform packaging: builds installers for five platforms at once
    • Android — a real, installable WebView APK (v1+v2+v3 signed). Each app uses its own dedicated signing certificate, with a proper adaptive icon normalized from your logo.
    • iOS — a .mobileconfig Web Clip profile, with optional CMS signing using a public-CA certificate ("signature-free" install).
    • Windows / macOS / Linux — lightweight launchers with a native icon.
  • Android WebView feature toggles (per build, tagged "Android" in the UI):
    • Immersive fullscreen (hide status + navigation bars)
    • Desktop mode (request the site with a desktop browser identity)
    • Hide toolbar (auto)
    • Fullscreen + status bar (edge-to-edge, status bar visible)
    • Enable JavaScript (default on)
    • Enable DOM storage (default on)
  • iOS standalone Web Clip: the profile embeds the target URL directly so the FullScreen clip opens standalone instead of being handed off to Safari. Profiles installed before this change still point at /a/<id>/launch, which continues to redirect to the current URL (hot-swappable server-side via a per-app edit_token).
  • Adaptive icon pipeline: any uploaded/recovered/generated logo is normalized into a proper Android adaptive icon (foreground + background layers, safe-zone compliant, all density buckets) — never stretched or distorted.
  • History: build history is saved per device fingerprint (HMAC-signed cookie), stored in SQLite, with export / import to other devices.
  • Celebration result popup: when a build finishes, a confetti-celebration popup reveals the share link.
  • Auto cleanup: apps with no visits for 30 days are automatically reclaimed.
  • Optional Cloudflare R2 offload: downloads go through the CDN, saving origin bandwidth.
  • Multilingual UI: 3 built-in languages — English, Indonesian (Bahasa Indonesia), Malay (Bahasa Melayu) — from a flag dropdown in the top-right corner. The UI defaults to English and can refine itself from /api/geo.
  • Mobile-first responsive experience: a dedicated compact layout for phones (≤430px) with a dot stepper, sticky bottom Back/Next bar with safe-area padding, full-width capability rows, a collapsible Build Ledger, and 44px+ touch targets — while the desktop layout is untouched.

App size

Each package is just a thin entry point to your site — it bundles no site content, so the artifacts are measured in kilobytes, not megabytes. Under the hood it uses each platform's native lightweight shell: an Android WebView APK, an iOS Web Clip profile, and .app / .bat / .desktop launchers that open the system browser in app mode on desktop.

Platform Package What's inside
Android android.apk A real, installable WebView APK (v1+v2+v3 signed, adaptive icon)
iOS / iPadOS ios.mobileconfig A Web Clip configuration profile
macOS macos.zip A .app bundle (launcher script + icon)
Windows windows.zip A .bat launcher + desktop-shortcut helper + icon
Linux linux.tar.gz A .desktop entry + install script + icon

When the Android toolchain is unavailable, the Android target falls back to an installable PWA package (android.zip) — nothing breaks.

Tech stack

  • Backend: Python 3.10+ · FastAPI · Uvicorn · SQLite (WAL) for task/history stores
  • Frontend: plain HTML / CSS / JS (static files served directly by the backend — no bundler)
  • Packaging toolchain: Android SDK (aapt2 / d8 / apksigner / zipalign), apktool, Pillow, openssl
  • Frontend tooling (dev only): ESLint + Prettier + a Node smoke test (package.json)

Project structure

.
├── index.html              Homepage / SPA shell
├── css/ js/ assets/        Frontend static assets (self-hosted fonts)
│   └── js/i18n.js          Lightweight i18n runtime
│       js/i18n.strings.js  Translations (en / id / ms)
├── scripts/                Frontend scripts (smoke test, cache-bust fingerprint)
├── server/
│   ├── main.py             FastAPI app and routes
│   ├── config.py           Environment-variable configuration
│   ├── net.py              Outbound SSRF guard (validate + connect time)
│   ├── history_store.py    Per-device history store (SQLite, WAL)
│   ├── task_store.py       Build task queue store (SQLite)
│   ├── logging_util.py     Structured JSON logging
│   └── engine/
│       ├── analyzer.py     Site analysis
│       ├── distiller.py    Generates the per-platform packages (core)
│       ├── apk_builder.py  Android APK build and signing
│       ├── icon_normalizer.py  Adaptive-icon normalization pipeline
│       ├── mobileconfig_signer.py  iOS profile signing
│       ├── storage.py      Cloudflare R2 offload (SigV4)
│       └── recipe.py       Sample recipe data (illustrative)
├── certs/                  Signing material (private keys are not committed)
└── generated/              Runtime-generated apps and data (not committed)

Quick start

Requires Python 3.10+. Building a real Android APK additionally requires the Android SDK and apktool (it falls back to a PWA package when they are missing).

Android build toolchain (for signed APK output on a VPS): JDK 17, Android SDK with Platform android-34 and Build-Tools 34.0.0 (aapt2, d8, apksigner, zipalign), apktool 2.11.1, and openssl. The one-shot installer is server/scripts/install_android_sdk.sh; see docs/DEPLOY.md for the full setup. ANDROID_HOME is auto-detected (override with ANDROID_HOME / ANDROID_SDK_ROOT). If AAPT2 ever fails, the build log now records the exact command, stage (compile/link), exit code and captured stdout/stderr to make the root cause visible.

# 1. Create a virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r server/requirements.txt

# 2. Configure (optional, everything has defaults)
cp .env.example .env
# Edit .env as needed

# 3. Run
uvicorn server.main:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000.

No environment variables are needed for local development. When deploying publicly, set PUBLIC_BASE_URL (otherwise iPhones can't open localhost) and run with ENV=production + a DEVICE_FINGERPRINT_SECRET. See .env.example for the full list.

Development

The frontend is dependency-free at runtime; the Node tooling is only for lint/format/test during development.

npm install            # install ESLint + Prettier (dev only)

npm run lint           # ESLint over js/
npm run format:check   # Prettier check
npm test               # i18n smoke test (key parity en/id/ms)
npm run fingerprint    # refresh ?v=<hash> cache-bust query strings in index.html

Backend tests (pytest):

pip install pytest
python -m pytest -q

Deployment

For a complete step-by-step production guide (systemd, Nginx, HTTPS, Android/iOS, R2), see docs/DEPLOY.md.

In production it is common to run it under systemd, behind an Nginx reverse proxy. A minimal production environment:

PUBLIC_BASE_URL=https://your-domain.com
ENV=production
DEVICE_FINGERPRINT_SECRET=<64 hex chars>   # required in production — builds are refused without it
METRICS_TOKEN=<random>                      # optional: gates /api/metrics behind a Bearer token
# /etc/systemd/system/webtoapp.service
[Unit]
Description=AppBuilder
After=network.target

[Service]
WorkingDirectory=/path/to/WebToApp
EnvironmentFile=/path/to/WebToApp/webtoapp.env
ExecStart=/path/to/WebToApp/venv/bin/uvicorn server.main:app --host 127.0.0.1 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

Health/readiness probes are available at /healthz and /readyz. For iOS profile signing ("signature-free" install), see the certificate setup in certs/README.md.

How Cloudflare R2 offload works

Generated installers (APK / ZIP / .mobileconfig) can be served from a CDN instead of the origin. When R2 is configured:

  1. After each build, every file in generated/<app_id>/downloads/ is mirrored to R2 under the key <app_id>/downloads/<filename> (server/engine/storage.py), and the resulting public URLs are written into the app's recipe.json as a downloads_cdn map.
  2. On download, GET /a/<id>/download/<platform> prefers the CDN URL in downloads_cdn and returns a 302 redirect to R2; if absent, it falls back to streaming the local file.
  3. On cleanup, an app's objects under <app_id>/ are removed from R2 alongside its local data.

If any R2_* variable is unset the feature is a no-op and downloads are served locally — nothing breaks. Existing apps built before R2 was enabled can be migrated with python -m server.tools.backfill_r2. Full setup steps are in docs/DEPLOY.md §11.

Security notes

  • All secrets (R2, Cloudflare, signing passwords) are read from environment variables; the repository contains no real credentials.
  • Signing private keys (certs/*.keystore, certs/app-keys/, certs/*.secret) and runtime data (generated/) are excluded by .gitignore — never commit them.
  • In production (ENV=production) the server fails closed: builds return 503 unless DEVICE_FINGERPRINT_SECRET is set, so per-device quota and history privacy can't silently fail open.
  • Outbound fetches are guarded against SSRF at both validate-time and connect-time (private/loopback/link-local/metadata IPs and non-allowlisted ports are refused). The same guard protects the URL-swap endpoint.
  • Sensitive paths (/certs, /server, /.git, /generated, key/cert suffixes) are hard-blocked from the static mount — including path-traversal attempts.
  • Each generated Android app uses its own independent signing certificate, which avoids the certificate fingerprint being flagged en masse and ensures the same app can be updated in place.

License

MIT

About

Turn any website into an installable app across iOS, Android, Windows, macOS and Linux, and generate a sharing link.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages