Deployment

Closing the app to anonymous visitors

A cluster row names a pathogen, a ward or an institution, and a date range; in a small population that combination is often enough to identify who, even without the line list. An instance that is reachable by anyone other than the colleagues it is meant for - rather than sitting behind network controls that already make that impossible - should close that gap rather than rely on the open default. Set access.require_login to true in your EPISODIC_CONFIG YAML:

access:
  require_login: true

With require_login: false (the shipped default), an instance is already behind network controls that make anonymous reachability impossible often enough that closing it too would just be a second sign-in nobody needed; weigh the setting deliberately for your own deployment rather than leaving it at either value by habit.

With require_login: true:

An anonymous visitor gets a sign-in prompt and nothing else: no navigation, no status strip, not one row of data. This is enforced on the server, not in the browser - none of those screens is rendered for a session that has not signed in, so nothing they would contain is ever serialised into the page. There is correspondingly nothing for a browser’s developer tools to uncover by removing the prompt: what is not sent cannot be inspected. The same gate covers inputs a client can set for itself, not only the links the navigation offers.

This is a YAML-only setting on purpose, with no override on the Settings screen: a login wall an admin account can switch off from inside the app is a login wall that falls with that one account. Turning it off takes file access to the machine. The Settings screen does report which way it is set, so an admin can confirm it without SSH access.

It is excluded from config_hash alongside notifications: it governs how the instance is operated, never what a detection run computes, so turning it on does not make historic runs look incomparable with current ones.

There are exactly two roles:

• "epidemiologist" - by definition, assesses clusters and classifies them. Can do everything a viewer can, plus classify, close, and mute clusters, and re-render reports on demand.
• "viewer" - read-only. Sees exactly what a signed-in epidemiologist sees, including patient-level detail, but cannot record an assessment.

Independent of role, an account can additionally be flagged is_admin, which unlocks the Settings screen: managing notification channels and recipients, creating accounts and changing their role/admin/active state, and exporting the resolved configuration. Detection parameters themselves stay read-only there deliberately - changing them is still a EPISODIC_CONFIG YAML change, so every past result stays traceable to the exact configuration that produced it (see “Configuration” above).

Sys.setenv(EPISODIC_DB = "/path/to/episodic.sqlite")  # or pass db_path explicitly below

episodic_add_user(
  username = "jdoe",
  role = "epidemiologist",  # or "viewer"
  full_name = "Dr Jane Doe",
  email = "[email protected]",
  password = "a-temporary-password"
)

episodic_add_user() takes db_path (defaulting to EPISODIC_DB, see Environment variables), not an open connection - it opens and closes its own via episodic_db_open(), so adding an account is one call at the console. The account is created with must_change = TRUE, so its first real sign-in forces the holder to set their own password before continuing. Pass is_admin = TRUE to give the new account Settings-screen access as well - you need at least one such account to manage anything from the dashboard itself; every account after that can be added either way.

Watching sign-ins

Both outcomes are recorded. A successful sign-in becomes a login event on the account; a refused one is written to episodic_app_login_failure with the username as typed and which of three reasons it was - no account with that username, wrong password, or account deactivated. The sign-in screen itself still says none of that to whoever is typing: unknown username and wrong password are one generic refusal to them, so that a stranger cannot use the login form to find out which usernames exist. The distinction is for the operator, in the record, afterwards.

Both appear on the Activity screen, where the filter chips at the top narrow the log to sign-ins alone. A run of refused attempts on one account, or a series of usernames nobody has, is then visible the same day it happens.

Sign-in rows are the one part of the Activity screen withheld from a reader who has not signed in - on an instance running with require_login: false, “who has an account here, and which usernames somebody has been trying” is precisely what not to hand a visitor.

This is a record, not a defence: EpiSODIC has no account lockout and no rate limiting, and deliberately so - a surveillance dashboard that locks an epidemiologist out mid-outbreak because somebody else mistyped their username is worse than the attack it prevents. Keeping attackers off the port is your network’s job (see the top of this vignette); noticing that one got as far as the login form is this log’s.

Which servers this is tested against

Every release runs the full test suite against a real MariaDB 11 and a real MySQL 8 server, not only against SQLite, and a schema change either server rejects fails the build. The suite has also been run by hand against MariaDB 10.11.

Both are tested because they are not the same server. MariaDB and MySQL disagree about how a foreign key written on the column rather than at the end of the table should be treated - MariaDB creates it, MySQL parses it and discards it - and EpiSODIC’s schema is written in the form SQLite wants. It is translated for these servers so that the constraints exist on all three, and the suite counts them on a live server rather than assuming.

