Railway Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The MoodTune Backend is a FastAPI-based Python application deployed on the Railway platform. Its primary purpose is to handle mood analysis via librosa, manage Spotify OAuth integrations, facilitate audio file uploads, and perform catalog searches. The deployment integrates with Supabase Postgres as the primary data store, utilizing the Supabase Python client for data persistence.
The deployment infrastructure is defined through a monorepo structure where the backend resides in the moodtune-backend directory. The system is designed to be highly portable, supporting both local development environments and cloud-based production environments via Railway's containerized execution model.
Sources: README.md:1-5, CLAUDE.md:1-6
Deployment Configuration
The Railway deployment is governed by the railway.toml file, which specifies the build process, start command, and health monitoring parameters. The application uses uvicorn as the ASGI server to handle incoming HTTP requests.
Build and Execution Flow
The diagram shows the sequence from build initiation to active traffic routing based on the project's configuration files.
Sources: railway.toml:1-5, README.md:16-20
Service Parameters
| Configuration | Value | Description |
|---|---|---|
| Root Directory | moodtune-backend | The path within the repository containing the backend code. |
| Build Command | pip install -r requirements.txt | Installs Python dependencies for the FastAPI environment. |
| Start Command | uvicorn app.main:app --host 0.0.0.0 --port $PORT | Launches the ASGI server on the Railway-assigned port. |
| Health Check Path | /health | The endpoint Railway polls to verify service availability. |
Sources: railway.toml:1-5, README.md:16-20
Environment Infrastructure
Successful deployment requires the configuration of several critical environment variables. These variables facilitate connections to external services such as Supabase and Spotify, and define security parameters for the FastAPI application.
Required Environment Variables
| Variable | Source / Purpose |
|---|---|
SUPABASE_URL | The endpoint for the Supabase Postgres database. |
SUPABASE_KEY | Anonymous public key for client-side interactions. |
SUPABASE_SERVICE_KEY | Service role key for bypassing Row Level Security (RLS). |
SPOTIFY_CLIENT_ID | OAuth credential for the Spotify Web API. |
SPOTIFY_CLIENT_SECRET | Secret key for Spotify application authentication. |
BACKEND_CORS_ORIGINS | Comma-separated list of allowed frontend origins. |
Sources: README.md:7-14, TEST_PLAN.md:11-19
Database Connectivity
The backend interacts with Supabase Postgres. It is critical that the Supabase project configuration allows incoming connections from Railway's egress IPs if IP allowlisting is enabled. The application uses the service role key to perform administrative database operations where RLS is active.
Sources: README.md:22-25
Integration and Resource Management
The deployment handles resource-intensive tasks, specifically audio analysis and file uploads, which require specific server-side configurations.
Audio Processing Pipeline
When a file is uploaded to the Railway-hosted instance, the AudioAnalysisService writes the data to a temporary directory defined in the settings before processing it with librosa.
This sequence illustrates the in-memory and temporary storage lifecycle of an audio analysis request within the Railway instance.
Sources: app/api/v1/audio_upload.py:20-60, CLAUDE.md:6-10
Operational Constraints
The deployment enforces several limits to maintain stability on Railway:
- Max Upload Size: Defined by
MAX_UPLOAD_SIZE_MB, preventing memory exhaustion during file buffering. - Format Validation: Only specific formats in
ALLOWED_AUDIO_FORMATSare processed. - Processing Time: Tracked via
processing_time_secondsin the response to monitor performance.
Sources: app/api/v1/audio_upload.py:34-45, app/api/v1/audio_upload.py:75-80
Deployment Verification
Verification of a successful deployment on Railway is performed using health checks and automated test scripts.
Health and Status Endpoints
- Service Health: The
/healthendpoint is used by Railway's infrastructure to determine if the container is responsive. - Spotify Status: The
/api/v1/spotify/statusendpoint verifies if the backend can communicate with both Supabase and Spotify.
Automated Verification Script
Developers use test_api.sh to verify the live Railway deployment by providing a valid Supabase JWT.
# Example verification against local or deployed instance
./test_api.sh YOUR_SUPABASE_JWT_TOKEN
Sources: test_api.sh:1-15, TEST_PLAN.md:36-45
Summary
The Railway deployment of MoodTune Backend provides a containerized environment for FastAPI, leveraging railway.toml for lifecycle management. By integrating Supabase for persistence and Spotify for catalog data, the deployment creates a scalable infrastructure for audio-based mood analysis. Key operational aspects include the management of environment variables for external service authentication and the secure handling of temporary file systems for librosa-based processing.