World Monitor is a real-time dashboard that aggregates news, markets, aviation, geo-risk, infrastructure and public intelligence data. It added about 13,231 stars in GitHub Trending in a week, but “can open the front end” and “run completely offline” are two different deployment goals. This article first separates components and network dependencies, and then provides three verifiable paths for source code development, container front-end and local AI summary.
Decide how much of the stack must work offline
The project documentation describes three deployment modes with different privacy boundaries. The simplest is to open the app locally, but continue to request the public API and cloud LLM. The second runs the desktop app with Ollama, LM Studio, llama.cpp, or vLLM, keeping news summaries local while other data sources remain online. The third category is isolated networks: local models, local PMTiles, pre-prepared data snapshots, and disabling live external sources. A Docker container alone cannot deliver the third mode because flight, market, RSS, and risk feeds still require data updates. Before starting, document the allowed domains, freshness requirements, and whether cloud-based summarization is permitted.
World Monitor is more than a web frontend
The front-end is a Vanilla TypeScript application, and the map is rendered by components such as MapLibre GL, deck.gl, and globe.gl. The server part includes Edge handler, RPC gateway, cache and data seeding tasks. AIS Relay is responsible for some real-time streaming and periodic data. Redis is used for caching, throttling, and preventing multiple requests from refreshing the same data at the same time. Desktop uses Tauri with Node.js sidecar. PMTiles can put basemaps into object storage or LAN HTTP services. Therefore, self-hosting needs to clarify which components are run by themselves and which continue to borrow upstream services.
Review the license before choosing a deployment model
The repository is AGPL-3.0 with additional instructions for commercial use.
Personal, research and educational use may be self-hosted subject to attribution and license conditions.
Commercial SaaS, debranding, or repackaging requires checking the project’s commercial licensing requirements.
Don’t understand “the code can be publicly downloaded” to mean that it can be sold unconditionally as a closed source.
When planning to provide external services, first read the LICENSE and README permission forms in the repository.
Prepare Node 22 and basic tools
The project change log has fixed Node 22 as the development baseline. It is recommended to use WSL2 Ubuntu on Windows, Linux and macOS can operate directly.
|
|
When the main version of Node is not 22, use nvm to switch:
|
|
Do not mix global packages between system nodes and nvm nodes.
Launch the complete development panel from source code
First fork or directly clone the official repository:
|
|
Save the commit SHA, and subsequent document and configuration changes can be traced back to the specific version. The official contribution document provides a unified installation target:
|
|
It will prepare buf, sebuf plugin, npm dependencies and Playwright browser. To only view help run:
|
|
Development server for full variant:
|
|
The default address is http://localhost:3000.
Variants are configurations, not separate repositories
World Monitor controls panels, map layers, refresh cycles, and default data sources via variant. Technology, Finance and Complete panels can be launched separately:
|
|
The production build also has a corresponding command:
|
|
Switching variants will reset some settings. Do not treat localStorage of different browser variants as the same configuration.
Enable environment variables one data source at a time
Copy the sample file:
|
|
Don’t fill in all the API keys at once.
Start with the panel that doesn’t require credentials and confirm that the frontend, map, and basic RPC are working.
Add News, Markets, Flights or LLM Suppliers one by one.
Each time a variable is added, the service is restarted and network requests are checked.
.env.local does not enter Git:
|
|
If the second item is not output, check .gitignore first and do not continue to fill in the real key.
Use Docker to host the frontend
docker/Dockerfile in the repository builds a multi-architecture image, nginx provides SPA, and proxies API requests to the upstream.
Build locally first:
|
|
Check the Dockerfile exposed port and nginx configuration before running. Do not guess the port:
|
|
Assuming image exposure 80, loopback-only mapping test available:
|
|
If the actual ports are different, the mirroring check result shall prevail.
A containerized frontend does not make every API local
Open the Network panel of your browser’s developer tools. Refresh the page and group requests by domain name. Any request to access Vercel, Railway, Upstash, third-party news or market interfaces indicates that there is still a current cloud dependency. Don’t use “the webpage comes from your own server” to deduce “the data does not leave the LAN”. When isolation is required, replace API endpoints item by item, or disable panels that don’t work locally.
Use Ollama for local summaries
with Ollama World Monitor’s native LLM route supports OpenAI-compatible services and can discover Ollama, LM Studio, llama.cpp, and vLLM models. Confirm the service after installing Ollama:
|
|
Pull a command model suitable for native resources:
|
|
Retest OpenAI compatible endpoint:
|
|
In the application, point the base URL to the loopback address and select the actual model ID.
Local LLM fallback chain requires active verification
The project documentation describes a summary fallback sequence that includes native LLM, Groq, OpenRouter, and browser T5. If the goal is to prevent data from leaving the network, simply configuring Ollama is not enough. Also remove the cloud key, block related domain names, and confirm that the browser does not silently roll back after a local timeout. Stop the Ollama service:
|
|
Trigger summary again. A strictly offline configuration should clearly indicate that the local service is unavailable rather than produce a cloud summary.
PMTiles solves the basemap dependency
Traditional maps will continuously request online tiles per viewport. PMTiles organizes tiles into individual archives that can be placed on local disk, NAS, object storage, or a normal HTTP service. After preparing the file, do the minimum HTTP service first:
|
|
Access the PMTiles file from your browser and confirm that Range requests are supported.
Without Range support, the map might try to download the entire large file or fail to locate the tile.
The reverse proxy needs to retain the headers related to Range and Accept-Ranges.
How to choose between Cloudflare R2 and LAN storage
R2 is suitable for public network services, can reduce origin site bandwidth and provide object-level access. LAN MinIO, NAS or nginx are more suitable for isolated environments. Basemap files can be large, record size and hash before publishing:
|
|
After the client configures the URL, use the browser to confirm the request and return 206 Partial Content.
Redis is not a hard threshold for local trial
Single-person development does not require the deployment of a complete cache system. Multi-person or public network services require Redis to control refresh storms, cache seed results, and limit traffic. Start local Redis:
|
|
Verification:
|
|
PONG should be returned.
Redis should not be directly exposed to the public network, and do not rely on the default passwordless configuration for cross-host access.
Locate failures across external data sources
Start by checking the URL, status code, and response time of the browser request.
401 or 403 is usually a key, quota or authorization range.
429 indicates rate limiting. Adding retries may make the problem more serious.
5xx needs to distinguish its own proxy, upstream service and cache layer.
An empty array is not necessarily a fault, it may be that there is no data for the region and time range.
Save the request ID and response header, don’t just take a screenshot of the blank panel.
Static builds cannot replace AIS and real-time feeds
Shipping AIS, flight and GPS interference layers rely on continuous data streams or periodic seeds.
Pure nginx SPA can only display existing data and call upstream interfaces.
When you need to self-host related flows, read scripts/ais-relay.cjs and Deployment Configuration to confirm data provider permissions.
Do not unconditionally mirror and republish data sources seen on public web pages.
Turn on health check and data freshness monitoring
The application can return 200, which does not mean that the data is being updated. Monitoring is divided into at least three levels: static pages, API endpoints and seed freshness. Record the last success time and the number of consecutive failures for each data source. The entire site should not be marked as fully healthy when the news is still being updated and the market is down.
Run project’s own checks before building
|
|
The existence of the command is based on the current repository package.json and make help.
When the data test fails, do not delete the failure source to make the CI turn green. First confirm whether the format has changed.
E2E requires browser dependencies and stable test data, and container CI requires reserved shared memory.
Expose only the required reverse-proxy endpoints
The public network deployment uses HTTPS and leaves the management end, Redis, Ollama and internal seed endpoints in the private network. Ollama should not be directly exposed to the Internet by default. If the front end and API are in separate domains, explicitly set the CORS allow list. Do not use a combination that allows any origin to also carry credentials.
Run a clean offline test
Disconnecting from the internet after loading a panel is prone to false positives because the service worker, browser cache, and IndexedDB still hold old data. First clear the test profile, block external domain names, and then reopen the application. Record which panels are normal, which ones show old cache, and which ones report errors. Check that the timestamp clearly identifies that the data has expired. Offline mode should degrade gracefully rather than disguise old information as real-time information.
Preserve variant and map configuration when upgrading
Save the commit, .env.local variable name, PMTiles URL, Redis schema, and reverse proxy configuration before upgrading.
|
|
Build in the new working tree first, do not directly overwrite the running directory. The setting format of the front-end localStorage may change. Check the variant, layer and refresh cycle after the upgrade.
Self-hosting completion checklist
- The page with the required variant can be built.
- Docker image ports come from inspect, not guesswork.
- All API keys are outside of Git.
- Does not silently go to the cloud when on-premises LLM fails.
- PMTiles returns a Range request.
- Redis, Ollama and internal services are not exposed to the public network.
- Each real-time data source has a last updated time.
- The offline test can distinguish between cache and real availability.
- License checked for commercial use.
World Monitor’s self-hosting boundaries depend on how many live data sources you retain. Drawing the network dependencies clearly first, and then deciding whether to use a local front end, privacy summary or complete isolation is more reliable than directly pursuing “one Docker command”.
First distinguish between web pages, CLI, REST API and MCP
This section solves the problem of “first distinguishing between web pages, CLI, REST API and MCP”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
For World Monitor, this is based on the following: Public MCPs allow tools to be listed, but calls that require authorization still require an API Key or OAuth; aggregate intelligence returned must be traced back to the original source. Don’t accidentally open more permissions at this stage.
|
|
Preserve command output and timestamp after execution. If the output depends on temporary variables in the current terminal, open a new terminal and check again.
What can be verified by exposing tools/list?
Process in the following order:
- Read the actual version and current configuration.
- Change only one setting relevant to this section.
- Run a read-only or revocable request.
- Check logs, exit codes, and final files.
- Revert the previous modification if it fails.
|
|
The completion standard here is not the appearance of the interface, but “what can be verified by public tools/list” with repeatable results.
Get and save World Monitor API Key
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| Obtain and save World Monitor API Key | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
|
|
Once the stop signal in the table appears, undo the changes in this section first and do not continue with subsequent automation.
Register Streamable HTTP MCP in Codex
Prepare a success sample and a failure sample around “Registering Streamable HTTP MCP in Codex”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
|
|
It is recommended to record the following four items:
- Pre-execution version or Git commit.
- Actual input, no secret value recorded.
- Observable output, status code or diff.
- Recovery actions and review results after recovery.
If the cause of the failure is still unclear, modify only one variable at a time; do not change the port, runtime, provider, and proxy at the same time.
Use CLI to run a country risk query first
This section addresses “Using the CLI to run a country risk query first.” First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
Restrict MCP results to read-only research
|
|
The completion criterion here is not interface appearance, but “restrict MCP results to read-only studies” with reproducible results.
How to return news excerpts to the original source
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| How to return news summaries to the original source | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
Market and geographical data cannot be confused
Prepare a success sample and a failure sample around “Market and geographical data cannot be confused”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
Handle 401, 403 and the tool list is empty
This section solves “Handling 401, 403 and empty tool list”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
|
|
Control query scope and call cost
The completion standard here is not the appearance of the interface, but “controlling the query scope and call cost” to have repeatable results.
Revoke keys and delete MCP configuration
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| Revoke keys and delete MCP configurations | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
|
|
A replicable intelligence verification checklist
Prepare a success sample and a failure sample around “a replicable intelligence verification checklist.” Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
How to choose between OAuth and API Key
This section solves “How to choose OAuth and API Key”. First record the current state, then perform the minimum action, and finally confirm the result with independent evidence.
Limit the countries and indicators allowed to be queried
The completion criterion here is not that the interface appears, but that “limiting the countries and indicators allowed to be queried” has repeatable results.
Cross-validate two sources for the same event
| What to check | Acceptable performance | Signals that you need to stop |
|---|---|---|
| Cross-validate two sources for the same event | Clear input and output scope | Automatically expand to other projects or accounts |
| Permissions | Get only the permissions you need to complete the task | Require administrator rights or full key |
| Log | Failed to locate and has been desensitized | Token, Cookie or private text appears |
| Rollback | Can restore the previous state | Modifications are irreversible and there is no backup |
Delete dead World Monitor connections
Prepare a success sample and a failure sample around “Delete dead World Monitor connection”. Successful samples verify the normal path, and failed samples verify whether the restrictions really take effect.
World Monitor FAQ
Is it possible to skip the test environment and use World Monitor directly in the official project?
Not recommended. Complete at least one minimal success request, one intentional failure, and one recovery drill first.
The World Monitor command can be run but the result is incorrect, where should I check first?
First check the input range, actual effective configuration and upstream response, and then check the model summary. A normal process does not mean that the business results are correct.
How to prevent World Monitor keys or tokens from entering Git?
Use system environment variables, secret management, or configuration files outside the project, and search the diff before committing. Keys must be rotated after a breach is discovered.
What is the most common thing to miss when upgrading World Monitor?
It is most easy to miss configuration format, default listening address, permission scope and cache compatibility. Save the version and verification samples before upgrading.
Project resources
- World Monitor Official Repository
- World Monitor Architecture Document
- World Monitor update record
- World Monitor Contribution and Development Document
World Monitor Docker Compose Self-Hosting Notes
koala73/worldmonitor is a real-time global intelligence dashboard for aggregating news, geopolitical events, infrastructure status, and different topic channels. It is closer to a situational awareness page and works well as a self-hosted news monitoring entry point.
Project repository:
https://github.com/koala73/worldmonitor
Official site:
Start Locally
The README quick-start commands are:
|
|
After startup, check whether the default page works before thinking about deployment.
Running Different Channels
The project includes several channel-specific development commands:
|
|
If you only care about technology news, start with dev:tech. If you care about finance or commodities, try dev:finance and dev:commodity.
Build and Checks
Before committing or deploying, it is worth running:
|
|
These commands can catch TypeScript type issues and production build problems early.
How to Use It
World Monitor fits these uses:
- Build a real-time news entry point for yourself.
- Create topic dashboards for a team, such as technology, energy, finance, or commodities.
- Observe multi-source news streams instead of relying on recommendations from a single platform.
- Extend it into an internal intelligence dashboard.
Deployment Suggestions
The README mentions a self-hosting guide, and deployment options include Vercel, Docker, and static deployment. Run it locally first, then deploy to Vercel or your own server.
When using it, remember that a news aggregation dashboard only helps you notice signals faster. It does not mean every piece of information has been verified. For finance, geopolitics, and security topics, it is best to open the original sources and cross-check them.