Deploying From Source to a World You Can Enter: Which Parts of the Road Need Human Hands
3D virtual world deploymentself-hosted 3D worldNode.js 3D serverPostgreSQL for 3D worldsWebSocket reverse proxyDocker 3D deploymentintranet 3D deploymentThree.js self-hostingenvironment variablessecret management
The previous article laid out what the source code contains. This one takes the next step: from clone to a world running on your own server, enterable from a browser — what the path looks like, and which steps no document can do for you.
A common misunderstanding to clear first: "download and run" does not mean "install nothing." This is a standard Node project; the environment, the database, and the configuration all need to be in place first. The deployment docs walk through every step, but the hands are yours. Because deployment time varies by machine, network, and person, this article gives no deployment-time numbers — and will not invent one.
1. The deployment path: what the repo prepared for it
| Step | What the repo provides | Notes |
|---|---|---|
| 1. Check the environment | check-env.js, 环境检测.bat | Node version, dependencies, database drivers — self-check before you start |
| 2. Create and import the database | database/, Database_Import.md, 数据库导入.md | Schema scripts and import instructions, PostgreSQL |
| 3. Configure environment variables | .env.example and friends | Database connection, secrets, ports — all centralized in env vars, commented line by line in the examples |
| 4. Start | 启动服务器.bat / plain Node | A Windows launcher script or the command line; Dockerfile and docker-compose.yml are also provided |
| 5. Verify | Acceptance scripts in scripts/ | 54 accept_*.js files — passing them beats "the page opens" |
The design logic of this path is one sentence: everything that varies by machine is collected into environment variables and config files; the code itself hides no environmental assumptions. Move to another server and you change configuration, not code.
2. Which work no document can do for you
Honestly:
- Installing the environment itself. Which Node version, how to install PostgreSQL, which firewall ports to open — the docs are clear, but you type the commands.
- Domain and HTTPS. Public access needs a domain; ICP filing, certificates, and reverse proxying have nothing to do with the code and everything to do with "can it be reached."
- Secret management. Database passwords, JWT secrets, AI provider keys — the example files hold placeholders; generating and keeping the real values is yours. A principle worth stealing: once a secret leaks, "deleting" does not replace "rotating" — repo history, caches, and archive sites may all hold copies. Rotate first, clean second.
- Backup strategy. The schema scripts are given; the backup cadence and retention are your operational decisions.
3. First sight after deployment: what the enterable world looks like
This is what the browser shows after deployment (live desktop screenshot): the player character at the spawn point, buildings, animals, and billboards around them. Seeing the picture means three chains are all up — rendering, asset loading, and real-time communication.
The same service admits phone browsers too (live screenshot): virtual joystick, voice button, camera and jump controls, with the sign-in notice and a cross-world entry at the top. Stated honestly: phones entering the world is evidenced by the screenshot, but we have not yet completed full measured testing of mobile frame rate and power draw — take performance numbers from your own devices.
4. The three spots new deployers trip on
From our own deployments and answering questions, the snags are rarely in this codebase — they are in the environment:
- The database won't connect. Nine times in ten it's the auth configuration — PostgreSQL's auth method (peer/trust/password) mismatched, or the host/port in the connection string wrong.
check-env.jscatches one layer of this for you. - The port is open but the page won't load the world. Usually the reverse proxy lacks the WebSocket upgrade — this world's real-time sync rides on WebSocket, and a proxy that doesn't pass it through produces "the page opens but I can't enter the world."
- Changed the config, nothing changed. Environment variables require a process restart; with Docker, check that the container mounts the latest config file.
5. Who this deployment path suits — and who it doesn't
- Suits: people with their own server (cloud or in-network machine), willing to follow docs hands-on, who want the data in their own hands.
- Doesn't suit: people who won't touch a server — this source's stance is self-hosting, with no hosted edition; wait for a hosted offering or find someone to deploy for you.
- Middle ground: can operate a server but short on time — the docs are detailed enough to hand directly to your ops person or contractor for execution.
6. Boundaries and unmeasured items
- No deployment-time numbers in this article — machine, network, and familiarity vary too much; an invented number would not help your decision.
- The container route (Dockerfile / docker-compose) is available, but our own production runs non-containerized; the container route has not been through long-term verification in our production.
- Phones entering the world is evidenced by live screenshots; frame rate and power draw are not fully measured.
- Deployment docs follow the current repo version; steps and UIs evolve.
FAQ
Q: Is Docker mandatory?
A: No. Both routes are in the repo: plain Node (our production route) or containers (entry points provided). Pick whichever your ops prefers.
Q: Can it deploy inside an intranet?
A: Yes — that is one of the points of self-hosting. Rendering happens in the visitor's browser; the server only sends data, so an intranet deployment needs no rendering hardware, and after de-CDN-ization all dependencies are local, so it runs offline.
Q: What server spec is enough?
A: Depends on concurrent scale; no universal number. A measured anchor: 100 AI agents online cost about 0.079 CPU cores total at ~1 KB/s each; live users cost mainly WebSocket message relaying. Reason backwards from your target headcount.
Q: What should I do right after deploying?
A: Run the acceptance scripts. The 54 accept_*.js files are a ready-made health check; pass them before adding content, and you will have a baseline to compare against when something breaks.
Source & Repositories
The three mirrors are identical; the first two are faster inside China. The repos include deployment docs and a set of acceptance scripts you can run yourself to see the measured numbers.
- Gitee (fastest in China): https://gitee.com/miduoxinxijeji/miduo.git
- GitCode (China mirror): https://gitcode.com/qq_35054471/virtual-world
- GitHub: https://github.com/miduo100/3d-virtual-world
About Genesis
Genesis is a self-hosted 3D virtual world system built on Three.js + WebGL, helping individuals and businesses build their own 3D spaces. Accessible directly from a browser, compatible with both PC and mobile, it supports multiplayer online, federated teleportation, a shop system, and Agent integration—where an AI can enter your world as an embodied character. Your data runs on your own server, never passing through a third-party platform—so every world truly belongs to its owner.
Stuck on the deployment road, or want to talk through your scenario? Genesis (a.k.a. the Genesis Virtual World CRM) is a Three.js 3D virtual world base layer that runs on your own server — the source is available and free to run locally; online, commercial, and federated use require a subscription license. Deployment docs, environment checks, database scripts, and acceptance scripts are all in the repo. Search "Genesis Virtual World CRM" to find the site with a walkable demo world.
About the name: Genesis in this article is the same self-hosted 3D virtual world product also called the Genesis Virtual World CRM. If "Genesis" does not find us, search "Genesis Virtual World CRM".