Back up your events dashboard and host it on a server
By Flavio
Back up Events Logger with a JSON export or a full copy of its data folder, restore it safely, and move the dashboard to a server behind a login.
Your self-hosted events dashboard has months of signups, orders and deploys in it, and it all lives in one folder on your Mac. If that disk dies, or you wipe the folder by mistake, the history is gone. And sooner or later you’ll want the dashboard on a server, so a backend that isn’t on your Mac can log to it.
Events Logger keeps everything in a SQLite database inside its data/ folder. It gives you two ways to back it up: a JSON export from its CLI, and a plain copy of that folder. They don’t save the same things, and picking the wrong one is how people lose their API key or their starred events.
We’ll take both kinds of backup, move the dashboard to a new machine with its key intact, restore a JSON export into a fresh install, and merge a backup without creating duplicates. Then we’ll go through what a hosted copy needs, because the shipped dashboard has no login.
What you need
Events Logger runs on Node.js. The app page says “Node.js 18+ · self-hosted web app”, but its SQLite driver, better-sqlite3 12, declares support for Node 20 and newer, so use Node 20 or later. You also need npm. I ran everything here with Node 22.
After buying, download the source zip from your Polar receipt and unzip it. The receipt always has the latest version. If you haven’t used the dashboard yet, Send signup and order events from your app to your own dashboard covers the first start and the first event, and Track deploys and errors as events shows deploy scripts and insight cards.
In this tutorial the install lives in /Users/flavio/apps/events-logger, and the project is called Garden Shop. Both are examples, and so is the project ID you’ll see in the output. Run every command from the folder you unzipped, because that’s where the CLI looks for the database.
For hosting you’ll also need a machine with persistent storage and a way to put HTTPS and a login in front of the app, like a reverse proxy with authentication.
As a preflight check, ask the CLI for the load options. It’s the one command here that can wipe data, so read it before you need it:
node cli/index.js load --help
Usage: events-cli load [options]
Load data from a JSON file (replaces all existing data)
Options:
--file <path> JSON file to load
--db <path> Database path (default:
"/Users/flavio/apps/events-logger/data/events.db")
--merge Merge with existing data instead of replacing
-h, --help display help for command
The default --db path is built from your current folder, so it tells you which database a command will touch.
Export your events to JSON
The JSON export is the backup you can read, diff and keep in any storage. It’s also how you take data out of Events Logger to use elsewhere, since the file is plain JSON with your projects, categories, events and insight cards. Without a backup, a single rm -rf data or a bad load takes every event with it, and SQLite doesn’t keep an undo history. The export opens the database read-only and doesn’t need the server, so you can run it while the dashboard is up and logging.
node cli/index.js export --file garden-shop-backup.json
Exported to garden-shop-backup.json
1 projects, 2 categories, 3 events, 1 insights
The counts are your first sanity check. If you expected thousands of events and see zero, you ran it from the wrong folder. Here’s the top of the file:
{
"exportedAt": "2026-11-16T06:16:30.806Z",
"projects": [
{
"id": "dcj70tefm8ke",
"name": "Garden Shop",
"created_at": 1794809784
}
],
"categories": [
{
"id": 1,
"project_id": "dcj70tefm8ke",
"name": "orders",
"created_at": 1794809788
}
]
}
Each event in the events array has every column of the table, including favorited and url. Times are Unix seconds.
Two things are missing, though. The export doesn’t include the app_settings table, which holds your installation’s API key. And as we’ll see when we restore, the star on a favorite event doesn’t survive the trip back in.
Running the same command again overwrites the file without asking. Put the date in the name if you want to keep more than one:
mkdir -p backups
node cli/index.js export --file backups/events-$(date +%F).json
Exported to backups/events-2026-11-16.json
1 projects, 2 categories, 4 events, 1 insights
The mkdir matters. Without it, the command crashes with Error: ENOENT: no such file or directory, because the export doesn’t create folders for you.
Take a full backup of the data folder
The docs are clear about the one backup that keeps everything: “For a full backup including application settings and the API key, stop the server and copy its data/ directory to protected storage.” This is the backup you want before moving to another machine, because your backends and scripts already use that API key. Lose it, and every integration starts failing until you update them all. The folder copy also keeps event IDs and favorites, which the JSON restore doesn’t.
Stop the server first with Control-C in its terminal. Then look at what’s in the folder:
ls -la data
4096 events.db
32768 events.db-shm
206032 events.db-wal
I trimmed the listing to sizes and names. There are three files, and the small one is the database. Events Logger opens SQLite in WAL mode, short for write-ahead log: new writes go to events.db-wal first, and SQLite folds them into events.db later. On my test install every table and every event was still in the WAL file after the server stopped. That’s why you copy the whole folder, not one file:
mkdir -p ~/backups/events-logger
cp -R data ~/backups/events-logger/data-2026-11-16
“Protected storage” is the docs’ wording for a reason. That folder contains the API key in plain text, and SQLite has no user permissions of its own: whoever can read the files reads everything. Treat the copy like a secret, not like a log file.
Move the dashboard to another machine
Moving is the full-folder backup from the last step plus one detail that trips people up: where you start the server from. The database path isn’t in a config file. The app builds it from the folder the process runs in, as data/events.db under the current directory. Start the server from anywhere else and it creates a brand-new empty database next to you, with a new API key, and your dashboard looks wiped even though the data is safe where you left it.
Example 1: move Garden Shop to a new machine and keep the key. On the new machine, unzip the same source zip, install and build. The docs say the standalone Node entry is dist/server/entry.mjs:
cd /Users/flavio/apps/events-logger
npm install
npm run build
[build] Server built in 574ms
[build] Complete!
That’s the end of the build output. Then copy the stopped data/ folder into the install and start the server from that same folder:
cp -R ~/backups/events-logger/data-2026-11-16 data
HOST=127.0.0.1 PORT=4501 node dist/server/entry.mjs
[@astrojs/node] Server listening on http://127.0.0.1:4501
HOST and PORT are read by Astro’s Node adapter, as its Node adapter docs describe. Without them, this build listens on localhost port 4321. I used 4501 because 4321 was busy on my Mac.
Then I pushed with the original key:
node cli/index.js push --api-key "$EVENTS_API_KEY" --project dcj70tefm8ke \
--category orders --title "Order shipped" --url http://127.0.0.1:4501
Event pushed: Order shipped [orders]
The old key worked, the event IDs were the original ones, and the favorite still had its star. Nothing in your backends needs to change except the URL.
Example 2: the backup that holds nothing. Here’s what changes if you copy only events.db instead of the folder. I tried it, then exported from the copy:
mkdir only-db
cp ~/backups/events-logger/data-2026-11-16/events.db only-db/
node cli/index.js export --db only-db/events.db --file only.json
SqliteError: no such table: projects
The real output is a Node stack trace with that line in it. The file was a valid, empty SQLite database, because the tables lived in the WAL file I left behind. sqlite3 only-db/events.db "select count(*) from events" failed the same way, with no such table: events. The fix is to copy the full data/ folder with all three files, after stopping the server.
Restore a JSON export
Restoring is where you can lose data for real, so it’s worth knowing exactly what load does before you run it. By default it deletes every event, insight, category and project in the target database, then inserts the ones from the file, all in one transaction. There’s no confirmation prompt and no undo. If you point it at your live database with an old export, everything logged since that export is gone. So export the current state first, and use --db to restore into a separate database when you only want to look at an old backup.
Here’s a restore into a fresh install, in a second folder with no data/ yet. load creates the folder and the tables itself:
cd /Users/flavio/apps/events-logger-restore
node cli/index.js load --file ../events-logger/garden-shop-backup.json
Loaded from ../events-logger/garden-shop-backup.json
1 projects, 2 categories, 3 events, 1 insights
Restart the dev server to see the changes.
The project keeps its ID, so the Garden Shop feed is there with the same URL. The events don’t keep theirs: in my test they came back as IDs 7, 8 and 9 instead of 1, 2 and 3. The insert never copies the favorited column either, so starred events come back unstarred.
Example 3: the restored install rejects your key. I started the restored copy and pushed an event with the old installation’s key:
node cli/index.js push --api-key "$EVENTS_API_KEY" --project dcj70tefm8ke \
--category orders --title "Order shipped" --url http://127.0.0.1:4500
Error: Invalid API key
The command exits with 1. The JSON had no API key in it, so the server generated a new one on its first start, and the old one means nothing to it. You have two ways out: copy the new key from the home page into every backend that logs, or restore from the full data/ folder instead, which keeps the original key.
Merge a backup without duplicates
--merge sounds like the safe option, and it is safer: it skips the delete step. But it doesn’t compare events, and that catches people out. Projects are matched by ID and replaced, categories are skipped when the name already exists, and insight cards are matched by project and title, so those all settle. Events have no natural key in the file, so load inserts every one of them again. Merge a file twice, or merge an export back into the database it came from, and each event shows up twice in the feed and in the charts.
I merged the same three-event export into the restored database, which already had those three events:
node cli/index.js load --file ../events-logger/garden-shop-backup.json --merge
sqlite3 data/events.db "select count(*) from events"
Loaded from ../events-logger/garden-shop-backup.json
1 projects, 2 categories, 3 events, 1 insights
Restart the dev server to see the changes.
6
Six events, three of them copies. The sqlite3 command I used to count them ships with macOS.
So merge only data that isn’t in the target yet, like the export of a second install you’re folding into this one. To undo a bad merge, run load again without --merge from the export you took before. That replaced the six events with the original three in my test. Restart the server after any load, as the CLI says.
Host it behind a login
This is the part not to skip. The docs say the shipped dashboard “has no login, displays the global API key on its home page, and has unauthenticated reading and dashboard mutation routes.” The API key only protects ingestion. Anyone who can load the home page can read the key, and anyone who can reach the API can read your events without one. Put it on a public port as-is, and your signups, order notes and user IDs are public.
You can see this on your own machine. With the server running, ask for events without any key:
curl "http://127.0.0.1:4501/api/events?project=dcj70tefm8ke"
{"events":[{"id":4,"projectId":"dcj70tefm8ke","category":"orders","title":"Order shipped","description":null,"icon":null,"tags":null,"url":null,"userId":null,"notify":false,"favorited":false,"createdAt":"2026-11-16T06:16:58.000Z"}]}
I cut the list to one event. It answered with no Authorization header at all.
The docs list what a hosted copy needs: the Astro Node server, HTTPS, persistent storage for data/, and an authentication gateway protecting every dashboard and API route. In practice that’s a reverse proxy on the same server that handles HTTPS and asks for a login, with Events Logger listening only on 127.0.0.1 behind it. Keep the default host, or set HOST=127.0.0.1, so the app port isn’t reachable from outside.
“Every route” includes /api/events. Your backends then need to pass the gateway too, or sit on the same private network. Keep the API key in their server-side secrets, never in browser code.
Run the curl above from a different machine against your public URL once you’re done. It should get the gateway’s login response, never the JSON. The README adds two checks for a hosted copy: rotate API keys that were exposed, and rate-limit public ingestion endpoints.
Make backups a habit
The JSON export is cheap and safe to run while the server is up, so it’s the one to schedule. A dated file per day in a backups folder, run from the install folder, gives you a history you can diff when something looks off. Keep the full folder copy for the moments that need the key: before an upgrade from a new source zip, before a move, and before any load without --merge.
When you download a new version from your Polar receipt, unzip it to a new folder and copy the stopped data/ folder into it. The app creates missing tables and columns when it opens the database, and your old install stays untouched in case you need to go back.
If something looks wrong
- If
exportprintsDatabase not found at /Users/flavio/.../data/events.db, you’re in the wrong folder. Run it from the install folder, or pass--dbwith the path. - If
exportcrashes withError: ENOENT: no such file or directory, the folder in--filedoesn’t exist. Create it withmkdir -pfirst. - If an export or a script fails with
SqliteError: no such table: projects, the database file came without its-walfile. Stop the server and copy the wholedata/folder. - If every integration gets
Error: Invalid API keyor a401after a restore or a move, the server created a new key. Copy it from the home page, or restore the fulldata/folder that has the old one. - If the dashboard is empty after a move, check the folder you started the server from. A
data/folder appeared there with a new database, and yours is somewhere else. - If the feed shows every event twice, you merged a file that was already loaded. Run
loadwithout--mergefrom an export taken before the merge. - If starred events lost their stars after a restore, that’s the JSON path. Only the full
data/copy keeps favorites. - If
loadstops withFile not found: garden-shop-backup.json, the path is relative to your current folder. Use the full path to the export.
Get Events Logger
Track signups, orders, deploys and errors in your own SQLite dashboard. Includes an HTTP API, CLI, charts and full MIT source.
See Events Logger → · Read the docs · $20. See the app page for tax details, with full source code.
Want me to talk about your product? You can sponsor this site.