
Deploy Scalar API Reference
Scalar 0.6.29: interactive OpenAPI and AsyncAPI docs with a built-in client
Scalar API Reference
Just deployed
/docs
Deploy and Host Scalar API Reference on Railway
Scalar API Reference turns OpenAPI (Swagger) and AsyncAPI documents into interactive API documentation with a built-in API client. Readers can browse endpoints and schemas, see request examples in many languages, and send test requests from the browser. Scalar is open source under the MIT licence.
About Hosting Scalar API Reference
Scalar's official Docker image is a small Caddy web server that serves the Scalar bundle. It has no database and no login. You point it at your API documents in one of two ways: a URL in the API_REFERENCE_CONFIG variable, or files in its /docs folder. This template builds that image (version 0.6.29, pinned by digest) from a public GitHub repo. Caddy listens on Railway's PORT, /health is the health check, and /docs is a Railway volume, so the documents you add there survive redeploys and restarts. The first deploy shows Scalar's demo API, with nothing to fill in.
Common Use Cases
- Public API documentation for a product or developer platform, on your own domain
- An internal reference for the services a team runs, generated from their OpenAPI files
- A browser-based API client for trying requests against a staging or local API
Dependencies for Scalar API Reference Hosting
- None beyond the one service: Scalar needs no database, cache or queue
- Your OpenAPI, Swagger or AsyncAPI documents (a URL or files on the volume)
Deployment Dependencies
- Scalar Docker image docs: https://scalar.com/products/api-references/integrations/docker
- Scalar configuration reference: https://scalar.com/products/api-references/configuration
- Scalar source and releases: https://github.com/scalar/scalar
- Template repo (Dockerfile, start script, changelog): https://github.com/aalfath/scalar-api-reference-railway-template
Implementation Details
The template deploys one service, Scalar API Reference (public), with a volume on /docs.
After deploy, show your own API in one of two ways:
- From a URL. In the service's Variables tab, change
API_REFERENCE_CONFIG, for example to{"sources":[{"url":"https://YOUR-API/openapi.json"}],"theme":"purple"}, then redeploy. You can list several sources, and any other Scalar setting (theme, layout,proxyUrl, hidden models) goes in the same JSON. - From files. Copy
.json,.yamlor.ymldocuments into/docs(sub-folders are fine), for example overrailway ssh(the repo README has a one-line command), then restart the service. Each document becomes a selectable API and is served under/openapi/, at the same path it has in/docs. When/docsholds documents, they replace the sources inAPI_REFERENCE_CONFIG; the other settings still apply.
The reference is public to anyone with the URL, so don't load documents you want to keep private. The API client sends requests from the reader's browser, so your API must allow CORS, or set proxyUrl (Scalar's hosted proxy is https://proxy.scalar.com).
Updates. The service builds from the template's GitHub repo. When we move it to a newer Scalar image there, Railway shows an "update available" notice in your project and you choose when to apply it. Read CHANGELOG.md in the repo first.
Why Deploy Scalar API Reference 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 Scalar API Reference 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.
Template Content
Scalar API Reference
aalfath/scalar-api-reference-railway-template