Set Up Push Gateway

The push gateway enables mobile push notifications for Android and iOS users connected to your node. Without it, mobile users will only receive messages when the app is open.

Option A: Docker (Recommended)

# Pull the push gateway image
docker pull ogmara/ogmara:push-gateway-latest

# Run the push gateway.
# This mounts the config file (created in the "Configuration" section below)
# and loads the secrets from the env file (created in the "Secrets via an
# Environment File" section below) — set both up first, then run this.
docker run -d \
  --name ogmara-push \
  --restart unless-stopped \
  -p 127.0.0.1:41722:41722/tcp \
  -v /etc/ogmara/push-gateway.toml:/etc/ogmara/push-gateway.toml:ro \
  --env-file /etc/ogmara/push-gateway.env \
  ogmara/ogmara:push-gateway-latest

Option B: Build from Source

# Clone and build
git clone https://github.com/Ogmara/push-gateway.git
cd push-gateway
cargo build --release

# Install the binary (the built binary is named ogmara-push-gateway)
sudo cp target/release/ogmara-push-gateway /usr/local/bin/
sudo chmod +x /usr/local/bin/ogmara-push-gateway

Generate VAPID Keys (Web Push only)

VAPID keys are needed only if you enable browser Web Push ([webpush] enabled = true). Skip this if you serve only mobile (FCM/APNs) or no push. There is no built-in generator subcommand; use the standard web-push tool, which emits keys in the base64url format the gateway expects:

# Generate a VAPID key pair (base64url)
npx web-push generate-vapid-keys

# Put the printed PRIVATE key into [webpush] vapid_private_key.
# The PUBLIC key is derived by the gateway automatically and served at
# GET /vapid-key (clients fetch it from there) — you do not configure it.

Configuration

# /etc/ogmara/push-gateway.toml
# (generate this file with: ogmara-push-gateway init -o /etc/ogmara/push-gateway.toml)

[gateway]
listen_port = 41722
listen_addr = "127.0.0.1"
# Shared secret with the L2 node. Prefer the OGMARA_PUSH_SECRET env var
# (see below) over hard-coding it here. Must equal the node's
# [push_gateway] auth_token.
push_secret = ""
# Canonical PUBLIC URL of THIS gateway. Device-registration requests are
# cryptographically bound to it, so it MUST match the URL clients use.
# REQUIRED: if empty, /register and /unregister reject every request (503).
# Prefer the OGMARA_GATEWAY_URL env var.
public_url = "https://push.yourdomain.com"
# Per-IP rate limit for /register + /unregister.
rate_limit_per_sec = 20
# Device registry file. Push tokens are encrypted at rest when
# OGMARA_REGISTRY_KEY (see below) is set.
registry_file = "/var/lib/ogmara/registry.json"

# Web Push is OPTIONAL (Android/iOS use [fcm]/[apns], default off).
[webpush]
enabled = false
vapid_private_key = "YOUR_VAPID_PRIVATE_KEY"
vapid_subject = "mailto:admin@yourdomain.com"
# The VAPID PUBLIC key is DERIVED automatically and served at GET /vapid-key —
# you do not set it here.

Secrets via an Environment File

Secrets are kept out of the config file in a small environment file. Three values go here:

• OGMARA_PUSH_SECRET — the shared secret with the L2 node (must equal the node's auth_token).
• OGMARA_GATEWAY_URL — this gateway's public URL. Required — without it, registration returns 503.
• OGMARA_REGISTRY_KEY — a 32-byte key that encrypts stored push tokens. Strongly recommended; without it, tokens are stored in plaintext.

Step 1 — generate the two random secrets. Run this twice and copy each line of output (you'll paste them in the next step):

openssl rand -hex 32

Step 2 — create the environment file at /etc/ogmara/push-gateway.env. Open it in an editor (sudo nano /etc/ogmara/push-gateway.env) and paste the following, replacing the three placeholder values. Note there are no quotes and no spaces around the = — this file is read literally, not by a shell, so do not put commands like $(openssl …) here:

# /etc/ogmara/push-gateway.env
OGMARA_PUSH_SECRET=paste-the-first-openssl-output-here
OGMARA_GATEWAY_URL=https://push.yourdomain.com
OGMARA_REGISTRY_KEY=paste-the-second-openssl-output-here

The OGMARA_PUSH_SECRET value must be identical to the auth_token you set in the L2 node config (next section).

Step 3 — lock down the file so only the gateway user can read it:

sudo chown ogmara:ogmara /etc/ogmara/push-gateway.env
sudo chmod 600 /etc/ogmara/push-gateway.env

The systemd service below loads this file automatically (EnvironmentFile=). Docker users: pass it with --env-file /etc/ogmara/push-gateway.env on docker run (the run command in Option A already includes it).

Connect L2 Node to Push Gateway

Edit the [push_gateway] block in your L2 node configuration (the auto-generated default ships with enabled = false and empty values).

# In /etc/ogmara/ogmara.toml

[push_gateway]
enabled = true
url = "http://127.0.0.1:41722"
# Must equal the gateway's OGMARA_PUSH_SECRET. The node reads this from the
# config file (there is no env-var override for it on the node side), so keep
# ogmara.toml readable only by the ogmara user.
auth_token = "YOUR_SHARED_SECRET"

Systemd Service (for Source Build)

# /etc/systemd/system/ogmara-push-gateway.service
[Unit]
Description=Ogmara Push Notification Gateway
After=network-online.target ogmara-node.service
Wants=network-online.target

[Service]
Type=simple
User=ogmara
Group=ogmara
WorkingDirectory=/var/lib/ogmara/push-gateway
# Secrets via an environment file (chmod 600, owned by ogmara) holding
# OGMARA_PUSH_SECRET / OGMARA_GATEWAY_URL / OGMARA_REGISTRY_KEY (see above).
EnvironmentFile=/etc/ogmara/push-gateway.env
# IMPORTANT: exactly ONE ExecStart line (systemd rejects multiple for
# Type=simple). The global --config goes BEFORE the `run` subcommand.
ExecStart=/usr/local/bin/ogmara-push-gateway --config /etc/ogmara/push-gateway.toml run
Restart=on-failure
RestartSec=5
# Hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/ogmara/push-gateway
PrivateTmp=true
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

# Enable and start — run daemon-reload after ANY edit to the unit file above
sudo systemctl daemon-reload
sudo systemctl enable ogmara-push-gateway
sudo systemctl start ogmara-push-gateway

# Restart the L2 node to connect to the push gateway
sudo systemctl restart ogmara-node