From laptop to live URL
You just finished a Go service. It handles requests, talks to a database, and runs perfectly on your laptop. You want to put it on the internet so a friend can use it, or so your API consumer can hit an endpoint. You don't want to manage a VPS, configure systemd, or fight with Dockerfiles that break on every minor change. You want the code to go from your terminal to a live URL with as little friction as possible. Railway automates the build and run steps for Go projects, turning your repository into a running service.
How Railway handles Go
Think of Railway as a kitchen that already has the stove, the ingredients, and a chef who knows the recipe. You just hand over the dish instructions. Railway looks at your code, sees it's Go, grabs the Go toolchain, compiles the binary, and starts the process. You don't configure the build environment. You don't manage the server. The platform handles the plumbing. Your job is to write the code and point Railway at your repository.
Railway detects Go projects by looking for a go.mod file. When it finds that file, it assumes you have a standard Go module. It runs the build, creates a minimal container image, and launches your binary. The process must stay alive and listen on the correct port. If the binary exits, the service crashes. If it listens on the wrong port, the health check fails. The platform restarts the service automatically, but your goal is to get it running correctly the first time.
Railway handles the build. You handle the code.
Minimal deployable app
Here's the simplest Go app Railway can deploy: a single file that reads the port from the environment and starts an HTTP server. Railway injects a PORT environment variable into the container. Your code must read that variable and bind to it.
package main
import (
"fmt"
"net/http"
"os"
)
// main starts an HTTP server on the port provided by the environment.
func main() {
// Railway sets PORT. Fall back to 8080 for local development.
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
// Handle the root path with a simple response.
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello from Railway")
})
// Start the server. The process blocks here until it fails.
// Railway expects the main goroutine to stay alive.
fmt.Printf("Listening on :%s\n", port)
if err := http.ListenAndServe(":"+port, nil); err != nil {
fmt.Printf("Server failed: %v\n", err)
}
}
The binary must listen. If it exits, the service dies.
What happens during the build
When you push code to GitHub and link the repository to Railway, the platform triggers a build pipeline. Railway clones the repository and scans the root directory. It finds go.mod and identifies the project as Go. The build environment includes the Go toolchain. Railway runs go build to compile the binary. The compiler produces a static executable by default. This binary contains everything needed to run, including the standard library and your dependencies.
The binary is copied into a minimal Linux container. The container starts with the binary as the entry point. The process begins executing. Railway monitors the process. It checks if the process is still running. It also performs a health check by connecting to the port the process listens on. If the process crashes or the port is unreachable, Railway restarts the container. The logs from stdout and stderr are captured and displayed in the dashboard. You can view the build logs to see the compilation output. You can view the runtime logs to see your application's output.
Go modules are the standard way to manage dependencies. Make sure your module is initialized with go mod init. The build process runs go build in the module root. If you have a Makefile, Railway might use it, but the default detection is robust for standard Go projects. Run gofmt -w . before you commit. The community expects formatted code, and it prevents style debates in reviews. Most editors run gofmt on save, so your code should already be clean.
Check the logs. The error message usually tells you exactly what went wrong.
Realistic service structure
Real apps have dependencies, configuration, and error handling. They need a go.mod file to define the module and its requirements. They often use environment variables for secrets and configuration. Railway supports all of this. The build process respects go.mod and go.sum. It downloads dependencies and compiles the code.
Here's a server configuration with production-ready timeouts. Railway expects the process to stay alive, and timeouts protect your server from slow clients.
package main
import (
"fmt"
"log"
"net/http"
"os"
"time"
)
// main initializes the HTTP server with timeouts and environment configuration.
func main() {
// Railway sets PORT. Default to 8080 for local testing.
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
// Configure timeouts to protect against slow clients.
srv := &http.Server{
Addr: ":" + port,
ReadTimeout: 5 * time.Second,
WriteTimeout: 10 * time.Second,
Handler: http.HandlerFunc(handler),
}
// Log startup and start listening.
log.Printf("Listening on :%s", port)
if err := srv.ListenAndServe(); err != nil {
log.Fatalf("Failed to start: %v", err)
}
}
// handler writes the response body.
func handler(w http.ResponseWriter, r *http.Request) {
fmt.Fprintln(w, "OK")
}
Environment variables are the standard way to configure deployed apps. Railway lets you set variables in the dashboard. Your code reads them with os.Getenv. Never hardcode secrets. If you use a database, pass the connection string as an environment variable. The compiler rejects undefined variables. If you reference a variable that doesn't exist, you get an undefined error. If you use a package that requires C libraries, you need to enable CGO. Railway supports CGO, but you might need to install system dependencies. The build fails if the linker can't find the library. Check the build logs for missing header files.
The blank identifier _ discards values. Use it when a function returns multiple values and you only need one. For example, result, _ := someFunc() drops the error. Use this sparingly. Dropping errors hides bugs. The community prefers explicit error handling. if err != nil makes the failure path visible. The boilerplate is verbose by design, and it keeps the unhappy path clear.
Timeouts protect your server. Environment variables configure it.
Common pitfalls
If your binary exits immediately, Railway marks the service as crashed. The log will show the process ending. This happens if you forget to start a server or if the server starts in a goroutine and the main function returns. The main goroutine must block. If you start the server in a goroutine, you need a mechanism to keep the main function alive, like waiting on a channel or a signal.
If you forget to read the PORT variable and hardcode 8080, the health check fails because Railway assigns a dynamic port. The service appears down even though the binary is running. Always read the port from the environment.
The build fails with go.mod file not found in current directory or any parent directory if you don't have a module file. Initialize the module with go mod init and commit go.mod and go.sum. If you use a dependency that requires a specific Go version, Railway detects the version from go.mod. If you need a different version, you can override it in the project settings.
The compiler rejects unused imports with imported and not used. Remove the import or use the blank identifier _ if you need the side effect. If you pass the wrong type to a function, the compiler complains with cannot use x as string value in argument. Fix the type mismatch before deploying.
If your app depends on a database, the connection might fail on startup. Railway restarts the service, which can cause a loop. Add retry logic or handle the error gracefully. The worst goroutine bug is the one that never logs. If you spawn a goroutine and it panics, the panic might not propagate to the main process. Recover from panics in goroutines and log the error.
Goroutines are cheap. Channels are not magic.
When to use Railway
Use Railway when you want zero-config deployment for a Go binary. Use a VPS when you need full control over the OS and networking. Use a container registry when you want to manage the image lifecycle yourself. Use a serverless platform when your app is event-driven and scales to zero. Use Railway when you have a long-running process that needs a persistent URL. Use a static host when you only serve HTML and assets.
Pick the tool that matches your control needs. Automation saves time until you need control.