How to Use Railway: The Beginner's Guide (First Deploy, a Database That Connects, Env Vars, and a Custom Domain)

CodexFuse Team · 2026-10-31T03:57:27.257Z · 19 min read

How to Use Railway: The Beginner's Guide (First Deploy, a Database That Connects, Env Vars, and a Custom Domain)

Learning how to use Railway is the shortest path most beginners will ever take from "it works on my laptop" to "it is live on the internet." Railway is a platform-as-a-service that deploys your app directly from a GitHub repo: you push your code, Railway detects your language and framework, builds it in the cloud, and hands you a live URL — no servers to provision, no YAML files, no Docker knowledge required. It also provisions a real database (PostgreSQL, MySQL, Redis, or MongoDB) with one click and wires it to your app automatically.

This Railway for beginners tutorial walks the complete arc, step by step: sign up and claim the trial credit, deploy from GitHub through the dashboard, deploy from your terminal with the Railway CLI, read a build log when something fails, add a PostgreSQL database and connect it with an injected connection string, manage environment variables the right way, and point a custom domain at your app with automatic HTTPS. Once your app is live, keep an eye on it with a website uptime monitor so the first person to notice downtime is you, not your users.

What Is Railway and How Do You Deploy an App on It?

Railway is a deployment platform where each project can hold your app, its database, its cache, and any other services, all networked together privately. Unlike serverless platforms that run your code as short-lived functions, Railway runs your application as a persistent process — a real server that stays up, keeps connections open, and handles long-running requests. That is why it fits WebSocket servers, background-job workers, and LLM agent backends that outlive function timeouts.

Deploying for the first time takes four moves:

1. Push your code to GitHub. Railway deploys from a GitHub repository; a linked GitHub account is required.
2. Create a project. In the Railway dashboard, click New Project and choose the GitHub repo option, then Deploy Now — or scaffold from your terminal with railway init and deploy with railway up.
3. Watch the build. Railway detects your stack, builds it in the cloud (with Railpack, its default builder, or your own Dockerfile), and streams the logs.
4. Open your URL. Generate a Railway domain from the service's settings, or attach your own domain — HTTPS is provisioned automatically.

What Do You Need Before You Deploy on Railway?

Three things, and all of them are free to start. You need a GitHub account with your project pushed to a repository, a Railway account (created by signing in with that GitHub account — Railway prompts you to link it), and a project that already runs on your own machine. If your app does not start locally, Railway cannot fix it in the cloud; get npm start, python app.py, or whatever your command is working first.

Signing up gets you a one-time grant of $5 in trial credits, and no credit card is required to start. The credits are applied toward any usage on the platform and expire in 30 days. After the trial, the entry plan is $1 per month (up to 1 vCPU and 0.5 GB RAM per service, 0.5 GB of volume storage, community support, 3-day log history), with the Hobby plan at $5 per month including $5 of monthly usage credit and the Pro plan at $20 per month including $20 of monthly usage credit. Included credits reset each billing cycle and do not accumulate, but if you upgrade while trial credits remain, the leftover balance carries over to your new plan.

How Do You Deploy a Project from GitHub on Railway?

Deploy from GitHub when you want automatic deployments on every push — this is the path the official quick-start tutorial teaches first, and it is the right default for beginners. Open the Railway dashboard, click New Project, and choose the GitHub repo option. Search for your repository, select it, and you get two choices: Deploy Now, which builds and deploys immediately, or Add variables, which takes you to your service first so you can add secrets and then hit Deploy yourself.

Once the project is created you land on the Project Canvas — Railway's term for the visual map of your project. Every service, environment, and deployment in the project is controlled from this canvas, and it is where you will add databases, set variables, and open logs. If anything fails during this first deploy, open the build or deploy logs and scroll through the whole log: the quick-start tutorial's own tip is that the actual error is rarely at the bottom, and important details get missed when you only read the tail.

This arc starts from a repo, so if Git is the part you are unsure about, a GitHub beginner guide covers the push-to-repo steps that happen before Railway ever sees your code.

How Do You Deploy from Your Terminal with the Railway CLI?

The Railway CLI is for local-development workflows and CI/CD pipelines — it lets you deploy without touching the dashboard. Install it once, then work from your project's folder:

npm install -g @railway/cli
railway login
railway init
railway up

