---
title: "Deploy Evidence"
description: "Build data reports by writing SQL and Markdown files"
category: "Analytics"
url: https://railway.com/deploy/evidence
---

# Deploy Evidence

Build data reports by writing SQL and Markdown files

**[Deploy Evidence on Railway](https://railway.com/template/evidence)**

- **Creator:** A3A
- **Category:** Analytics

## Template content

### evidence https://raw.githubusercontent.com/evidence-dev/media-kit/main/svg/logo-square-white-on-transparent.svg

- **Source:** https://github.com/gridalpha/evidence-railway
- **Public domain:** Yes

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

![Evidence logo](https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcSXSP4S7SIs2csyAsNO5M9adiqxq0WqLQIcTPvC5O5AgMBK0LNEVA4JoQY&s=10)

# 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](https://github.com/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.

![Evidence and Postgres services connected on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787801960/evidence-architecture.png)

## 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`.

![Evidence revenue report with KPI tiles and monthly trend](https://res.cloudinary.com/rroe4rtk/image/upload/v1787801962/evidence-revenue-overview.png)
![Product revenue table and units sold bar chart](https://res.cloudinary.com/rroe4rtk/image/upload/v1787801963/evidence-product-performance.png)
![Sales channel report filtered to the Europe region](https://res.cloudinary.com/rroe4rtk/image/upload/v1787801964/evidence-channels-filtered.png)

## 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](https://github.com/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

| Variable | Required | Description |
|---|---|---|
| `EVIDENCE_BASIC_USER` | yes | Site HTTP basic auth username |
| `EVIDENCE_BASIC_PASSWORD` | yes | Site HTTP basic auth password |
| `EVIDENCE_DB_PASSWORD` | yes | Password for the read-only warehouse role |
| `EVIDENCE_DB_HOST` | no | Warehouse host; defaults to the Postgres service |
| `EVIDENCE_DB_NAME` | no | Warehouse database name |
| `EVIDENCE_DB_USER` | no | Role Evidence connects as (`evidence_reader`) |
| `EVIDENCE_DB_SSLMODE` | no | `disable`, `require`, `verify-ca` or `verify-full` |
| `EVIDENCE_BOOTSTRAP` | no | Set `0` when using your own warehouse |
| `EVIDENCE_AUTH_DISABLED` | no | `true` removes all auth — private networks only |

### 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

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 0.5 vCPU | 1–2 vCPU |
| RAM | 512 MB | 1–2 GB |
| Storage | none (stateless) | none; size Postgres to your data |
| Runtime | Docker | Docker |

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

| | Evidence | Metabase | Apache Superset |
|---|---|---|---|
| Authoring | Markdown + SQL in Git | Point-and-click UI | UI with SQL Lab |
| Version control | Native — reports are files | Serialisation export | Limited |
| Self-hosted auth | HTTP basic auth | Full user accounts | Full user accounts |
| Best for | Curated, reviewed reports | Ad-hoc exploration | Large BI deployments |

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.



## Similar templates

- [Betterlytics](https://railway.com/deploy/betterlytics) — Betterlytics is a cookieless analytics platform GDPR-compliant.
- [Finance Tracker](https://railway.com/deploy/finance-tracker-1) — Private multi-user household finance ledger with budgets and CSV import.
- [Matomo Analytics + MariaDB](https://railway.com/deploy/matomo-analytics-mariadb) — Privacy-friendly analytics with MariaDB and persistent volumes.

Open this page in a browser: https://railway.com/deploy/evidence