Skip to content

Commit bdbf262

Browse files
ucatbasucatbas
authored
Merge pull request #2738 from jonasfrisell/add-railway-docs
docs: add Railway deployment guide
2 parents 82dd860 + bf44a10 commit bdbf262

3 files changed

Lines changed: 138 additions & 0 deletions

File tree

‎docs/mint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -311,6 +311,7 @@
311311
"setting-up/installation/brew",
312312
"setting-up/installation/container",
313313
"setting-up/installation/fly",
314+
"setting-up/installation/railway",
314315
"setting-up/installation/google",
315316
"setting-up/installation/helm",
316317
"setting-up/installation/kubernetes",

‎docs/setting-up/installation/intro.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,16 @@ Here is some options that you can use to set up and deploy Permify in your serve
5353
Deploying Permify with Helm Charts.
5454
</Card>
5555
</div>
56+
<div style={{ flex: "1 1 calc(50% - 20px)", margin: "10px" }}>
57+
<Card title="Fly.io" icon="paper-plane" href="/setting-up/installation/fly">
58+
Deploy Permify on Fly.io with PostgreSQL.
59+
</Card>
60+
</div>
61+
<div style={{ flex: "1 1 calc(50% - 20px)", margin: "10px" }}>
62+
<Card title="Railway" icon="train" href="/setting-up/installation/railway">
63+
One-click deploy Permify on Railway with PostgreSQL.
64+
</Card>
65+
</div>
5666
</div>
5767

5868
If you have any questions, feel free to join our [Discord community](https://discord.gg/n6KfzYxhPp) and start a discussion!

‎docs/setting-up/installation/railway.mdx‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Deploy on Railway
3+
---
4+
5+
This guide covers deploying Permify on Railway, either via a one-click template or manual setup.
6+
7+
## One-Click Deploy
8+
9+
The fastest way to get started:
10+
11+
[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/permify)
12+
13+
This template automatically provisions:
14+
- A Permify instance with API authentication enabled
15+
- A PostgreSQL database for persistent storage
16+
- Private networking between services
17+
18+
## What Gets Deployed
19+
20+
### Permify Service
21+
22+
The template deploys the latest Permify container image with the following default configuration:
23+
24+
| Variable | Default Value | Description |
25+
|----------|---------------|-------------|
26+
| `PERMIFY_DATABASE_ENGINE` | `postgres` | Database backend |
27+
| `PERMIFY_DATABASE_URI` | Auto-configured | Connection string to PostgreSQL |
28+
| `PERMIFY_AUTHN_ENABLED` | `true` | Enable API authentication |
29+
| `PERMIFY_AUTHN_METHOD` | `preshared` | Authentication method |
30+
| `PERMIFY_AUTHN_PRESHARED_KEYS` | Auto-generated | 32-character secret key |
31+
| `PERMIFY_LOG_LEVEL` | `info` | Logging verbosity |
32+
33+
### PostgreSQL Database
34+
35+
A dedicated PostgreSQL instance is provisioned and connected to Permify over Railway's private network. The database connection is configured automatically—no manual setup required.
36+
37+
## Connecting Your Application
38+
39+
After deployment, add these environment variables to your application service to connect to Permify:
40+
```shell
41+
PERMIFY_HOST=${{Permify.RAILWAY_PRIVATE_DOMAIN}}
42+
PERMIFY_GRPC_PORT=3478
43+
PERMIFY_REST_PORT=3476
44+
PERMIFY_API_KEY=${{Permify.PERMIFY_AUTHN_PRESHARED_KEYS}}
45+
```
46+
47+
### Available Endpoints
48+
49+
Permify exposes two ports:
50+
51+
| Port | Protocol | Description |
52+
|------|----------|-------------|
53+
| 3476 | HTTP/REST | REST API and health checks |
54+
| 3478 | gRPC | High-performance gRPC API |
55+
56+
<Note>
57+
Both ports are accessible over Railway's private network by default. To expose them publicly, configure a public domain in your Railway service settings.
58+
</Note>
59+
60+
## Verifying the Deployment
61+
62+
By default, Permify runs on Railway's private network with no public access. To verify the deployment:
63+
64+
**Option 1: Check Railway logs**
65+
66+
View the deployment logs in Railway's dashboard. A successful start shows:
67+
```
68+
🚀 grpc server successfully started: 3478
69+
🚀 http server successfully started: 3476
70+
```
71+
72+
**Option 2: Expose a public domain**
73+
74+
To test externally, add a public domain in Railway's service settings (Settings → Networking → Public Networking). Then:
75+
```
76+
curl https://<your-public-domain>/healthz
77+
```
78+
79+
You should see:
80+
```json
81+
{"status":"SERVING"}
82+
```
83+
84+
**Option 3: From another Railway service**
85+
86+
Your application can reach Permify on the private network at:
87+
```
88+
http://permify.railway.internal:3476/healthz
89+
```
90+
91+
## Manual Deployment
92+
93+
If you prefer to deploy manually instead of using the template:
94+
95+
### 1. Create a New Project
96+
97+
Create a new project in Railway and add a PostgreSQL database.
98+
99+
### 2. Add the Permify Service
100+
101+
Add a new service and deploy from the Docker image:
102+
```
103+
ghcr.io/permify/permify:latest
104+
```
105+
106+
### 3. Configure Environment Variables
107+
108+
Set the following environment variables on your Permify service:
109+
```shell
110+
PERMIFY_DATABASE_ENGINE=postgres
111+
PERMIFY_DATABASE_URI=${{Postgres.DATABASE_URL}}
112+
PERMIFY_AUTHN_ENABLED=true
113+
PERMIFY_AUTHN_METHOD=preshared
114+
PERMIFY_AUTHN_PRESHARED_KEYS=<your-secret-key>
115+
PERMIFY_LOG_LEVEL=info
116+
```
117+
118+
### 4. Set the Start Command
119+
120+
Configure the start command:
121+
```
122+
permify serve --database-auto-migrate=true
123+
```
124+
125+
### 5. Expose Ports
126+
127+
In the service settings, expose ports 3476 (REST) and/or 3478 (gRPC) as needed.

0 commit comments

Comments
 (0)