Open Museum
Open Museum is a bilingual (English/German) static website for exploring 3D reconstructions of monuments, fountains, and public art. The project documents cultural heritage through interactive 3D presentation at openmuseum.io.
Working on the code? AGENTS.md is the orientation guide — architecture, the build's Firestore dependency, and the gotchas that are not visible from the tree. Written for coding agents, but the same ground a new contributor needs.
Project Goals
The primary aim is to document and preserve 3D models of cultural and artistic heritage in public spaces. By leveraging modern photogrammetry and 3D reconstruction, we make these works accessible for online viewing and cultural documentation.
Explore the Models
All works are available on the website for interactive viewing in the browser:
- Browse models: Visit openmuseum.io
- Models are served as
.glb (web) and .usdz (Apple AR) where available
- Most works are view-only on the website; downloads are offered only for selected works where rights allow (see License)
Each work page shows its IP status (public domain, freedom of panorama, or authorized use) and whether downloads are available.
Tech Stack
| Layer | Choice |
|---|
| Framework | Astro v7 (static output) |
| Styling | Tailwind CSS v4 |
| 3D viewer | <model-viewer> v4 |
| Content | Cloud Firestore (content / works) loaded at build time |
| i18n | Astro built-in routing — English at /, German under /de/ |
| Deployment | GitHub Pages via GitHub Actions |
Local Development
pnpm install
pnpm dev
Content is fetched from Firestore during astro dev and astro build. Authenticate with Application Default Credentials first:
# Option A: gcloud ADC
gcloud auth application-default login
# Option B: point at a credentials file
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/adc.json
export GOOGLE_CLOUD_PROJECT=open-museum-885a1
Create a .env file in the project root for optional configuration (see Asset Storage).
Asset Storage
Large files (3D models and images) are hosted on external storage to keep the repository lightweight.
The storage URL is configured via the PUBLIC_ASSETS_BASE_URL environment variable:
# .env
PUBLIC_ASSETS_BASE_URL=https://open-museum-885a1.firebasestorage.app
Asset paths in Firestore documents are resolved at build/runtime via src/utils/assets.ts.
Modes
- With remote assets: Set
PUBLIC_ASSETS_BASE_URL in .env and assets load from Firebase (or another compatible host)
- With local assets: Leave
PUBLIC_ASSETS_BASE_URL empty and place asset files in public/models/ and public/images/works/ (these directories are gitignored)
- Switching providers: Change the base URL — path resolution is handled centrally in
getAssetUrl()
Firebase (authenticated model loading)
When Firebase is configured, model files can be loaded through authenticated requests. Set these in .env (or as GitHub Actions variables for deployment):
PUBLIC_FIREBASE_API_KEYPUBLIC_FIREBASE_AUTH_DOMAINPUBLIC_FIREBASE_PROJECT_IDPUBLIC_FIREBASE_STORAGE_BUCKETPUBLIC_FIREBASE_APP_ID
Content
Works are stored in Firestore (project open-museum-885a1, database content, collection works). Each document ID is the work slug (for example berlinstein). Astro loads the collection only at build/dev time via a custom content loader — visitors receive static HTML and never talk to Firestore.
Edit documents in the Firebase Console or via the Firebase/Admin CLI. Security rules allow public reads (the work data is public website content) and deny client writes except for the content-admin allowlist in isContentAdmin(), which exists so the work creator below can publish new works. Console/CLI updates use IAM and are not blocked by those rules.
Key fields:
title, description — bilingual (de / en)category — brunnen, denkmal, or kunstwerkmodel.glb, model.usdz — asset pathsphotos, poster — gallery and preview imageslocation — coordinates, address, optional Google My Maps embed URLcity, country, artist, modelCreator, year, material — metadataipStatus — public-domain, freedom-of-panorama, or authorized-usedownloadAllowed — whether GLB/USDZ download is offered on the work pagetour — optional guided camera tour steps
See src/content/work-schema.ts for the full schema.
Adding a work
pnpm work:create
This serves the work creator at
http://localhost:5174/tools/work-creator/: a local page that uploads the
GLB/USDZ/poster/photos to Firebase Storage and writes the works/<slug>
document, validated against the same rules the build enforces. It needs a
one-time setup (an admin user plus a config file) — see
tools/work-creator/README.md.
Gallery thumbnails need no action: prebuild regenerates missing .webp files
from Storage during the build, so nothing has to be committed for a new work.
Validation is shared between the tool and the CLI in
scripts/lib/work-shape.mjs; keep it in sync with
src/content/work-schema.ts when fields change.
Publishing content changes
Firestore edits do not auto-publish. After updating works:
- Push to
main, or
- Run the Deploy to GitHub Pages workflow manually (
workflow_dispatch)
Migration helpers
If you still have local JSON under src/content/works/:
pnpm works:migrate:dry # validate + print plan
pnpm works:migrate # upsert into Firestore
pnpm works:verify # read back / validate remote documents
GitHub Actions variables for Firestore builds
In addition to the existing PUBLIC_* variables, set:
| Variable | Example |
|---|
GCP_WORKLOAD_IDENTITY_PROVIDER | projects/717967107645/locations/global/workloadIdentityPools/github-actions/providers/github-oidc |
GCP_SERVICE_ACCOUNT | [email protected] |
These enable keyless Workload Identity Federation so CI/deploy can read Firestore at build time.
Gallery Thumbnails (Build-Time Optimization)
Work-page gallery images use generated .webp thumbnails for initial render and load the full-size photo only when the user opens the lightbox.
- Generator script:
pnpm thumbs:generate
- Script source:
scripts/generate-work-photo-thumbnails.mjs
- Auto-run before build:
prebuild runs the generator automatically
- Output directory:
public/images/thumbnails/works/
The generator reads all photos arrays from Firestore works (gallery photos only), then:
- fetches originals from
PUBLIC_ASSETS_BASE_URL when set (Firebase-compatible URL handling), or
- reads originals from local
public/ when external storage is not configured.
Optional tuning via environment variables:
WORK_THUMBNAIL_WIDTH (default: 900)WORK_THUMBNAIL_QUALITY (default: 72)WORK_THUMBNAIL_CONCURRENCY (default: 4)
CI Asset Health Check
The deployment workflow includes an automated changed-page asset validation step:
- Command:
pnpm test:assets:changed
- Script:
scripts/ci/asset-health-check.mjs
- Scope: validates only pages affected by changed content/routes in the current deployment diff
- Checks:
- poster assets (e.g.
<model-viewer poster> and og:image)
- photo assets (
<img src>)
- 3D model sources (
<model-viewer src> and ios-src)
If validation fails, the workflow:
- fails the build before deployment,
- emits GitHub Actions error annotations per failed asset,
- uploads
asset-health-report.md as a workflow artifact,
- writes the same report to the workflow step summary for quick triage.
How to Contribute
Feel free to contribute in any way you can — capturing new models, improving existing ones, or sharing feedback.
If you have questions or suggestions, don't hesitate to get in touch.
Support Us
Your support means a lot:
- Make a donation
- Star this repository
- Share the project with others
License
Code (website / software)
All source code (Astro/TypeScript/CSS/JavaScript) in this repository is licensed under the MIT License. See LICENSE.
3D models and media
Not all assets share the same license. Rights vary by work:
- View-only works — Most 3D models, scans, textures, and photos on the website are shown for online viewing and cultural documentation only. They remain subject to the copyright of their artists, creators, or rights holders. Downloading, reproducing, or creating derivative works is not permitted unless explicitly stated on the individual work page.
- Downloadable works — A subset of works is offered for download where the underlying subject is public domain or explicit permission has been granted. Those downloads are released under Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) for non-commercial use, as indicated on each work page.
Check the IP status badge and download controls on each work page at openmuseum.io before reusing any asset. For rights questions or takedown requests, see the About page or contact [email protected].
Thank you for your interest in Open Museum!
