Deploy and Host PBI Gateway on Railway

PBI Gateway is a secure, serverless API bridge that lets Power BI Desktop and Service query your SQL Server database over HTTPS — without installing Microsoft's Windows-based On-Premises Data Gateway. It ships with its own login, JWT validation (Entra ID), rate limiting, the Statdeck Geo Power BI visual, a Theme PBI studio and an SVG → PBI converter.

> 🌐 Need MySQL, MongoDB, Oracle, PostgreSQL, Excel or SharePoint? Sign up at statdeck.lat to access more enterprise connectors managed by Statdeck.

About Hosting PBI Gateway

This template deploys a Node.js 20 service from a multi-stage Dockerfile. Railway builds the image, exposes it on a public HTTPS domain, runs a /api/gateway/health healthcheck and restarts on failure. You configure the gateway through environment variables: SQL Server credentials (host and port separated), a session-signing GATEWAY_RECOVERY_KEY, dashboard login (GATEWAY_USER / GATEWAY_PASSWORD), a public Mapbox token (for the Statdeck Geo visual) and an optional DATABASE_URL for PostgreSQL profile storage. Add a Railway PostgreSQL plugin to the project and the variable is injected automatically. The container drops to an unprivileged user, supports gzip compression, structured logging via Pino and streams large result sets without exhausting memory.

Common Use Cases

• Replace Microsoft's Windows On-Premises Data Gateway with a cloud-native HTTPS proxy that Power BI Service can refresh on schedule.
• Connect Power BI Desktop to SQL Server databases hosted on Railway, Azure, AWS RDS or on-prem (with a public endpoint) — no VPN, no domain join.
• Ship branded Power BI deliverables: custom theme generator, SVG-to-icon converter and the Statdeck Geo map visual (Mapbox, multi-profile) bundled in one place.

Dependencies for PBI Gateway Hosting

• SQL Server reachable from Railway — for example the Railway SQL Server template, Azure SQL Database, or any host with a public TCP endpoint. The configured SQLSERVER_USER should hold read-only permissions only.
• Mapbox public token — only required if you use the bundled Statdeck Geo visual.
• PostgreSQL (optional) — adds the Railway PostgreSQL plugin so the Statdeck Geo visual can persist user profiles. Railway injects DATABASE_URL automatically.

Deployment Dependencies

• Microsoft Entra ID (Azure AD) app registration — for Bearer-token authentication from Power BI.
• Mapbox access tokens — public token for the Statdeck Geo visual.
• Power BI Web connector docs — used by Power BI to consume this gateway.
• Railway PostgreSQL plugin — optional storage for the Statdeck Geo visual.
• Statdeck — more enterprise connectors — MySQL, MongoDB, Oracle, PostgreSQL, Excel, SharePoint and more.

Implementation Details

Configure the required environment variables in Railway → Variables:

# 🔒 Dashboard login + Power BI Basic Auth
GATEWAY_USER=admin
GATEWAY_PASSWORD=
GATEWAY_RECOVERY_KEY=<32+ random bytes — openssl rand -base64 48>

# 🗄️ SQL Server — host and port MUST be separated
SQLSERVER_HOST=metieto.proxy.rlwy.net
SQLSERVER_PORT=38350
SQLSERVER_USER=
SQLSERVER_PASSWORD=
SQLSERVER_ENCRYPT=true
SQLSERVER_TRUST_CERT=true

# 🗺️ Mapbox (Statdeck Geo visual)
MAPBOX_TOKEN=pk.eyJ...

# 🐘 PostgreSQL (auto-injected by the Railway plugin)
DATABASE_URL=postgres://...

Once deployed, open the public URL → sign in with GATEWAY_USER / GATEWAY_PASSWORD → use the Conexión tab to discover databases and generate Power BI Web URLs. Paste those URLs into Power BI Desktop → Get Data → Web → Basic and authenticate with the same gateway credentials. Power BI Service uses identical credentials for scheduled refresh — no On-Premises Data Gateway required.

> ⚠️ The /api/gateway/query endpoint executes raw SQL from authenticated clients. The SQLSERVER_USER must be limited to db_datareader (or equivalent read-only role). See SECURITY_HARDENING.md for the full hardening checklist.

Why Deploy PBI Gateway on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying PBI Gateway on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.