Railway Deployment Guide
Relevant source files
The following files were used as context for generating this wiki page:
Thoth uses Terraform to provision and manage infrastructure on the Railway platform. The deployment encompasses the core API service, a PostgreSQL database, and automated database migration jobs.
The system automates the lifecycle of the application by linking the GitHub repository directly to Railway services. It configures environment variables, handles domain binding, and executes one-shot migration tasks using Flyway.
Provisioning Workflow
You provision the infrastructure using the Terraform CLI. The Railway provider requires a valid API token to interact with the project.
- Copy
terraform.tfvars.exampletoterraform.tfvarsand set the required variables. - Export your Railway API token:
export RAILWAY_TOKEN="<token>". - Initialize Terraform:
terraform init. - Apply the configuration:
terraform apply.
Sources: infra/railway/README.md:5-9
The diagram shows the sequential steps to provision the Thoth infrastructure from a local environment to Railway.
Sources: infra/railway/README.md:7-9, infra/railway/project.tf:1-3
Core Infrastructure Components
Railway Project
The railway_project resource serves as the top-level container for all services and environments. It uses a name defined in the var.project configuration.
Sources: infra/railway/project.tf:1-3
API Service
The API service runs the backend application. It pulls source code from a specific GitHub repository and branch.
- Source Configuration: Uses
var.project.repoandvar.project.branch. - Config Path: Points to
apps/api/railway.toml. - Domain: Binds a custom domain if
var.api.domainis provided, otherwise defaults to the Railway public domain. - Port: Routes traffic to the target port specified in
var.api.port.
Sources: infra/railway/api.tf:1-20, infra/railway/locals.tf:13
Database Migrations
The system runs one-shot Flyway jobs to handle schema changes. These jobs execute within the private network to ensure security.
- Service Name: Prefixed with
migrate-(e.g.,migrate-api). - Config Path: Points to
flyway/railway.toml. - Network: Connects to the database using
${{Postgres.RAILWAY_PRIVATE_DOMAIN}}. - Source: Derived from the
migrationsmap in local variables.
Sources: infra/railway/migrate.tf:2-23, infra/railway/locals.tf:30-32
Environment Configuration
The railway_variable_collection resource manages environment variables for each service. The following table details the primary configuration keys used by the API service.
| Variable | Description | Source |
|---|---|---|
PORT | The network port the API listens on | var.api.port |
DATABASE_URL | Connection string for PostgreSQL | ${{Postgres.DATABASE_URL}} |
GITHUB_CLIENT_ID | OAuth application ID for authentication | var.github.client_id |
BETTER_AUTH_SECRET | Secret key for the authentication layer | random_password.better_auth |
OPENROUTER_API_KEY | API key for LLM integration | var.llm.api_key |
CORS_ORIGINS | Allowed origins for web requests | local.api_domain |
Sources: infra/railway/locals.tf:15-28, infra/railway/api.tf:8-12
Database Environment Variables
The PostgreSQL instance is configured with the following local variables:
PGDATA: Set to/var/lib/postgresql/data/pgdata.POSTGRES_USER&POSTGRES_DB: Defined byvar.db.name.POSTGRES_PASSWORD: A randomly generated password.
Sources: infra/railway/locals.tf:4-11
Service Architecture
The diagram illustrates the relationship between the GitHub source code, the public-facing API service, and the private database and migration infrastructure.
Sources: infra/railway/api.tf:1-20, infra/railway/migrate.tf:2-23, infra/railway/locals.tf:4-11
Conclusion
Thoth leverages Terraform and Railway to create a reproducible deployment environment. By separating the API service from the migration jobs and utilizing Railway's private networking for database access, the project maintains a secure and scalable architecture. The use of variables and local definitions ensures that environment-specific configurations remain decoupled from the infrastructure logic.