railway login opens your browser to authorize the CLI. railway init creates a new empty project and links your local directory to it. railway up is the whole deploy: it scans your project files, compresses them, uploads them to Railway's backend, and streams the build and deployment logs to your terminal in real time. When the deploy finishes, railway open takes you back to the Project Canvas.

The CLI has three useful modifiers. Add -d (or --detach) to upload and return immediately, letting the deployment continue in the background — check on it with railway logs. Add -c (or --ci) to stream only the build logs and exit when the build completes, which is what you want inside CI/CD pipelines. And railway redeploy re-runs the current deployment without uploading new code, which is the fast way to apply an environment-variable change or restart a crashed service.

For automated deployments, do not use interactive login: create a Project Token in the dashboard and use it instead. Project tokens are scoped to one environment and can only do deployment-related actions — deploy code, redeploy, and view logs — and Railway reports deployment status back to GitHub, so you can trigger actions after deploys complete. If your project has several services, railway up will ask which one you mean, and by default the CLI respects your .gitignore when deciding what to upload.

How Does Railway Build Your App?

Railway builds your code with Railpack — its default builder — or with your Dockerfile if the project has one. Railpack detects your language, framework, and build system from the files in your repo (a package.json with a start script for Node.js, a requirements.txt for Python, and so on), so most projects build with zero configuration. If you have unusual requirements, adding a Dockerfile overrides the detection entirely, which makes Railway also a fine host for stacks its auto-detection does not cover.

Understanding this is what separates beginners who deploy from beginners who debug. A Docker beginner guide is worth reading at this point, not because Railway requires Docker knowledge, but because every build log you will ever read is the story of a container being assembled — knowing what a build layer is turns a wall of log text into a progress report you can actually follow.

What Do You Do When a Deploy Fails?

You read the build logs before you change anything. Open the failed deployment on the Project Canvas and scroll the full log, top to bottom — the tutorial's advice is blunt: the real error is rarely at the bottom. A missing start command, a dependency that installs locally but not in the build, or a step that assumes files your .gitignore excluded are the three usual suspects, and the log tells you which one you are looking at.

After the build succeeds, a second failure mode appears: the service starts and immediately crashes. Nine times out of ten, this is a port problem — your app is listening on a hard-coded port or on localhost instead of the address Railway expects. Never hard-code your port; read it from the environment and bind to all interfaces (for example, 0.0.0.0 plus the PORT value Railway provides). Check your service's Networking settings to see which port Railway routes to, then make your code match it.

The other classic is the missing secret: your code works locally because your .env file is sitting on your laptop, and the deployed service never got those values. That is not a build problem and not a code problem — it is a variables problem, covered two sections from here. The fix takes thirty seconds once you know where the Variables tab lives.

How Do You Add a PostgreSQL Database on Railway?

Adding a database is the feature that makes Railway feel unfair compared to the old way of doing things. On the Project Canvas, click New, choose Database, and pick PostgreSQL — Railway provisions it inside your project in under a minute, on the same private network as your app service. This one-click Railway PostgreSQL setup is the fastest way to put a real database behind a first app, and MySQL, Redis, and MongoDB work the same way, and every database also comes in a high-availability variant with automatic failover if you need it later.

Here is the part beginners should understand precisely: Railway injects the connection string into your app automatically. Your code just reads it from the environment — in Node.js, that looks like process.env.DATABASE_URL — and you never type, copy, or commit the actual URL. Services inside one project talk to each other over private networking, so database traffic never touches the public internet. If you need to connect from your own laptop, the database service offers a TCP proxy for external access.

Know where Railway's responsibility ends. Railway provisions the database, ships security patches for its images, and shows you database metrics and query statistics in the database view — but backups, point-in-time recovery (PostgreSQL and MySQL), connection pooling (PostgreSQL), and high availability are switches you turn on yourself, and your schema, queries, indexes, and data are always yours. Also note that Railway does not publish an uptime SLA for its databases today. If your backup strategy is "the platform probably handles it," turn the backup switch on before you have users, not after.

How Do Railway Environment Variables Work?

Every service has a Variables tab in the dashboard, and that tab — not a file you commit — is where your app's configuration lives. Click New Variable to add a single value, or use the RAW Editor to paste the contents of a .env file directly. When you connect a GitHub repo, Railway scans the repository root for .env, .env.example, .env.local, and .env.production files and offers to import their variable names for you — it imports the names, not your local secrets, which is exactly the behavior you want.

