Command-Line Interface parameters

Required parameters

Most of the parameters have sane defaults and don't require customization. There are only a few parameters the user has to define:

1. SECRET - secret key, can be any long and hard-to-guess string
2. REMARK_URL - URL pointing to your Remark42 server, i.e., https://demo.remark42.com
3. At least one OAuth2 provider, either via AUTH_<PROVIDER>_CID + AUTH_<PROVIDER>_CSEC or via AUTH_CUSTOM_*

The minimal docker-compose.yml has to include all required parameters:

version: "2"

services:
  remark42:
    image: ghcr.io/umputun/remark42:latest
    restart: always
    container_name: "remark42"
    environment:
      - REMARK_URL=https://demo.remark42.com # URL pointing to your Remark42 server
      - SITE=YOUR_SITE_ID # site ID, same as used for `site_id`, see "Setup on your website"
      - SECRET=abcd-123456-xyz-$%^& # secret key
      - AUTH_ANON=true # enable anonymous commenting
      - AUTH_GITHUB_CID=12345667890 # OAuth2 client ID
      - AUTH_GITHUB_CSEC=abcdefg12345678 # OAuth2 client secret
    volumes:
      - ./var:/srv/var # persistent volume to store all Remark42 data

Complete parameters list

• command-line parameters are long-form --<key>=value, i.e., --site=https://demo.remark42.com
• multi parameters separated by , in the environment or repeated with command-line keys, like --site=s1 --site=s2 ...
• required parameters have to be presented in the environment or provided in the command-line

Custom OAuth2 integration

Custom OAuth2 integration currently supports only one custom provider at a time, and AUTH_CUSTOM_NAME must match ^[a-z0-9][a-z0-9_-]*$.

Security Considerations for auth.send-jwt-header

When auth.send-jwt-header=true is enabled:

• Security Impact: JWT tokens are stored in client-accessible cookies that can be accessed by JavaScript
• Vulnerability: This increases vulnerability to XSS attacks compared to server-set HttpOnly cookies
• Implementation Mitigations:
  • SameSite=Strict cookies to prevent CSRF attacks
  • Secure flag automatically added on HTTPS connections
  • __Host- prefix added on HTTPS to prevent subdomain attacks
  • Double Submit Cookie pattern with XSRF token matching the JWT ID

This configuration should only be used when:

1. You need cross-domain authentication support
2. You understand and accept the increased XSS risk
3. You have implemented strong XSS protections on your site

Trusted proxies and client IP

Remark42 keys per-IP rate limiting — and, when --votes-ip is enabled, vote de-duplication and the stored comment IP — on the client IP. When Remark42 runs behind a reverse proxy (nginx, Reproxy, Traefik, Cloudflare, an ALB, a k8s ingress, …) the TCP connection it sees comes from the proxy, not the visitor, so the proxy forwards the real client IP in a header and Remark42 reads it (priority: X-Real-IP, then CF-Connecting-IP, then X-Forwarded-For) to recover the real IP.

⚠️ Security note. Those headers can be set by any client. If Remark42 trusts them from everyone, a caller can send X-Real-IP: <anything> and rotate its apparent IP to bypass rate limiting and vote de-duplication. Use --trusted-proxy so Remark42 reads the forwarding headers only when the request actually arrives from your proxy.

--trusted-proxy / TRUSTED_PROXY takes a comma-separated list of networks (CIDR) or bare IPs. When set, the forwarding headers are honored only if the direct peer — the machine that opened the TCP connection to Remark42 — falls inside one of them; for a request from any other peer those headers are dropped and the real socket IP is used. When it is not set, the headers are trusted from any client: this preserves the historical behavior so existing deployments keep working, but leaves the bypass above open, and Remark42 prints a warning at startup. If Remark42 is reachable from the internet, set this.

Two conditions must both hold to be safe:

1. Trust the right peer. Point --trusted-proxy at the network your proxy connects from, and nothing wider.

2. Your proxy must set the IP itself. Trusting a proxy is not enough if the proxy relays what the client sent. Because Remark42 reads X-Real-IP first, the proxy must set X-Real-IP to the real connecting client and overwrite any client value. A proxy that only appends to X-Forwarded-For (Traefik, most cloud ALBs, k8s ingress, HAProxy defaults) or that derives X-Real-IP from a client-controlled X-Forwarded-For leaves the visitor in control of the reported IP even through a trusted proxy:

• nginx — safe with the manual's proxy_set_header X-Real-IP $remote_addr; (overwrites any client value).
• Reproxy — sets X-Real-IP, but derives it from an incoming X-Forwarded-For when present, so a directly-exposed Reproxy still lets a client choose it; front it with something that strips client X-Forwarded-For, or don't rely on it for per-IP controls.
• Cloudflare — does not set X-Real-IP, and a client-supplied X-Real-IP wins over CF-Connecting-IP; add a Cloudflare Transform Rule that sets X-Real-IP from CF-Connecting-IP and clears any inbound X-Real-IP / X-Forwarded-For.

Recommended --trusted-proxy per deployment:

Examples:

# docker-compose: nginx on the same network
TRUSTED_PROXY=172.16.0.0/12

# a single upstream proxy
--trusted-proxy=10.0.0.5

# multiple ranges (v4 and v6)
TRUSTED_PROXY=10.0.0.0/8,fd00::/8

Caveats:

• IPv6. CIDRs are matched by family — 172.16.0.0/12 (or 0.0.0.0/0) never matches an IPv6 peer. If your proxy reaches Remark42 over IPv6 (dual-stack / IPv6-enabled Docker), add the IPv6 network too, or every visitor collapses onto the proxy's IP and gets over-throttled.
• Don't publish Remark42's own port when trusting a Docker range. If Remark42's port is exposed to the host, external traffic is SNAT'd to the Docker gateway (inside 172.16.0.0/12) and appears trusted — re-opening the bypass. Publish only the proxy.
• 0.0.0.0/0 trusts everyone and re-opens the bypass; too narrow a range over-throttles real visitors. If unsure which network your proxy uses, check a Remark42 request log for the peer address it reports.

Deprecated parameters

The following list of command-line options is deprecated and might be removed in the next major release after the version they were deprecated. After the Remark42 version update, please check the startup log once for deprecation warning messages to avoid trouble with unrecognized command-line options in the future.

Admin users

Admins/moderators should be defined in docker-compose.yml as a list of user IDs or passed in the command line.

environment:
  - ADMIN_SHARED_ID=github_ef0f706a79cc24b17bbbb374cd234a691a034128,github_dae9983158e9e5e127ef2b87a411ef13c891e9e5

To get a user ID just log in and click on your username or any other user you want to promote to admins. It will expand login info and show the full user ID.

Docker image

Two parameters allow customizing the Docker container on the system level:

• APP_UID - sets UID to run Remark42 application in container (default=1001)
• TIME_ZONE - sets time zone of Remark42 container, would be used only on the backend as comments shown with user's timezone in the web interface (default=America/Chicago)

See umputun/baseimage for more details.