Deploy and Host HAProxy on Railway

HAProxy is a high-performance open-source load balancer and reverse proxy used to distribute traffic across backend services. It helps improve availability, route HTTP/TCP traffic, handle failover, and provide a reliable entry point for web applications, APIs, microservices, and internal services.

About Hosting HAProxy

On Railway, HAProxy can run as a lightweight traffic layer for your application stack. It is useful when you need a dedicated reverse proxy, load balancer, simple routing layer, or central entry point for self-hosted services.

This template includes a default HAProxy configuration so the service can start immediately after deployment. You can keep the default configuration, customize it through Git/GitHub, or provide a persistent custom configuration through a Railway Volume.

Common Use Cases

• Reverse proxy for web apps, APIs, and internal services
• Load balancing across multiple backend instances
• Routing requests by domain, path, port, or service type
• Improving reliability with backend health checks and failover
• Central traffic entry point for microservices
• HTTP and TCP proxying for self-hosted applications

Dependencies for HAProxy Hosting

• HAProxy Docker image
• A valid HAProxy configuration
• One or more backend services to proxy traffic to
• Railway public networking or private service networking
• Optional Railway Volume mounted at /data for persistent custom config

Deployment Dependencies

• HAProxy Docker Image
• HAProxy Documentation
• Railway Documentation

Configuration

This template supports two HAProxy configuration paths:

By default, HAProxy uses:

/usr/local/etc/haproxy/haproxy.cfg

If a Railway Volume is attached and this file exists:

/data/haproxy.cfg

the container will automatically use /data/haproxy.cfg instead of the default image configuration.

Startup behavior:

/data/haproxy.cfg exists     -> use /data/haproxy.cfg
/data/haproxy.cfg not found  -> use /usr/local/etc/haproxy/haproxy.cfg

This lets the template work immediately after deployment while still supporting persistent user-managed configuration.

Using Custom Configuration

To customize HAProxy persistently, create or update:

/data/haproxy.cfg

After editing the config, always validate it:

haproxy -c -f /data/haproxy.cfg

If the configuration is valid, restart or redeploy the Railway service.

HAProxy does not automatically reload config changes just because the file was edited.

Update Configuration via Railway Console

Open your HAProxy service in Railway, then open the Console tab.

View the default config:

cat /usr/local/etc/haproxy/haproxy.cfg

Copy the default config into the Railway Volume:

cp /usr/local/etc/haproxy/haproxy.cfg /data/haproxy.cfg

Edit the custom config:

vi /data/haproxy.cfg

If vi is unavailable, overwrite the file manually:

cat > /data/haproxy.cfg <<'EOF'
global
    maxconn 4096
    log stdout format raw local0
    log stdout format raw local1 notice
    user root
    chroot /

defaults
    log     global
    mode    http
    option  httplog
    timeout connect 5000
    timeout client  50000
    timeout server  50000

frontend main
    bind *:80
    http-request return status 200 content-type text/plain string "Custom HAProxy config from /data is running."

listen stats
    bind *:8404
    stats enable
    stats admin if TRUE
    stats uri /stats

EOF

Validate the config:

haproxy -c -f /data/haproxy.cfg

Then restart or redeploy the service from Railway.

After restart, logs should show that HAProxy is using:

/data/haproxy.cfg

Update Configuration via Railway CLI

Install and authenticate Railway CLI, then link your project:

railway login
railway link

Open an interactive shell inside the deployed service:

railway ssh

If your project has multiple services, select the HAProxy service.

Copy the default config to the persistent volume:

cp /usr/local/etc/haproxy/haproxy.cfg /data/haproxy.cfg

Edit it:

vi /data/haproxy.cfg

Or overwrite it:

cat > /data/haproxy.cfg <<'EOF'
global
    maxconn 4096
    log stdout format raw local0
    log stdout format raw local1 notice
    user root
    chroot /

defaults
    log     global
    mode    http
    option  httplog
    timeout connect 5000
    timeout client  50000
    timeout server  50000

frontend main
    bind *:80
    http-request return status 200 content-type text/plain string "Custom HAProxy config from Railway CLI is running."

listen stats
    bind *:8404
    stats enable
    stats admin if TRUE
    stats uri /stats

EOF

Validate it:

haproxy -c -f /data/haproxy.cfg

Exit the shell:

exit

Restart the service:

railway restart

Use redeploy if you want to trigger a new deployment:

railway redeploy

Update Configuration via Git / GitHub

Use this workflow if you want to manage HAProxy changes through GitHub and let Railway redeploy after every push.

Source repository:

https://github.com/codestorm-official/haproxy

Steps:

1. Deploy the template on Railway.
2. Open the deployed HAProxy service in Railway.
3. Open Source Repo or Upstream Repo from the Railway dashboard.
4. Fork the repository to your own GitHub account.
5. Clone your fork locally:

git clone https://github.com/YOUR_USERNAME/haproxy.git
cd haproxy

6. Edit the default HAProxy config:

haproxy.cfg

This file is copied into the image as:

/usr/local/etc/haproxy/haproxy.cfg

7. Validate locally if HAProxy is installed:

haproxy -c -f haproxy.cfg

8. Commit and push your changes:

git add .
git commit -m "Customize HAProxy configuration"
git push origin main

9. In Railway, change the service Source Repo to your fork if Railway does not automatically link it.
10. After the service is connected to your fork, future pushes can trigger automatic redeployments.

Important: Git/GitHub changes update the default image config. If /data/haproxy.cfg exists, HAProxy will still use /data/haproxy.cfg instead of the Git-based default config.

To use the Git/GitHub config again, remove the custom volume config:

rm /data/haproxy.cfg

Then restart or redeploy the service.

Console vs CLI vs GitHub

For production or reusable templates, Git/GitHub is usually the cleanest workflow because every change is tracked in commit history.

Roll Back to Default Configuration

If your custom config breaks or you want to return to the default image config, remove:

rm /data/haproxy.cfg

Then restart the service.

On the next startup, HAProxy will fall back to:

/usr/local/etc/haproxy/haproxy.cfg

Example Backend Configuration

Example backend for one Railway service:

backend app_backend
    balance roundrobin
    server app1 your-service.railway.internal:3000 check

Example backend for multiple Railway services:

backend app_backend
    balance roundrobin
    server app1 app-1.railway.internal:3000 check
    server app2 app-2.railway.internal:3000 check

Example frontend using the backend:

frontend main
    bind *:80
    default_backend app_backend

Replace the service names and ports with your actual Railway service private domains and internal ports.

Important Notes

• Editing haproxy.cfg does not reload HAProxy automatically.
• Always validate the config before restarting the service.
• Use /data/haproxy.cfg for persistent custom configuration.
• Use /usr/local/etc/haproxy/haproxy.cfg as the default image configuration.
• If /data/haproxy.cfg exists, it takes priority over the default config.
• If /data/haproxy.cfg does not exist, the default image config is used.
• If the last line of haproxy.cfg is missing a newline, HAProxy may fail with a Missing LF on last line error.

Why Deploy HAProxy on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway hosts your infrastructure so you do not have to deal with manual server configuration, while still allowing you to scale vertically and horizontally.

By deploying HAProxy 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.