Variables come in three flavors. Service variables belong to one service. Shared variables are defined once in Project Settings and then attached to whichever services need them, which keeps things like an API key defined in one place instead of copied five times. Reference variables are defined by pointing at another variable with template syntax: ${{ shared.VARIABLE_KEY }} for a shared variable, ${{SERVICE_NAME.VAR}} for a variable on another service, and ${{ VARIABLE_NAME }} for one in the same service. This is how the database connection string flows into your app without you ever pasting it.

Three rules keep this system safe. First, adding, updating, or removing variables creates a set of staged changes you must review and deploy — nothing applies silently, which is good, but it also means a variable change without a redeploy does nothing. Second, never put the injected database URL or any production secret into your repository; read them from the environment in code. Third, for your most sensitive values, use sealed variables: their values reach builds and deployments but are never visible in the UI and cannot be retrieved through the API. You cannot un-seal a sealed variable later, so choose that option deliberately.

During local development you do not have to guess whether your deployed variables are correct: link the CLI to your project and run railway run <command> — for example railway run npm run dev — and your code executes locally with the environment variables configured in your Railway project.

How Do You Get a URL and Add a Custom Domain?

A Railway service does not get a public domain automatically, but getting one takes seconds. Open your service's settings, find the Networking section, and choose Generate Domain — you get a free *.up.railway.app address. That is enough for testing, demos, and sharing with a friend.

Your own domain takes two DNS records, and both are required. In the same Networking section, click + Custom Domain and type your domain (wildcards like *.example.com are supported). Railway hands you a CNAME record pointing at your service's Railway address and a TXT record used to verify that you own the domain. Add both to your DNS provider exactly as shown. If the TXT record is missing, requests to your custom domain return a 404 even after the CNAME resolves — that two-record requirement is the heart of the Railway custom domain flow, and Railway will not route traffic to you until ownership is verified. Two more facts the docs state plainly: Railway does not publish a static IP, so A records are not supported (use CNAME, or ALIAS/ANAME for root domains where your provider supports it), and DNS changes can take up to 72 hours to propagate worldwide, although they usually land much faster.

HTTPS is the easy part: Railway automatically issues an SSL certificate for your custom domain once the records verify, and renewals happen on their own. If you do not own a domain yet, Railway also sells them directly at railway.com/domains — over 250 TLDs, one-year registrations, auto-renewal on by default, with DNS fully managed by Railway so pointing works without manual records. And for terminal-first setups, the railway domain command generates service domains, adds custom domains, and retries certificate issuance when DNS was the problem.

How Much Does Railway Cost?

Railway pricing is usage-based, metered per second, and the trial is genuinely usable: $5 in one-time credits, 30 days to spend them, no credit card required. The question every beginner asks next is what $5 actually buys. The published rates are $0.00000772 per vCPU-second (about $20 per vCPU per month of continuous use), $0.00000386 per GB-second of memory (about $10 per GB per month), $0.00000006 per GB-second of volume storage, and $0.05 per GB of egress. Worked through: a small always-on service running 0.5 vCPU with 0.5 GB of memory costs roughly $15 per month — so the $5 trial covers about ten days of continuous running for that service, or a full month if your app is smaller or sleeps between uses. Tiny side projects fit comfortably; a production app with real traffic will outgrow the trial, which is the point of a trial.

After the trial, the plans step up cleanly. The $1-per-month entry tier caps each service at 1 vCPU and 0.5 GB RAM with 0.5 GB of volume storage — enough for hobby projects. The Hobby plan at $5 per month includes $5 of monthly usage credit, so small projects often cost nothing extra beyond the subscription; you only pay for usage above the credit. The Pro plan at $20 per month includes $20 of monthly usage credit and unlocks up to 1,000 vCPU and 1 TB of RAM per service, 42 replicas, 20 custom domains, and 30-day log history for teams shipping to production. One honest detail worth knowing: included usage resets every billing cycle and never rolls over, so size your plan to a normal month, not your busiest one.

Railway vs Render vs Vercel: Which Should You Pick?

These three get compared constantly because they all promise "push code, get a URL" — but they host fundamentally different things. The table below draws the lines as they matter to a beginner choosing a first platform:

