Reset a demonstration organization every night

A public demonstration collects other people’s typing. A nightly reset makes the organization become the file it was stored as: its records, its logins, its sessions, its images and its audit log, all at once.

The reset is a property of the organization, not a declaration of an application. No .mtd file mentions it. An application cannot say “forget everything that happened”, because the answer has to include logins and sessions that no application model can name.

Everything after the template is lost

A reset is not an undo of one act. Every record written since the template was taken is gone, and there is no way to get it back. Use this on a demonstration organization only.

What a template is

A template is a complete copy of the organization, stored beside it:

File	What it holds
<name>.template.db	the database: records, logins, sessions, the model, the audit log
<name>.template.blobs/	the images that database refers to

The copy is transactionally consistent and carries no write-ahead log, so restoring it is a byte copy. After a reset the live database is byte-identical to the template.

The template holds no schedule records of its own, so the restored organization gets a fresh clock and resets again the following night.

Switch the nightly reset on

1. Open /matterdata/jobs on the organization’s own address.
2. Find the Nightly reset card and open Switch the nightly reset on.
3. Type the time in Time, as HH:MM.
4. Type the time zone in Time zone.
5. Press Switch on.

The form is in a closed disclosure, so switching the reset on takes two deliberate presses. It needs no JavaScript.

If the organization has no template yet, switching on takes one from the current state. The form says so before you press the button. That state is what the organization returns to every night.

If a template already exists, switching on keeps it. Switching the reset off for an afternoon and on again at 17:00 does not promote the afternoon’s typing to the good state. Replacing a template is a separate act, described below.

Which time zone the reset keeps

The zone is stored with the schedule and defaults to UTC. A regional default would make the engine state a fact about the world that nobody wrote down.

Write UTC, or an Area/Location name such as Europe/Berlin. An abbreviation is refused:

• an abbreviation is ambiguous. CST is US Central, China and Cuba.
• EST, MST and HST are fixed offsets that never observe summer time. EST is −05:00 in July, while New York is −04:00. CET is not one of these, and it is still refused, because the ambiguity applies to all four.

The organization keeps its own zone here. An application’s timezone: decides how its pages are drawn; it does not decide when the organization resets.

Change the time without touching the template

Open Change the time, type the new time and zone, and press the button of the same name. It writes the new schedule and leaves the template exactly as it is.

Switch the nightly reset off

Press Switch the nightly reset off. The schedule goes and the template stays.

That asymmetry is deliberate. Switching off is the reversible half of the pair. A switch that also deleted the template would make switching on again capture the current state. That state is the one the reset exists to undo.

Replace the template with the current state

Open Capture the current state as the template and press Capture the template again now. The organization is stored as it is now, and the previous template is deleted. This is the destructive act on the page, and the previous good state stops existing.

The act sits behind a closed disclosure with its own confirmation, so it takes two deliberate presses and needs no JavaScript.

Use it after you have prepared the demonstration data you want visitors to find. Do not use it to “save progress” on an organization that visitors have already typed into.

The act does not change the schedule. What the organization becomes and when it becomes it are two decisions.

Reset now

Open Reset now and press Queue now. The act marks the reset as due. The page replaces nothing itself.

The running service performs the swap. It starts within a minute while that service has the organization open, and otherwise within an hour, when the scheduler next reads the directory.

The same act is available at a command line, on an organization that nothing is serving:

matterdata reset -dir data -tenant showcase

That command also replaces nothing. It marks the record due and prints both waiting times. The swap needs to drain the requests that are still reading the old file, and only the serving process holds that state.

Switch it on at install time

matterdata install -dir data -tenant showcase -app dsl/examples/showcase \
  -demo -reset-nightly "03:00 Europe/Berlin"

-reset-nightly takes 03:00, or "03:00 Europe/Berlin". The zone defaults to UTC and is always stored. The template is written from the state install produced.

What a visitor sees while the swap runs

A request already being served finishes on the old file. A request that arrives during the swap waits and is then served from the new one.

Measured on the showcase demonstration: the swap takes 14 ms for a 552 KiB database. Re-installing the same demonstration from its sources takes 496 ms.

If a request is still in flight when the drain gives up, the reset is postponed to the next minute rather than failed. A failure would move the clock to tomorrow and skip a night.

Back up three things

An organization that resets itself has three things to copy, not two:

1. <name>.db, the database.
2. <name>.blobs/, its images.
3. <name>.template.db and <name>.template.blobs/, the state it returns to.

A backup without the third restores an organization that resets itself into a state you no longer have.

What the audit log records

Every act on this page that succeeds writes one admin.command event, kept for 365 days: switching the reset on, changing its time, switching it off, replacing the template, and marking a reset due. The actor is the administrator who pressed the button. A refused act records nothing.

A successful reset writes no job.run event. The log it would be written into is the file being replaced, and a record in it would break the byte identity the design rests on. A failed reset does write one: that file survives, and it is where an operator asks why the demonstration is still vandalized.

Read Security model for every audit class and its retention.