Deploy and Host Apache Pinot on Railway

Built for an LLM agent to deploy and use. There is no setup step and nothing to fill in: authentication is on from the first request with a generated 32-character password, and the whole cluster (ZooKeeper, controller, broker, server) runs in one service. The contract below lists every URL, variable name and the one script that proves it works.

Apache Pinot is a real-time distributed OLAP datastore: columnar storage, star-tree and inverted indexes, and SQL queries that answer in milliseconds over billions of rows, fed from batch files or Kafka streams. This template runs a single-node Pinot 1.6.0 cluster with basic authentication on the controller and the broker.

About Hosting Apache Pinot

Upstream documents Pinot as a ZooKeeper plus separate controller, broker and server containers. This template runs all four in one service, the official apachepinot/pinot image pinned by digest, with their data on one volume at /var/pinot. A boot script sizes each JVM heap from the container's memory limit (the image default is 4 GB per JVM, which does not fit), gives every role the fixed host name pinot-node so segment assignments survive a redeploy (Pinot pins data to instance ids built from the host name, and Railway gives a new container a new host name), and supervises the four processes: if one dies the container exits and Railway restarts it. The first boot takes a few minutes; after a redeploy the data is queryable again about a minute and a half after the controller reports healthy.

The controller (REST API, Swagger UI, query console, /sql query proxy) is the one public service on port 8080. The broker listens on 8099 and is reachable from other services in the same project.

Agent contract

Public URL: https:// plus RAILWAY_PUBLIC_DOMAIN, given as PINOT_PUBLIC_URL. It serves the controller REST API, the Swagger UI at /help and the query console at /.
Private URL: http://pinot.railway.internal:8080 for the controller and http://pinot.railway.internal:8099 for the broker (variable PINOT_PRIVATE_BROKER_URL), for services in the same project.
Credentials: user admin, password in ADMIN_PASSWORD.
Auth: HTTP basic auth on every controller and broker request (curl -u admin:PASSWORD). Anonymous calls answer 401.
Health: GET /health on the controller returns OK with no credentials.

# run with PINOT_PUBLIC_URL and ADMIN_PASSWORD set; needs curl
U="admin:$ADMIN_PASSWORD"; J='Content-Type: application/json'
T="agent_$(cat /proc/sys/kernel/random/uuid | tr -d - | cut -c1-8)"
curl -s -w ' health %{http_code}\n' "$PINOT_PUBLIC_URL/health"
curl -s -o /dev/null -w 'anonymous %{http_code}\n' "$PINOT_PUBLIC_URL/tables"
curl -fsS -u "$U" -H "$J" -X POST "$PINOT_PUBLIC_URL/schemas" -d "{\"schemaName\":\"$T\",\"dimensionFieldSpecs\":[{\"name\":\"item\",\"dataType\":\"STRING\"}],\"metricFieldSpecs\":[{\"name\":\"qty\",\"dataType\":\"LONG\"}]}" >/dev/null
curl -fsS -u "$U" -H "$J" -X POST "$PINOT_PUBLIC_URL/tables" -d "{\"tableName\":\"$T\",\"tableType\":\"OFFLINE\",\"segmentsConfig\":{\"replication\":\"1\"},\"tenants\":{},\"tableIndexConfig\":{\"loadMode\":\"MMAP\"},\"metadata\":{}}" >/dev/null
printf 'item,qty\nbook,2\npen,5\n' > /tmp/$T.csv
curl -fsS -u "$U" -X POST -F "file=@/tmp/$T.csv" "$PINOT_PUBLIC_URL/ingestFromFile?tableNameWithType=${T}_OFFLINE&batchConfigMapStr=%7B%22inputFormat%22%3A%22csv%22%7D" >/dev/null
for i in 1 2 3 4 5 6 7 8 9 10; do
  curl -fsS -u "$U" -H "$J" -X POST "$PINOT_PUBLIC_URL/sql" -d "{\"sql\":\"select sum(qty) as total from $T\"}" | grep -o '"rows":\[\[7\.0\]\]' && break; sleep 3
done

A fresh deploy prints OK health 200, anonymous 401 and "rows":[[7.0]]. Services in the same project query the broker directly with curl -u admin:PASSWORD -H 'Content-Type: application/json' -X POST http://pinot.railway.internal:8099/query/sql -d '{"sql":"select count(*) from mytable"}'.

Why Deploy Apache Pinot 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 Apache Pinot 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.

Agent-ready - generated password, contract block and one working script; no wizard, no open cluster.
One service, not four - ZooKeeper, controller, broker and server run together on one volume instead of four services you wire by hand.
Closed by default - the stock Pinot controller and broker answer any caller, including table drops; here every call needs the generated password.
State survives redeploys - schemas, tables and segments stay assigned across redeploys because the cluster identity does not depend on the container host name.
Sized for the container - JVM heaps come from the memory limit, not the host.

Common Use Cases

User-facing analytics - low-latency dashboards and metrics APIs over event data.
Real-time OLAP for AI agents - give an agent a SQL endpoint over large event tables without a warehouse.
Stream analytics - ingest from Kafka-compatible brokers in the same project and query within seconds.

Dependencies for Apache Pinot Hosting

None. ZooKeeper runs inside the service; all state is on the volume at /var/pinot.

Deployment Dependencies

apache/pinot - upstream project