Skip to content

Railway

Railway is one of the easiest ways to deploy Hyperterse. It provides automatic deployments from GitHub, built-in PostgreSQL, SSL certificates, and zero-configuration setup.

Quick deploy

Section titled “Quick deploy”

  1. Export bundle

    Terminal window
    hyperterse export -f config.terse -o dist

  2. Create Dockerfile

    FROM alpine:3.19
    

    # Install bash and ca-certificates for HTTPS database connections
    RUN apk --no-cache add bash ca-certificates
    

    WORKDIR /app
    

    # Copy the exported script (replace 'config' with your actual script name)
    COPY dist/config /app/config
    

    # Make script executable
    RUN chmod +x /app/config
    

    EXPOSE 8080
    

    # Run the script
    CMD ["/app/config"]

    Note: Replace config with the actual name of your exported script (it matches your config filename without the .terse extension).

  3. Push to GitHub

    Commit and push your code to a GitHub repository:

    Terminal window
    git add Dockerfile dist/
    git commit -m "Add Hyperterse deployment"
    git push origin main

    Ensure your repository is public or connected to Railway.

  4. Create Railway project

    • Go to Railway dashboard
    • Click “New Project”
    • Select “Deploy from GitHub repo”
    • Authorize Railway to access your GitHub account if needed
    • Select your repository

  5. Configure deployment

    Railway will automatically:

    • Detect your Dockerfile
    • Build your Docker image
    • Deploy your container
    • Assign a public URL with SSL

    No additional configuration needed!

  6. Add environment variables

    In the Railway dashboard:

    • Go to your service → Variables
    • Add DATABASE_URL with your database connection string
    • Click “Add” to save

    Security: Railway encrypts environment variables automatically.

Railway PostgreSQL Recommended

Section titled “Railway PostgreSQL ”

Railway makes it easy to add a managed PostgreSQL database:

  1. Add PostgreSQL database

    In your Railway project:

    • Click “New” → “Database” → “Add PostgreSQL”
    • Railway automatically creates a PostgreSQL instance

  2. Automatic connection

    Railway automatically:

    • Creates a DATABASE_URL environment variable
    • Links it to your Hyperterse service
    • Handles connection pooling

    No manual configuration needed!

  3. Access database

    • Click on the PostgreSQL service
    • Use the “Query” tab to run SQL queries
    • Or connect using any PostgreSQL client with the connection string

Configuration

Section titled “Configuration”

Railway automatically handles:

  • Public URL: Every deployment gets a *.railway.app URL
  • SSL certificates: Automatic HTTPS with Let’s Encrypt
  • Restarts: Automatically restarts on crashes
  • Logs: Real-time log streaming in the dashboard
  • Deployments: Automatic deployments on every Git push

Environment variables

Section titled “Environment variables”

Railway provides multiple ways to manage environment variables.

Via Railway Dashboard

Section titled “Via Railway Dashboard”
  • Go to your service → Variables
  • Add, edit, or delete variables
  • Changes take effect immediately

Via Railway CLI

Section titled “Via Railway CLI”
Terminal window
# Install Railway CLI
npm i -g @railway/cli


# Login
railway login


# Link to your project
railway link


# Set variable
railway variables set DATABASE_URL="postgresql://..."


# View all variables
railway variables

Via railway.toml

Section titled “Via railway.toml”

Create a railway.toml file in your project root:

railway.toml
[build]
builder = "dockerfile"


[deploy]
startCommand = "/app/config"
healthcheckPath = "/heartbeat"
healthcheckTimeout = 100
restartPolicyType = "always"

Custom domain

Section titled “Custom domain”

Add your own domain to Railway:

  1. Add domain in Railway

    • Go to your service → Settings → Domains
    • Click “Add Domain”
    • Enter your domain (e.g., api.example.com)

  2. Configure DNS

    Railway provides DNS instructions:

    • Add a CNAME record pointing to Railway’s domain
    • Or add an A record with Railway’s IP

  3. SSL certificate

    Railway automatically provisions and renews SSL certificates via Let’s Encrypt.

Scaling

Section titled “Scaling”

Railway supports horizontal scaling:

  1. Adjust replica count

    • Go to your service → Settings → Scaling
    • Increase the replica count
    • Railway will distribute traffic across instances

  2. Configure health checks

    Railway automatically health checks your service:

    • Default: Checks root path /
    • Customize in railway.toml:
    [deploy]
    healthcheckPath = "/heartbeat"
    healthcheckTimeout = 100

Monitoring and logs

Section titled “Monitoring and logs”

View logs:

  • Dashboard: Go to your service → Logs tab
  • CLI: railway logs (streams logs in real-time)

Metrics:

Railway provides basic metrics in the dashboard:

  • Request count
  • Response times
  • Error rates
  • Resource usage

For advanced monitoring, integrate with external services like Datadog or New Relic.

Continuous deployment

Section titled “Continuous deployment”

Railway automatically deploys on every Git push:

  • Main branch: Deploys to production
  • Other branches: Can be configured for preview deployments
  • Rollbacks: Click “Redeploy” → Select a previous deployment

Troubleshooting

Section titled “Troubleshooting”

Deployment fails: Check build logs in Railway dashboard. Common issues include incorrect Dockerfile paths or missing files.

Can’t connect to database: Verify DATABASE_URL is set correctly and that the database service is running.

Service won’t start: Check logs for errors. Common issues include incorrect port configuration (should be 8080) or missing environment variables.

High costs: Railway charges based on usage. Monitor your usage in the dashboard and consider:

  • Using Railway’s free tier for development
  • Optimizing resource usage
  • Setting up usage alerts