Deploy Evidence

Deploy and Host Evidence on Railway

Evidence is an open-source business intelligence tool that treats reports as code. Instead of dragging fields around a canvas you write a Markdown file, drop SQL queries into it and add chart components inline, then version it in Git and review changes in a pull request. Data teams use it to publish repeatable reports without per-seat BI licences, and a dashboard stays a text file you can diff and reuse. Evidence queries your warehouse at request time, so there is no second copy of the numbers to sync.

This template lets you self-host Evidence on Railway with a warehouse already attached. It runs two services: an Evidence web service built from gridalpha/evidence-railway on the official evidencedev/serve image, and a managed Postgres database used as the warehouse. Browser traffic reaches Evidence over its public Railway domain behind HTTP basic auth; Evidence queries Postgres over the private network as a SELECT-only role it provisions on first boot. A sample retail dataset is seeded automatically, so the reports render real charts as soon as the deploy turns green.

Getting Started with Evidence on Railway

Set EVIDENCE_BASIC_USER and EVIDENCE_BASIC_PASSWORD when you deploy — they guard the whole site, and Evidence refuses to serve beyond localhost without them. Open the generated Railway URL and your browser shows a native sign-in prompt. There is no account system or sign-up screen: everyone with the credentials sees the same reports.

You land on Revenue Overview, which reads the seeded demo schema and renders four KPI tiles, a monthly revenue line, category and region breakdowns and a best-sellers table. The sidebar leads to Sales Channels and Products. On Sales Channels, pick a Region: every chart and table re-queries Postgres and narrows to it, the quickest way to confirm the warehouse connection is live rather than cached.

To make it yours, fork the source repository and edit project/pages/*.md. Each page is Markdown with fenced SQL blocks naming a query plus components such as {% line_chart %} or {% big_value %} that reference it; push and Railway rebuilds the site. For your own warehouse, edit project/connection.yaml — Postgres, Snowflake, BigQuery, ClickHouse, Databricks, Fabric, Cube and MotherDuck are supported — and set EVIDENCE_BOOTSTRAP=0.

About Hosting Evidence

Evidence turns a directory of Markdown files into a fast, interactive report site. Queries run against your warehouse when a page is requested, so numbers are never stale and no extract job needs scheduling. Self-hosting suits teams whose data must stay in their own infrastructure, and anyone wanting versioned reports without a per-user BI bill.

• Reports authored in Markdown with embedded SQL and chart components
• Live queries against your own warehouse — no data copy, no sync job
• Charts, tables, big-value tiles, dropdowns and cross-filtering built in
• Everything in Git: branch it, review it, roll it back
• HTTP basic auth for self-hosted deployments

The Evidence service is stateless — reports live in the image, data in Postgres — so it needs no volume and is safe to scale past one replica. Postgres holds the seeded demo tables and anything else you load.

Why Deploy Evidence on Railway

Railway removes the infrastructure work around a self-hosted report site:

• Postgres provisioned and privately networked in one click
• Automatic HTTPS on a generated domain, or bring your own
• Push to Git and the site rebuilds itself
• Private networking keeps the warehouse off the internet
• Health checks and restarts handled for you
• Usage-based pricing, no per-seat licence

Common Use Cases

• Internal KPI reporting — revenue, retention and funnel dashboards reviewed like any code change
• Customer-facing reports — a branded metrics site backed by your production database
• Analytics engineering handoff — dbt models published as narrative reports, not ad-hoc charts
• Data quality monitoring — freshness, row counts and reconciliation checks anyone can open

Dependencies for Evidence

• Evidence — built from gridalpha/evidence-railway on evidencedev/serve:latest, upstream's hardened evidence serve runtime. Serves the reports and runs every query.
• Postgres — Railway's managed postgres:18, holding the warehouse tables and reachable only on the private network.

Environment Variables Reference

Deployment Dependencies

• Source repo: https://github.com/gridalpha/evidence-railway
• Upstream: https://github.com/evidence-dev/evidence (MIT)
• Docker image: https://hub.docker.com/r/evidencedev/serve
• Self-host docs: https://docs.evidence.dev/self-host

Hardware Requirements for Self-Hosting Evidence

Evidence renders pages on demand, so its footprint stays small. Query cost lands on the warehouse: size Postgres for the tables you load.

Self-Hosting Evidence with Docker

Upstream publishes evidencedev/serve so self-hosting is a two-line Dockerfile pointed at a project directory holding a connection.yaml and your pages:

FROM evidencedev/serve:latest
COPY --chown=evidence:evidence . /project

To try it against a warehouse you already have, this runs the published image and mounts your project read-only:

docker run --rm -p 3000:3000 \
  -e EVIDENCE_BASIC_USER=analyst \
  -e EVIDENCE_BASIC_PASSWORD=change-me \
  -v "$PWD":/project:ro \
  evidencedev/serve:latest

Self-hosted Evidence requires a direct connector configured in connection.yaml at the project root. Move every secret into a ${VAR} reference so the file is safe to commit, and give Evidence a SELECT-only role rather than the database owner — this template creates one.

How Much Does Evidence Cost to Self-Host?

Evidence is open source under the MIT licence, so the software is free with no per-seat charges. Self-hosting on Railway costs only the compute and storage the two services use — a few dollars a month for a small report site on a modest Postgres database. The commercial Evidence Studio platform, which adds SSO, row-level security, a hosted warehouse and AI agents, starts at $2,500/month; none of it is needed to self-host.

Evidence vs Metabase and Superset

Choose Evidence when reports should be reviewed like code; choose Metabase or Superset when non-technical users build their own charts.

FAQ

What is Evidence? Evidence is an open-source business intelligence tool where reports are Markdown files containing SQL queries and chart components, rendered into an interactive site that queries your warehouse live.

What does this Railway template deploy? Two services: an Evidence web service built from a public GitHub repository on the official evidencedev/serve image, and a managed Postgres warehouse. A sample retail dataset and a read-only database role are created on first boot.

Why does the template include a Postgres database? Evidence stores no data of its own — it queries a warehouse. Postgres gives the template something real to query so the reports work immediately, and is where you load your own tables.

How do I secure a self-hosted Evidence deployment? It uses shared HTTP basic auth via EVIDENCE_BASIC_USER and EVIDENCE_BASIC_PASSWORD, and refuses to start without them on a public interface. For SSO, front it with an authenticating proxy such as oauth2-proxy or Cloudflare Access.

Does self-hosted Evidence support per-user permissions or row-level security? No. Every viewer sees the same reports, queried under the single warehouse identity in connection.yaml. Per-viewer access rules and row-level security are Evidence Studio features.