OpenVGal
Self-hosting

Files you can keep.

A gallery is a folder of ordinary files: an HTML page, a JSON description of the building, the 3D rooms, and your images. Put that folder on any web server and it runs — no account, no database, no call back to us.

This is the same engine the galleries we host run on, under an MIT licence. You do not need a subscription to get a copy, and having one does not take the option away.

Getting the files

There are two ways to the same thing, and both hand you a gallery that is complete — viewer, room templates, materials and your images.

Save local copy

In the builder, beside Save as draft. No account needed: build a gallery and take it away. This is the whole path for someone who never intends to publish here.

Download

In your dashboard, on any gallery that has files — draft or live. Use it to take a copy of something you already publish with us, or to move it out.

What arrives depends on your browser. Chrome and Edge can write into a folder you pick, so you choose one and the gallery lands in it, ready to open. Firefox and Safari cannot, so the gallery comes as a single zip to expand.

It is around 40 MB before your images, because the 3D engine, the room templates and the materials all travel with it. That is the point: the copy keeps working with nothing of ours behind it.

Downloading stays available even if a subscription lapses. Your work does not become hostage to a card that expired.

What is in the folder/ZIP

viewer.html
The page you open. Everything else hangs off it.
building_v2.json
The building: rooms, doors, and which image hangs where at what size.
declarations.js
Where the viewer looks for everything. Relative by default, which is why the folder works anywhere.
templates/
The 3D rooms of the style you built in.
materials/
Textures, the lit sign, and the material definitions the rooms use.
Your folders
One per room, holding your images under the names you gave them.

There is a README.md in there too, saying much of this in shorter form, plus the overlay files and the Babylon.js engine the rooms are drawn with.

Putting it online

Every path in the folder is relative to viewer.html, so there is nothing to configure and nothing to edit. Upload the folder and open it. It works at the root of a domain and it works three levels down:

example.com/gallery/viewer.html

Hosting an OpenVGal gallery for free — a three-minute walkthrough.
GitHub Pages
Free. Commit the folder to a repository and turn Pages on.
Netlify
Free tier. Drag the folder onto the deploy page and it is live.
Cloudflare Pages
Free tier, same idea — upload the folder.
Your own server
Anything that serves static files: Apache, nginx, a shared host, a folder inside an existing site.

Only declarations.js needs touching if you want something unusual — serving your images from a different host, say. Otherwise leave it alone.

Opening it on your own machine

A gallery has to be served, not opened from the disk. Double-clicking viewer.html gives you a file:// address, and Chrome and Firefox refuse to let a page opened that way fetch its own neighbouring files — you get a room that never loads rather than an error you can read.

Any static server fixes it. If you have Python, one line in the gallery folder is enough:

python -m http.server 8080

Then open http://localhost:8080/viewer.html. Nothing leaves your machine; this is the same check worth doing before you upload anywhere.

Making it yours

The sign. The lit sign on the entrance-hall wall is materials/logo.png. Replace it with your own: white line art on a black background — the white is what glows — as a PNG, 1024 × 512 px. A photograph comes out a grey smear.

The gallery itself. Rooms, sizes, titles and style are set before you download — customizing a space covers all of it. To change something afterwards, change it in the builder and download again.

What you take on

Hosting your own gallery is not hard, but it is yours. Worth knowing what moves across with the files and what does not.

  • No permanent address from us. The URL is whatever your server says it is, and the openvgal.com/view/you/gallery form is not part of the deal.
  • No artist page, no social cards. The gallery listing and the preview image that appears when a link is shared are things our hosting builds around your gallery, not things inside it.
  • Updates are a re-download. Your copy runs the engine as it was on the day you took it. Improvements to the viewer reach it when you download a new copy.
  • The bandwidth is yours. A gallery is mostly images; a busy month is a busy month on your host, not ours.
  • The backups are yours. You need to run on your own the backups of your files. Same for security and maintenance.

In exchange you get a gallery that outlives anything we do: plain files, an open licence, and no service in the middle.

Next

The open-source repository is where the engine is developed, and where the format, the templates and the layout algorithm are documented for anyone who wants to go further than the files.

Open the builder