Merge pull request #998 from feldroy/add-railway-deployment-docs

pydanny · web-flow · commit e12f5eae310b · 2026-01-14T12:58:37.000+08:00
Add Railway deployment docs
diff --git a/docs/deployment/index.md b/docs/deployment/index.md
@@ -0,0 +1,29 @@
+# Deployment
+
+Air applications can be deployed in several ways. We provide detailed examples for containerization and Kubernetes deployment, and have successfully deployed Air apps on various hosting platforms.
+
+## Examples
+
+* [Containerizing an Air application](https://github.com/feldroy/air/tree/main/examples/containerize)
+* [Deploying an Air application to Kubernetes](https://github.com/feldroy/air/tree/main/examples/deployment/k8s)
+
+## Hosting Platforms
+
+We have experience deploying Air on the following hosting platforms. If you're using these services, please consider using our referral links - they help sustain the Air project! 💚
+
+### Railway
+
+* [Our Railway referral link to get $20 in Railway credit](https://railway.com?referralCode=5EX8pI)
+* [Example Railway config for Air](railway.md)
+
+### Vultr
+
+* [Our Vultr link to get $300 of Vultr credit](https://www.vultr.com/?ref=9686150)
+
+### FastAPI Cloud
+
+* Not open to the public yet, but you can join the [FastAPI Cloud waitlist](https://fastapicloud.com/)
+
+## Contributing
+
+Have you deployed Air on other platforms? We'd love to hear about your experience! Consider contributing deployment guides or examples back to the [Air repository](https://github.com/feldroy/air) to help the community.
diff --git a/docs/deployment/railway.md b/docs/deployment/railway.md
@@ -0,0 +1,42 @@
+# Deploying Air on Railway
+
+Railway is a platform for deploying web applications with automatic scaling, built-in databases, and zero-config deployments. This guide shows how to deploy an Air application to Railway using Nixpacks for builds and Hypercorn for serving.
+
+## Prerequisites
+
+- An Air project with a `main.py` file containing your app.
+- A Railway account and project connected to your Git repository.
+- (Optional) Railway's PostgreSQL plugin if your app uses a database.
+
+Railway automatically detects Python projects and uses Nixpacks to build them. It provides a `$PORT` environment variable for binding your server.
+
+## Add hypercorn to the dependency list
+
+We use Hypercorn instead of Uvicorn here because one of the prerequisites for deploying Starlette apps to Railway is Hypercorn as a dependency in the pyproject.toml. When using `uv`, add it to your base packages in `pyproject.toml` thus:
+
+```sh
+uv add hypercorn
+```
+
+If using `pip` or `uv pip`, you'll need to add hypercorn to whatever file stores your dependency list (often this is `requirements.txt`).
+
+## Basic Configuration
+
+Create a `railway.json` file in your project root:
+
+```json
+{
+  "$schema": "https://railway.app/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "uv run hypercorn main:app --bind \"[::]:$PORT\""
+  }
+}
+```
+
+Tips:
+
+- Commit your uv.lock file to the repo. Don't .gitignore or .railwayignore it.
+- Use hypercorn because Railway insists on using it instead of uvicorn.
diff --git a/mkdocs.yaml b/mkdocs.yaml
@@ -68,6 +68,8 @@ nav:
       - sprint/index.md
       - Source Examples: sprint/src_examples.md
 
+  - Deployment: deployment/index.md
+
 theme:
   name: material
   features:
