@harshankur/viewcounter 3.1.0 → 3.3.0

package/.env.example

@@ -1,7 +1,7 @@
 # ViewCounter configuration
 #
 # Copy to `.env` and fill in. Every value here can also come from dbInfo.json /
-# allowed.json, which take precedence — see config/index.js for the resolution
+# allowed.json, which take precedence. See config/index.js for the resolution
 # order (config file > environment variable > built-in default).
 #
 # Anything marked Required is checked at startup in production: the server
@@ -37,7 +37,7 @@ CORS_ORIGINS=https://example.com,https://www.example.com
 # Credentials for the analytics READ endpoints (/stats, /views, /trends, ...),
 # comma-separated, sent by clients as the `x-api-key` header. Keys shorter than
 # 32 characters are ignored. List several so one consumer's key can be revoked
-# without rotating everyone else's. With none set, the read API returns 503 —
+# without rotating everyone else's. With none set, the read API returns 503:
 # it fails closed rather than serving your analytics to anyone who asks.
 #   Generate one with:
 #   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
@@ -59,6 +59,17 @@ ADMIN_API_KEYS=
 #   Generate one with: openssl rand -base64 24
 #ADMIN_PASSWORD=
 
+# How long an admin UI session lasts: it ends after this long without use, or
+# this long after signing in, whichever comes first. Sessions are kept in the
+# database (only a hash of the token), so they survive restarts, and using the
+# UI, even just reading it, keeps one alive. A number with m, h, or d, such as
+# 30m, 12h, or 7d. A malformed value, or an idle time longer than the maximum,
+# stops the server from starting. Erasing views permanently asks for the
+# password again unless it was entered in the last 15 minutes, however long
+# the session. Defaults: 7d idle, 30d maximum.
+#ADMIN_SESSION_IDLE_TIMEOUT=7d
+#ADMIN_SESSION_MAX_AGE=30d
+
 # Number of reverse proxies in front of this service, or a comma-separated list
 # of trusted proxy CIDRs. Leave unset if nothing proxies it.
 #
@@ -72,8 +83,8 @@ ADMIN_API_KEYS=
 # Where the visitor-hash secret is persisted. Generated with a CSPRNG on first
 # run at mode 0600. This secret is the only reason a stored visitor hash cannot
 # be brute-forced back to the IP that produced it, so back it up with the same
-# care as the database password — and note that replacing it makes existing
-# hashes unlinkable from new ones (which is deliberate, not a bug).
+# care as the database password. Replacing it makes existing hashes
+# unlinkable from new ones (which is deliberate, not a bug).
 #VISITOR_SECRET_PATH=/var/lib/viewcounter/.visitor-secret
 
 # Supply the secret directly instead of persisting a file. Useful for
@@ -95,8 +106,8 @@ DB_PORT=3306
 PORT=3030
 
 # Defaults to `production`. Set to `development` for local work. This does not
-# change what is returned to callers — errors never include internal detail in
-# any environment — but it does relax the startup checks above.
+# change what is returned to callers (errors never include internal detail in
+# any environment), but it does relax the startup checks above.
 #NODE_ENV=production
 
 # Operational log verbosity: debug | info | warn | error | silent.
@@ -104,7 +115,9 @@ PORT=3030
 LOG_LEVEL=info
 
 # Rate limiting, applied per client IP across all endpoints. This is the
-# single-abuser backstop.
+# single-abuser backstop. Engagement reports (/engage, two a minute from each
+# page being read) have a separate budget of the same size, here and per app,
+# so they never use up the one page views depend on.
 RATE_LIMIT_WINDOW_MS=60000
 RATE_LIMIT_MAX=100
 
@@ -125,11 +138,24 @@ UNIQUE_VISITOR_WINDOW_HOURS=24
 # 0 keeps trash until someone empties it by hand. Default: 30.
 TRASH_RETENTION_DAYS=30
 
-# Days an entry stays in the view register log (one row per accepted view)
-# before it is removed. The log holds no personal data; this only bounds its
-# size, and never touches the views themselves. The admin operation log is
-# never pruned. 0 keeps the view log forever. Default: 90.
+# Days an entry stays in the tracking log (one row per accepted view, plus
+# per-minute counts of bots and refused requests) before it is removed. The
+# log holds no personal data; this only bounds its size, and never touches the
+# views themselves. The admin operation log is never pruned. 0 keeps the
+# tracking log forever. Default: 90. (The name predates the tracking log.)
 VIEW_LOG_RETENTION_DAYS=90
 
+# A city database, for the region and city of each view. Countries work
+# without one (a GeoLite2 country database ships in the package). Point this
+# at a MaxMind-format .mmdb file:
+#   - DB-IP IP to City Lite, free under CC BY 4.0, updated monthly:
+#     https://db-ip.com/db/download/ip-to-city-lite (the admin UI credits it
+#     as its licence asks)
+#   - or MaxMind GeoLite2 City, which needs a free MaxMind account
+# The file is read again when it changes, so a monthly download that replaces
+# it needs no restart. Unset: region and city stay empty. A path that cannot
+# be opened stops the server from starting.
+#GEOIP_CITY_DB=/var/lib/viewcounter/dbip-city-lite.mmdb
+
 # Device size buckets accepted on /registerView, comma-separated.
 #ALLOWED_DEVICE_SIZES=small,medium,large