Deploy and Host Locomotive on Railway

A Railway sidecar service for sending webhook events when new logs are received. Supports Discord, Datadog, Axiom, BetterStack and more!

About Hosting Locomotive

Configuration is done through environment variables. Metadata is gathered once when the locomotive starts. If a project/service/environment name has changed, the name in the metadata will not be correct until the locomotive is restarted. The body will always be a JSON array containing one or more log objects. Various common timestamp attributes are included in every log object to increase compatibility with external logging services. The default Content-Type for these POST requests is set to application/json.

Common Use Cases

Log Aggregation: Send Railway application logs to external logging services like Datadog, Axiom, and BetterStack
Team Notifications: Forward log events to Discord and Slack channels for real-time monitoring and alerting
Log Analytics: Stream logs to Grafana Loki for centralized log analysis and visualization

Dependencies for Locomotive Hosting

The Railway template includes the required sidecar service configuration and webhook connectivity.

Deployment Dependencies

Implementation Details

Configuration Variables:

Core configuration:

RAILWAY_API_KEY: Your Railway API key (project level keys do not work)
ENVIRONMENT_ID: The environment ID your service is in (auto-filled to the current environment ID)
TRAIN: The ID of the service you want to monitor (supports multiple service IDs, separated with a comma)

Discord Integration:

DISCORD_WEBHOOK_URL: The Discord webhook URL to send logs to (optional)
DISCORD_PRETTY_JSON: Pretty print the RAW JSON object in Discord embeds

Slack Integration:

SLACK_WEBHOOK_URL: The Slack webhook URL to send logs to (optional)
SLACK_PRETTY_JSON: Pretty print the RAW JSON object in Slack embeds
SLACK_TAGS: Tags to add to the Slack message (supports multiple tags, separated with a comma, optional)

Loki Integration:

LOKI_INGEST_URL: The Loki ingest URL to send logs to (optional)

Generic Webhook Integration:

INGEST_URL: The URL to send a generic request to (optional)
ADDITIONAL_HEADERS: Any additional headers to be sent with the generic request (useful for auth, in the format of a cookie)

System Configuration:

REPORT_STATUS_EVERY: Reports the status of the locomotive every 5 seconds (default: 5s, format must be in the Golang time.DurationParse format)

Log Filtering:

Level Filters:

LOGS_FILTER: Global level filter applied to all outputs
LOGS_FILTER_DISCORD: Level filter applied to Discord output
LOGS_FILTER_SLACK: Level filter applied to Slack output
LOGS_FILTER_LOKI: Level filter applied to Loki output
LOGS_FILTER_WEBHOOK: Level filter applied to webhook output

Level filter options: ALL, INFO, ERROR, WARN, or any custom combination of severity/level. Accepts multiple values, separated with a comma. Defaults to allowing all log levels.

Content Filters:

LOGS_CONTENT_FILTER: Global content filter applied to all outputs
LOGS_CONTENT_FILTER_DISCORD: Content filter applied to Discord output
LOGS_CONTENT_FILTER_SLACK: Content filter applied to Slack output
LOGS_CONTENT_FILTER_LOKI: Content filter applied to Loki output
LOGS_CONTENT_FILTER_WEBHOOK: Content filter applied to webhook output

Content filters support regular expressions or plain text searches.

Generic Webhook Log Formats:

Locomotive supports both plaintext and structured JSON logs, with metadata including deploymentId, deploymentInstanceId, environmentId, environmentName, projectId, projectName, serviceId, and serviceName. Structured log attributes sent to Grafana Loki must always be a string.

Why Deploy Locomotive on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

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