Self-hosted house planner: true-scale 2D floor plan, 3D, satellite map overlay, sewer, electrical, water and underfloor heating with calculations, priced bill of materials. React + PHP, no database. By the team behind homedesignsai.pro
Installation
English | Русский
House Planner is a static React app plus a small PHP API that keeps the plan in files. There is no database and no Node.js process on the server. Pick one of three ways to run it.
| Option | Good for | Needs |
|---|---|---|
| Docker | a home server, a VPS, trying it out | Docker with Compose |
| Local PHP server | development, a quick look | Node.js 22, PHP 8.1+ |
| Shared hosting | a permanent site with HTTPS | PHP 8.1+ hosting with Apache or LiteSpeed |
Docker
git clone https://github.com/egmalt/house-planner.git
cd house-planner
docker compose up -d --build
Open http://localhost:8080/. On the first run the app asks you to finish setup: open /api/setup.php and set a password (at least 8 characters).
Password from the environment. To skip the wizard, pass the password on the first start:
HOUSE_PASSWORD='a-long-password' docker compose up -d --build
The password is applied only when the storage is empty. Once installed, HOUSE_PASSWORD is ignored, so it is safe to leave it in your .env.
Port. The container listens on 8080; the host port is HOUSE_PORT (default 8080):
HOUSE_PORT=9000 docker compose up -d
Compose also reads these variables from a .env file next to docker-compose.yml.
Data. The config, the current plan, every version and every snapshot live in the named volume house-data, mounted at /var/lib/house-planner. Rebuilding the image and docker compose restart keep it. docker compose down -v deletes it, so do not use -v unless you mean it.
Changing the password. Delete the config inside the volume and install again; the plan and history stay:
docker compose exec house-planner rm /var/lib/house-planner/config.php
HOUSE_PASSWORD='new-password' docker compose up -d --force-recreate
or, without HOUSE_PASSWORD, run docker compose restart and open /api/setup.php. Existing logins stop working because the cookie token is regenerated.
Protecting the wizard. Between the first start and setting the password, anyone who can reach the port can open /api/setup.php. Either start with HOUSE_PASSWORD, or set HOUSE_SETUP_KEY so the wizard asks for that key too.
Backup.
docker compose exec -T house-planner tar -C /var/lib/house-planner -czf - . > house-backup-$(date +%F).tar.gz
HTTPS. The container serves plain HTTP. Put it behind a reverse proxy that terminates TLS (Caddy, Traefik, nginx) and forward to HOUSE_PORT. The login cookie gets the Secure flag when the request comes over HTTPS.
Local PHP server
Development mode, no build needed. Two terminals:
npm i
npm run dev:api # terminal 1: PHP API on 127.0.0.1:8000 from public/
npm run dev # terminal 2: Vite on http://localhost:5173
Open http://localhost:5173/api/setup.php, keep the first storage option, set a password, then open http://localhost:5173/. Vite proxies /api, /data and /plans to PHP. The storage is $HOUSE_STORAGE if set, otherwise ./storage in the repository root (git-ignored).
scripts/dev-router.php repeats the .htaccess rules for the PHP built-in server (no direct access to api/_*.php and storage/, cookie check for data/ and plans/). Still, the built-in server is for your own machine only.
To run the production build locally instead: npm run build && php -S 127.0.0.1:8000 -t dist, then http://127.0.0.1:8000/api/setup.php.
Shared hosting
Any hosting with PHP 8.1+ (with the curl extension, used by the Petrovich cart) and Apache or LiteSpeed with mod_rewrite works. Build locally, upload dist/, open /api/setup.php. Full walkthrough with scripts/deploy.sh, FTP, HTTPS, updates and backups: deploy.md.
What setup does
/api/setup.php runs once. It:
- Offers storage locations in order:
$HOUSE_STORAGE,<site root>/../storage(outside the web root, preferred),<site root>/storage(inside, closed byRequire all denied). - Creates the storage folder with
config.php(password hash, random cookie token, seed plan path, time zone). - Writes
data/.htaccessandplans/.htaccess, which return401without the login cookie. - Returns
403on every later visit.
On the first API request the storage is seeded from plans/demo.json: a fictional Nordic single-storey house with a garage on a 30 × 45 m plot in Estonia. Replace it with your own plan in the editor, or import a JSON file from the "⋯" menu.
Requirements in short
| Component | Version |
|---|---|
| Node.js (build only) | 22 |
| PHP | 8.1+ with json, curl (for the Petrovich cart) |
| Web server | Apache 2.4 or LiteSpeed with mod_rewrite; nginx works if you deny /storage, /data, /plans yourself |
| Browser | a current Chrome, Firefox, Safari or Edge with WebGL 2 |
Next: usage guide.