Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/wikioasis/salt/llms.txt

Use this file to discover all available pages before exploring further.

The sentry_relay Salt state deploys Sentry Relay — Sentry’s open-source event ingestion proxy — on mw* and staging* servers. Running Relay locally means that MediaWiki’s Sentry SDK can send error events to localhost:3030 instead of making outbound HTTPS calls to sentry.io on every request. Relay batches, filters, and forwards events to the upstream Sentry SaaS endpoint, reducing latency and providing a resilient local buffer.

​
State overview

1

System user

Creates a system user sentry-relay with no home directory and a nologin shell. All Relay processes and files run as this user.
2

Directories

Creates /etc/sentry-relay (config) and /var/lib/sentry-relay (working directory), both owned by sentry-relay:sentry-relay with mode 0750.
3

Binary download

Downloads the pre-built relay-Linux-x86_64 binary from the GitHub release for version 24.9.0 to /usr/local/bin/sentry-relay. The SHA-256 hash is verified before the file is placed, so no corrupted or tampered binary can be installed.
4

Configuration file

Renders /etc/sentry-relay/config.yml from the Jinja template using pillar values. Owned by sentry-relay:sentry-relay, mode 0640.
5

Systemd service unit

Writes /etc/systemd/system/sentry-relay.service inline (no template — all runtime parameters are fixed). The service runs as sentry-relay, uses /var/lib/sentry-relay as its working directory, and restarts on failure.
6

Service management

Ensures sentry-relay is running and enabled at boot, restarting whenever config.yml changes.

​
Full state

# salt/sentry_relay/init.sls
sentry_relay_user:
  user.present:
    - name: sentry-relay
    - system: True
    - shell: /usr/sbin/nologin
    - home: /var/lib/sentry-relay
    - createhome: False

/etc/sentry-relay:
  file.directory:
    - user: sentry-relay
    - group: sentry-relay
    - mode: '0750'
    - require:
      - user: sentry_relay_user

/var/lib/sentry-relay:
  file.directory:
    - user: sentry-relay
    - group: sentry-relay
    - mode: '0750'
    - require:
      - user: sentry_relay_user

sentry_relay_binary:
  file.managed:
    - name: /usr/local/bin/sentry-relay
    - source: https://github.com/getsentry/relay/releases/download/24.9.0/relay-Linux-x86_64
    - source_hash: sha256=6b098fba024cc119f200f1fd7c6c602204e6159b7d72501f8a5c975f8f263683
    - mode: '0755'
    - user: root
    - group: root

/etc/sentry-relay/config.yml:
  file.managed:
    - source: salt://sentry_relay/files/config.yml.jinja
    - template: jinja
    - user: sentry-relay
    - group: sentry-relay
    - mode: '0640'
    - require:
      - file: /etc/sentry-relay

/etc/systemd/system/sentry-relay.service:
  file.managed:
    - contents: |
        [Unit]
        Description=Sentry Relay
        After=network.target

        [Service]
        User=sentry-relay
        WorkingDirectory=/var/lib/sentry-relay
        ExecStart=/usr/local/bin/sentry-relay run --config /etc/sentry-relay
        Restart=on-failure

        [Install]
        WantedBy=multi-user.target
    - user: root
    - group: root
    - mode: '0644'

sentry-relay:
  service.running:
    - enable: True
    - watch:
      - file: /etc/sentry-relay/config.yml
    - require:
      - user: sentry_relay_user
      - file: sentry_relay_binary
      - file: /etc/sentry-relay/config.yml
      - file: /var/lib/sentry-relay
      - file: /etc/systemd/system/sentry-relay.service

​
Configuration template

The config.yml.jinja template produces a minimal Relay configuration. Relay is set to proxy mode, which means it forwards all envelopes to the upstream Sentry endpoint without any local project key validation or PII scrubbing — the full Sentry pipeline runs in the cloud. 
# salt/sentry_relay/files/config.yml.jinja
relay:
  upstream: "https://sentry.io/"
  host: "0.0.0.0"
  port: 3030
  mode: proxy

sentry:
  enabled: true
  dsn: "{{ pillar['sentry_relay']['dsn'] }}"

​
Rendered output example

relay:
  upstream: "https://sentry.io/"
  host: "0.0.0.0"
  port: 3030
  mode: proxy

sentry:
  enabled: true
  dsn: "https://<key>@sentry.io/<project>"

​
Pillar reference

KeyRequiredDescription
sentry_relay.dsn✅Sentry DSN for Relay’s own internal error reporting to sentry.io
# Example pillar entry (store in an encrypted pillar or Vault)
sentry_relay:
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0"
The sentry_relay.dsn is a secret credential. Store it in an encrypted Salt pillar (using gpg renderer) or a secrets backend such as HashiCorp Vault. Never commit a plaintext DSN to the pillar repository.

​
Systemd service unit

The service unit is written inline in the state (no separate file template) because all parameters are static: 
[Unit]
Description=Sentry Relay
After=network.target

[Service]
User=sentry-relay
WorkingDirectory=/var/lib/sentry-relay
ExecStart=/usr/local/bin/sentry-relay run --config /etc/sentry-relay
Restart=on-failure

[Install]
WantedBy=multi-user.target
Relay listens on 0.0.0.0:3030. MediaWiki’s Sentry SDK should be configured to use http://localhost:3030 as its DSN host so that all error envelopes go through the local relay instead of directly to sentry.io.

​
Installed file summary

PathOwnerModeDescription
/usr/local/bin/sentry-relayroot:root0755Pre-built Relay binary (v24.9.0)
/etc/sentry-relay/sentry-relay:sentry-relay0750Configuration directory
/etc/sentry-relay/config.ymlsentry-relay:sentry-relay0640Rendered Relay configuration
/var/lib/sentry-relay/sentry-relay:sentry-relay0750Working directory (envelope queue, credentials cache)
/etc/systemd/system/sentry-relay.serviceroot:root0644Systemd unit file

​
Applying the state

# Apply to all mw* and staging* minions
salt 'mw* or staging*' state.apply sentry_relay

# Apply to a single MediaWiki host
salt 'mw-us-east-011*' state.apply sentry_relay

# Dry-run first
salt 'mw*' state.apply sentry_relay test=True

# Check service status after applying
salt 'mw*' cmd.run 'systemctl status sentry-relay --no-pager'

# Verify Relay is accepting envelopes
salt 'mw-us-east-011*' cmd.run 'curl -s http://localhost:3030/api/relay/healthcheck/'
After applying, send a test event from one of the mw* hosts and confirm it appears in the Sentry project dashboard. Use journalctl -u sentry-relay -f on the minion to watch Relay’s forwarding logs in real time.

Build docs developers (and LLMs) love

Get started for freeTalk to us