CHECK constraints are enforced from MariaDB 10.2.1 / MySQL 8.0.16 onwards; on older servers they are accepted but silently ignored.

Sharing a schema with something else

EpiSODIC does not need a database of its own. Its tables can sit in a schema alongside another application’s, which is a common way to be given a database by an infrastructure team, and every operation that enumerates tables - creating the schema, overwrite = TRUE, and episodic_db_truncate() - is scoped to EpiSODIC’s own tables and cannot touch a co-tenant’s.

If you already have a MariaDB or MySQL database

One created by EpiSODIC 0.15.x or earlier has no foreign keys. They were declared in the schema and the server discarded them without saying so, so such a database has been accepting rows that reference nothing. There is no migration that adds them, because a constraint cannot be added to a table that already violates it: recreate the database with episodic_db_create(overwrite = TRUE) and load your case data again. SQLite databases are unaffected and always had them.

To check what your server actually created:

SELECT COUNT(*) FROM information_schema.REFERENTIAL_CONSTRAINTS
 WHERE CONSTRAINT_SCHEMA = DATABASE()
   AND TABLE_NAME LIKE 'episodic\_%';

Anything other than 56 means the schema and the server disagree, and the suite’s own live tests check that same number against a live server on every run.

What a migration does, and does not do

• It never deletes data. Migrations add tables, add columns and backfill values, and never rewrite anything. A column is dropped only when EpiSODIC no longer uses it and it holds no value on any row; a column holding data is kept, and the log says so. Your surveillance history, your assessments and your audit trail are carried forward untouched.
• It runs before the run. Each step is a transaction of its own, applied before the run writes anything, never inside the detection run’s own transaction.
• It copies a SQLite database first. The file is copied beside itself as <file>.schema-<from>-to-<to>.bak before the first step, and the log names the copy. If a copy with that name already exists from an earlier attempt at the same upgrade, it is kept rather than replaced. A MariaDB or MySQL database is not copied, because a server’s backups belong to whoever runs the server; the log says so.
• One process migrates at a time. A scheduled run and a manual episodic_db_migrate(), or two servers sharing one MariaDB schema, can meet the same out-of-date database at once. One of them migrates, the other waits, finds the work done, and carries on.
• Old databases are adopted. A database built by EpiSODIC 0.12.x or earlier carries no version at all, since the version table postdates it. It is adopted at version 1 and brought forward from there.
• Skipped versions are fine. An instance that skips versions (0.19 straight to 0.25) is brought through every step in between, in order.

When the schema is not the application’s to change

Many hospitals do not let an application change its own database schema: the account EpiSODIC connects with may read and write rows but not CREATE or ALTER, and schema changes go through a DBA and change control. For such an instance, turn the automatic migration off in your EPISODIC_CONFIG YAML:

database:
  auto_migrate: false

A run that then meets a database behind the package does not start. The refusal is:

• printed in the run log, naming both schema versions and the command to run;
• recorded as a failed run, so the gap is explained on the Activity screen once the database has been migrated.

Until then, the dashboard of the upgraded package cannot open the database either: it refuses it with the same explanation rather than reading a schema it does not know.

Whoever holds the privileges then runs, from an account that has CREATE, ALTER, INDEX and REFERENCES on the database:

episodic_db_migrate()   # or episodic_db_migrate(db_path)

If auto_migrate is left on and the account lacks those privileges, the run fails the same way, and the message says which privileges are missing rather than passing on the server’s CREATE command denied.

Under MariaDB and MySQL, a schema change commits on its own, so a step that fails part-way may leave part of itself in place. Every step skips what it finds already done, so running the migration again once the cause is fixed is the correct response.

Going back

Migrations only go forward. A package older than its database refuses to open it, and tells you to upgrade the package - or, if the upgrade is already installed, to restart the R process still running the old one. A dashboard started before the upgrade is the usual case: the scheduled run has migrated the database under it.

To really go back, restore the SQLite copy taken before the migration, or your own MariaDB/MySQL backup.

Behind a reverse proxy

The dashboard holds its connection open as a WebSocket, not a sequence of ordinary HTTP requests, so a proxy in front of it needs the Upgrade handshake forwarded, not only /. Give that connection a generous idle timeout too: an epidemiologist reading one dossier for minutes sends almost nothing over the socket in the meantime, and a timeout sized for ordinary HTTP traffic can drop a quiet session and grey out the page while the R process behind it is still running.