The short version: if your project is a frontend with API routes, Vercel is the natural home; if it is a persistent server with a database that needs to stay connected, Railway and Render are the candidates, and Railway's edge is that the database lives inside the same project on the same private network with its connection string injected automatically. If you want the PaaS model but on your own server instead of a hosted platform, that is a different lane entirely — what is VPS hosting explains the self-hosted side, where you rent the machine and manage everything on it.

What Comes After Your First Deploy?

Your first deploy is the beginning, not the end. Turn on automatic GitHub deploys so every push to your branch rebuilds and redeploys — the Project Canvas shows each deployment and its logs, so regressions are one scroll away from their cause. Open a pull request and Railway can spin up a preview environment for it, giving reviewers a live copy of your app with its own services instead of screenshots.

Then think about operations like someone with users. Read the build logs the way the tutorial teaches — top to bottom, not the tail first. Set up the observability dashboard on the canvas to watch CPU, RAM, and disk per service, and configure alerts so a resource spike reaches you before it becomes an outage. A deployed app that nobody watches is a hobby project with extra steps; the professional habit starts with the second deploy, not the hundredth.

Sources

Every fact in this guide was verified on the platform's official pages on 2026-10-30 — making this Railway tutorial current as of October 30, 2026: the quick-start tutorial (dashboard GitHub deploy flow, CLI railway init / railway up / railway open, Railpack/Dockerfile builds, Generate Domain, the build-log reading tip, 650+ templates) at docs.railway.com/quick-start; the CLI deployment reference (log streaming, --detach, --ci, railway redeploy, railway logs, project tokens, GitHub deployment status, PR environments, .gitignore handling) at docs.railway.com/cli/deploying; the databases page (PostgreSQL/MySQL/Redis/MongoDB templates and HA variants, security patches, user-turned-on backups and point-in-time recovery, private networking, TCP proxy, volume storage, no published uptime SLA) at docs.railway.com/databases; the variables guide (Variables tab, RAW editor, .env import suggestions, shared and reference variables, ${{...}} template syntax, sealed variables, staged changes, railway run, Heroku import) at docs.railway.com/guides/variables; the working-with-domains guide (Generate Domain, custom domains with required CNAME + TXT records, the 404-on-missing-TXT behavior, wildcards, domain purchase at railway.com/domains, the railway domain command, no static IPs, up-to-72-hour propagation) at docs.railway.com/networking/domains/working-with-domains; and the pricing page (the $5 one-time 30-day trial credit, the $1/month entry tier, Hobby $5/mo with $5 included usage, Pro $20/mo with $20 included usage, per-second CPU/memory/volume/egress rates, credit reset and carry-over rules) at railway.com/pricing. The Railway-vs-Render-vs-Vercel framing cross-checks live 2026 guide coverage from dev.to and bestdeployplatform.com; the usage-rate arithmetic ($5 ≈ 10 days of a 0.5 vCPU / 0.5 GB always-on service) is computed from Railway's published per-second rates, not copied from any article.

Frequently Asked Questions

Can I use Railway for free without a credit card?

Yes. New accounts get a one-time grant of $5 in trial credits with no credit card required, and the credits apply to any usage on the platform. They expire in 30 days, so the trial is real but time-boxed — enough to deploy a real app and learn the platform, not enough to host production indefinitely.

Does Railway host my database too?

Yes — PostgreSQL, MySQL, Redis, and MongoDB are available as one-click services inside your project, on the same private network as your app, with the connection string injected automatically as an environment variable. Railway ships security patches for these templates; you turn on backups, point-in-time recovery, and high availability yourself, and your schema and data stay yours.

What happens to my app when my code has a bug in production?

The service crashes, Railway's restart policy kicks in, and the deploy logs show you the crash. For a real error-tracking loop — knowing which deploy introduced the bug and getting alerted instead of discovering it from users — pair your deploy with an error-tracking tool; reading one real crash end to end is the fastest way to learn what production looks like.

Is Railway better than Render for beginners?

They solve the same problem and both are beginner-friendly. Railway's distinguishing move is that databases live inside the same project as your app on private networking with auto-injected connection strings, while Render treats databases as separate products. If you already know Render, the concepts transfer almost one to one — pick whichever trial experience you prefer and move on; neither choice is a trap.

Do I need Docker to use Railway?

No. Railway's default builder, Railpack, detects your language and framework from your repo files and builds without any container knowledge. You only need a Dockerfile if your stack has unusual requirements — and if you are curious how the build actually works under the hood, that is exactly what a beginner Docker guide is for.