After looking at SketchForge, House Planner is a natural next stop.
Both are browser-based design tools. But they are not solving the same problem.
SketchForge is about making 3D parts. House Planner is about planning a whole private house: walls, rooms, plot, utilities, underfloor heating, map alignment, estimates, versions, and snapshots.
That makes it much closer to:
self-hosted construction planning
than generic browser CAD.
What is House Planner?
House Planner is an MIT-licensed self-hosted house planning app.
It gives you:
- a true-scale 2D floor plan editor in millimetres;
- a 3D preview;
- satellite map overlay and GeoJSON parcel support;
- wall, opening, furniture, material, and room data;
- sewer, electrical, water, and hydronic underfloor-heating layers;
- calculations and warnings for those utility networks;
- a priced bill of materials from a JSON catalog;
- server-side plan versions and named snapshots;
- one-password login;
- no database requirement.
The repo describes the stack as React + PHP with no database. The plan lives as JSON files on your own server.
Why It Is Different from SketchForge
SketchForge and House Planner are both useful for homelab/makerspace-style design work, but the mental model is different.
| Question | House Planner | SketchForge |
|---|---|---|
| Main object | A full house/site plan | A 3D part/model |
| Primary workflow | Draw walls, rooms, networks, estimate materials | Create primitives, cut holes, export model files |
| Main storage | Server-side JSON with revisions/snapshots | Browser-local storage plus optional shared .skf shelf |
| Backend | PHP files plus file storage | Next.js server for app/shared projects |
| Database | None | None |
| Best fit | Construction planning, BOM, utility layout | Printable parts and quick 3D object design |
| Offline behavior | Needs its PHP server, but can run on LAN without internet | More browser-local for private projects |
So the quick distinction:
SketchForge = browser CAD for objects
House Planner = self-hosted planner for a house project
Architecture Overview
House Planner is refreshingly simple:
React/Vite frontend -> PHP API -> JSON files on disk
Observed stack:
| Layer | House Planner Uses |
|---|---|
| Frontend | React 19, TypeScript, Vite |
| State | Zustand + zundo |
| 2D editor | Konva / react-konva |
| 3D preview | three.js, React Three Fiber, drei |
| Geometry | clipper2, three-bvh-csg |
| Map | MapLibre GL, proj4 |
| Validation | zod |
| Backend | PHP 8.1+ API |
| Storage | JSON files, versions, snapshots |
| Docker runtime | PHP 8.3 Apache image |
| License | MIT |
There is no Postgres, Redis, queue, SQLite, or object storage layer.
The Dockerfile builds the Vite app with Node 22, copies the result into a PHP/Apache image, and persists the planner storage under:
/var/lib/house-planner
Self-Hosting House Planner with Docker
I added a Home-Lab compose:
House Planner Docker Compose
services:
house-planner:
build:
context: https://github.com/egmalt/house-planner.git#5c91280da6c5cc84c1a534ef80ddafb64a6b5baa
dockerfile: Dockerfile
image: house-planner:5c91280
container_name: house-planner
restart: unless-stopped
ports:
- "${HOUSE_PORT:-3817}:8080"
environment:
HOUSE_PASSWORD: "${HOUSE_PASSWORD:-}"
HOUSE_SETUP_KEY: "${HOUSE_SETUP_KEY:-}"
HOUSE_DEMO: "${HOUSE_DEMO:-}"
volumes:
- house-data:/var/lib/house-planner
volumes:
house-data:
Start it with:
cd /home/jalcocert/Desktop/Home-Lab/house-planner
docker compose up -d --build
Then open:
http://localhost:3817/
http://192.168.1.2:3817/
First-run setup is at:
http://192.168.1.2:3817/api/setup.php
That setup page lets you choose storage and set the one installation password.
Until setup is completed, the main editor can load but it will show a server connection error. That is because /api/plan.php returns:
HTTP 503 not_installed
That state means the app is reachable but no password/config has been created yet.
Field Note: Docker Trial
I built and ran the Docker image locally from commit:
5c91280da6c5cc84c1a534ef80ddafb64a6b5baa
The test command:
docker build -t house-planner:foss-trial .
docker run -d --name house-planner-foss-trial --restart unless-stopped \
-p 3817:8080 \
-e HOUSE_STORAGE=/var/lib/house-planner \
-v house-planner-foss-trial-data:/var/lib/house-planner \
house-planner:foss-trial
Result:
container: house-planner-foss-trial
status: healthy
URL: http://127.0.0.1:3817/
LAN URL: http://192.168.1.2:3817/
setup wizard: http://192.168.1.2:3817/api/setup.php
/api/plan.php before setup: 503 not_installed
image size: about 514 MB
I intentionally left the trial in first-run setup mode so you can choose the password from the browser.
How Storage Works
This is the most important practical difference from SketchForge.
House Planner stores the plan on the server.
The storage folder contains:
| Path | Purpose |
|---|---|
config.php |
Password hash, cookie token, settings |
current.json |
Current plan |
versions/ |
Every saved revision |
versions.jsonl |
Revision index |
snapshots/ |
Named restore points |
snapshots.jsonl |
Snapshot index |
site-fixed.json |
Optional locked parcel/site data |
In Docker, all of that lives in the house-data volume.
Backups are therefore straightforward:
back up the whole storage folder or house-data volume
Do not run docker compose down -v unless you intentionally want to delete the plan history.
Editing Through JSON and AI Assistants
One detail I like: the plan is a strict JSON document.
That means the browser is not the only editing surface. The repo includes scripts to pull, validate, and push the plan:
scripts/plan-pull.sh
node scripts/plan-validate.mts plans/server.json
scripts/plan-push.sh
The same versioned API is used by both the browser and scripts. If the plan changed on the server, the push exits with a conflict instead of overwriting silently.
That makes House Planner unusually friendly to assistant-driven workflows:
pull JSON -> ask an assistant to add/move/change geometry -> validate -> push as a new version
For construction planning, that is much more useful than a closed binary file.
FAQ
Is House Planner self-hostable?
Yes.
It supports Docker, shared PHP hosting, and local development with PHP + Vite. The easiest homelab path is Docker.
It does not need a database. The plan, versions, snapshots, and config are regular files in the storage folder.
Is House Planner a PWA or offline-first app?
No, not in the full PWA/offline-first sense.
It is a browser app, and it can run fully on your local network once the server is up. But the plan is stored on the PHP server. If the app cannot reach the server API, the editor cannot open the plan for editing.
The practical split:
works without internet if hosted locally: mostly yes
works without its PHP server: no
full PWA with offline edit queue: no
Internet is still needed for satellite imagery, product links, and the Petrovich cart integration.
What is the default username and password?
There is no default username.
House Planner uses one installation password. On first run, open:
/api/setup.php
and set that password.
If you open / before doing this, the UI may show:
No connection to server
HTTP 503
That does not mean Docker is broken. It means the installation is still waiting for first-run setup.
In my LAN trial, opening /api/setup.php, choosing /var/lib/house-planner, and setting the first password cleared the 503 not_installed state and allowed the editor to load normally.
For unattended Docker setup, pass HOUSE_PASSWORD on the first start. It is only applied when the storage is empty. After installation, changing the environment variable does not rotate the password; delete config.php from the storage volume and run setup again.
Should I set HOUSE_PASSWORD or use the setup wizard?
For a local-only trial, the setup wizard is fine.
If the service is reachable by other machines before setup, set either:
HOUSE_PASSWORD
or:
HOUSE_SETUP_KEY
before the first start. Otherwise, anyone who can reach /api/setup.php before you do could complete setup.
Does House Planner support multiple users?
Not as separate accounts.
There is one password per installation and no roles. Several people can still use it safely in the sense that saves are revision-checked. If two tabs, users, or scripts edit from different revisions, the server returns a conflict instead of silently overwriting.
For truly separate projects, run separate installations with separate storage volumes.
How does it compare with SketchForge?
Use SketchForge when you want a browser CAD workbench for individual printable objects and model exports.
Use House Planner when you want a whole-house planning system:
- floor plan;
- parcel/map context;
- sewer/electrical/water/heating layers;
- material estimate;
- version history;
- server-side JSON source of truth.
They are complementary. SketchForge is for parts; House Planner is for the building plan.
Can I use it without internet?
Mostly, if you host it locally.
The editor, 3D view, utility networks, estimates, and PHP API can work on a local network without internet access.
Internet is needed for:
- satellite imagery tiles;
- product links;
- the Petrovich cart integration;
- any external retailer/catalog workflows you add.
The app does not need third-party CDN scripts or fonts for the core UI.
Is the map feature based on OpenStreetMap?
Not by default.
House Planner uses MapLibre GL as the browser map renderer, but the checked source points the raster imagery layer at Esri World Imagery:
https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}
So the map feature is better described as a satellite imagery overlay rendered with MapLibre, not an OpenStreetMap tile setup.
There is still OSM-adjacent technology in the sense that MapLibre is the open mapping renderer and the app can import GeoJSON parcel/boundary data. But the default basemap tiles are Esri satellite tiles, so internet access and that third-party tile service matter for the map view.
Are the house plan, positions, and dimensions controlled by JSON?
Yes.
The plan is a single JSON document, validated by the Zod schema in src/model/schema.ts. Coordinates and dimensions are stored as integer millimetres.
Important examples:
| JSON section | What it controls |
|---|---|
site.width, site.depth |
plot size |
site.boundary |
custom parcel polygon |
site.geo.lat, site.geo.lng, site.geo.rotationDeg |
map georeference/origin |
site.imagery |
satellite overlay adjustment |
walls[].a, walls[].b |
wall start/end points |
walls[].thickness, walls[].height |
wall dimensions |
openings[] |
doors, windows, gates by offset along a wall |
furniture[].x, furniture[].y, rotationDeg, w, d, h |
object position, rotation, and size |
rooms[] |
room labels and area grouping |
networks.sewer, networks.electric, networks.water, networks.heating |
utility layers |
estimate |
bill-of-materials lines and purchases |
That is why the repo includes plan-pull, plan-validate, and plan-push scripts: you can pull the server plan JSON, edit it by hand or with an assistant, validate it, and push it back as a new version.
The UI is still the safer everyday editor because it handles snapping, visual placement, rotations, and validations interactively. But under the hood, the source of truth is plain JSON.
Could House Planner designs be integrated with Blender for sun-ray simulation?
Yes, but the difficulty depends on the accuracy you want.
For a visual sun/shadow study, it is feasible. For building-code-grade daylight analysis, it becomes a much harder simulation problem.
House Planner already has the useful ingredients:
- wall geometry as JSON points in millimetres;
- wall height and thickness;
- openings with width, height, sill, and wall offset;
- site georeference with
lat,lng, androtationDeg; - 3D rendering logic already derived from the same plan model.
That is enough to generate a Blender scene programmatically.
The missing integration work would be:
- export
plan.jsoninto a Blender Python script, glTF, OBJ, or another 3D format; - map
1000 mmin House Planner to1 min Blender; - generate wall meshes from
walls[]; - cut or model openings from
openings[]; - add transparent/glass window materials;
- orient the scene from
site.geo.rotationDeg; - use
site.geo.latandsite.geo.lngfor solar position; - set sun angle by date and time;
- batch render multiple timestamps with Eevee or Cycles.
A pragmatic first version could be:
House Planner JSON
-> blender_import_house.py
-> walls/windows/site orientation
-> set sun for June 21, Dec 21, equinox
-> render 09:00, 12:00, 15:00 shadow studies
A more complete version could calculate:
- per-room sunlight hours;
- window penetration depth;
- seasonal comparisons;
- animated timelapses;
- false-color daylight maps.
The clean summary:
visual sun/shadow study: doable
accurate daylight simulation: harder
building-code daylight analysis: use specialist tools
The reason this is realistic at all is the JSON model. Since House Planner stores the design as structured geometry instead of a closed binary file, a Blender exporter can be deterministic.
What are the important backup files?
Back up the whole storage folder or Docker volume.
In Docker, that is the house-data volume mounted at:
/var/lib/house-planner
It contains the password/config, current plan, all numbered versions, named snapshots, and optional locked site data.
Are the calculations enough for real construction?
No software note should be treated as a licensed engineering design.
House Planner includes useful reference checks and simplified calculations for networks and materials, but the repo itself warns that building-code checks and formulas do not replace a design by a qualified engineer or local-code review.
Treat it as a planning, estimating, and early validation tool.
What is the Petrovich cart integration?
It is a Russian DIY retailer workflow.
The server-side api/petrovich-cart.php can use catalog item codes to create an estimate/cart link on petrovich.ru. This depends on PHP curl and on Petrovich’s website behavior, not an official stable API.
If you are outside that market, treat the bundled catalog and integration as examples to replace with your own material catalog and suppliers.
Conclusion
House Planner is much more specialized than SketchForge, and that is a strength.
If you want a quick browser CAD tool for parts, use SketchForge.
If you want a self-hosted planning surface for an actual house project, House Planner is the more relevant project: true-scale plan, 3D preview, site map, utility layers, estimates, JSON versions, and no database.
For a homelab, the architecture is easy to reason about:
Docker container + PHP API + JSON storage volume
That is a good shape for a personal construction-planning tool.
Comments