Module 5: Deployment

From Localhost to the World

The “Works on My Machine” Problem

Figure: Local vs. Production environment gap.

• Local: You control everything.
• Production: The untamed wild.
• Goal: Bridge the gap reliably.

• Hook: We’ve all been there. It runs perfectly on your laptop, but fails the moment you show it to someone else.
• Context: In the previous modules, we built an API, containerized it, and connected a database. But it’s still trapped on your machine.
• The Gap: Deployment is about crossing the chasm between a controlled local environment and the public internet. Today, we make your work real.

The Road to Production

1. Configuration: Separating secrets from code.
2. Platform: Hosting on Railway (PaaS).
3. Database: Managed storage & networking.
4. Automation: Continuous Deployment interactions.
5. Diagnostics: validation & logs.

• Lay of the Land: Here is our journey for this module.
• Step 1: We start by securing our app with Environment Variables.
• Step 2: We choose a home for it—Railway, a Platform as a Service.
• Step 3: We give it memory by provisioning a production database.
• Step 4: We automate the process so we never manually copy files again.
• Step 5: Finally, we learn how to fix it when things break.

Part 1: Mental Models

Configuration: Code vs. Environment

Figure: Separation of code and configuration.

• Rule: Code and Config must be strictly separated.

• Python:

  import os
  # Reads from System Env or .env file
  db_url = os.getenv("DATABASE_URL")

• Why: Security (Secrets) & Flexibility.

• Definition: The “12-Factor App” methodology states strict separation of config from code.
• Code: Notice the Python snippet. We don’t hardcode the URL. We ask the Operating System for it.
• Benefit: This allows the same code to run locally (reading from a .env file) and in production (reading from the platform’s secret store).

The Binding Contract: Host & Port

Figure: Localhost vs. Public interface binding.

• 127.0.0.1 (Localhost): Listening inside the house (Loopback).
• 0.0.0.0 (Any): Listening at the front door (Public).
• $PORT: The specific door number assigned by the cloud.

• The Problem: By default, apps run on localhost (127.0.0.1). This is secure—only you can access it.
• Fix: For deployment, we must listen on 0.0.0.0. This tells the app to accept connections from the outside world.
• The Port: We don’t verify the port (like 8000). The Cloud Provider gives us a dynamic port variable $PORT that we must use.

The Start Command

Figure: The web server start command.

• Purpose: Tells the platform how to run your app.
• Procfile: Standard file for run commands (web: uvicorn ...).
• Flags: --host 0.0.0.0 and --port $PORT.

• The Instruction: Installing dependencies is not enough; the server needs to know what command starts the web server.
• Procfile: We often use a Procfile to declare this: “web equals this command”.
• Vital Flags: We explicitly pass the host and port arguments we just learned about.

About Railway

Figure: PaaS deployment workflow.

• Flexible Sources: Deploy from Repo (Code) or Registry (Docker Image).
• Hassle-Free: Sane defaults & Zero Config out of the box.
• Operational Model: “Push to Deploy” with built-in observability.

• What is Railway? It’s a modern cloud deployment platform designed for instant deployments and effortless scaling.
• Flexibility: You can point it to a GitHub repo (it builds the image for you) or bring your own Docker image.
• Philosophy: It emphasizes “Sane Defaults”. You don’t need a PhD in Kubernetes to get online. It just works.

Provisioning PostgreSQL

Figure: Internal networking between services.

• Managed Service: Automated backups, updates, and scaling.
• Internal Networking: Secure communication (private IP).
• Connection: DATABASE_URL env var auto-injected.

• The Database: Moving your database to production is scary. Data loss is permanent.
• Managed Services: We use a “Managed” Postgres. Railway handles backups and uptime.
• Networking: Crucially, your web app talks to the database over an private internal network, not the public internet. It’s faster and more secure.
• Auto-Magic: Railway often auto-injects the connection string as DATABASE_URL, simplifying configuration.

Part 2: Execution Walkthrough

Step 1: Preparation

Figure: Python project dependency manifests.

• pyproject.toml: Project metadata & dependencies (managed by uv).
• uv.lock: Lockfile for reproducible builds.
• Procfile: Defines the start command (e.g., web: dbmate --wait up && uvicorn ...).

• Modern Python: We use uv locally, so we rely on pyproject.toml instead of requirements.txt.
• The Wait Flag: In the Procfile, we use dbmate --wait up. This is crucial because it tells our app to wait until the database is ready before applying migrations and starting the server.
• Automation: This ensures that every deployment automatically updates your database schema before your code runs.

Step 2: Connection

Figure: Connecting GitHub to the deployment platform.

• Source: Connect GitHub account.
• Repo: Select your project repository.
• Trigger: “Deploy Now” (starts initial build).

• Linking Up: We don’t upload files. We link our GitHub repository.
• Access: This gives Railway permission to read our code and watch for changes.
• First Run: It will try to deploy immediately. It might fail if config is missing—that’s okay.

Step 3: Variables

Figure: Configuring environment variables.

• Dashboard: Go to “Variables” tab.
• Secrets: Add OPENAI_API_KEY, passwords, etc.
• Redeploy: Changing variables triggers a restart.

• Injecting Secrets: Remember the 12-Factor App? This is where we input those values.
• Security: These values are encrypted and injected into the container at runtime. The public never sees them.

Step 4: Provision Database

Figure: Provisioning a managed database service.

• Action: Add “PostgreSQL” service (Plugin).
• Wiring: Railway auto-injects DATABASE_URL variable.
• Migrations: Handled via dbmate on startup.

• One-Click Power: We click “New Service” -> “Database”.
• Magic: Railway spins up a Postgres container and automatically sets the DATABASE_URL variable in our web app.
• The Handshake: Because of our Procfile command (dbmate --wait up), the moment this variable is available, our app will apply any new migrations to the production database automatically.

Step 5: Verification

Figure: Verifying the deployed API.

• Public URL: https://your-project.up.railway.app
• Routes: Check /docs for Swagger UI.
• Test: Make a live request.

• The Moment of Truth: Click the generatd URL.
• Docs: If you see the Swagger UI, your API is alive effectively.
• Live: You can now send this link to anyone in the world.

Continuous Deployment & Environments

Figure: Continuous Deployment lifecycle and environments.

• Trigger: git push triggers build & deploy.
• Environments: Supports Static (Prod) and Ephemeral (PR Previews).
• Workflow: Test changes in a unique URL before merging.

• Automation: The act of saving your code is the deployment mechanism.
• Environments: Railway isn’t just for Production.
• Review Apps: It can create “Ephemeral Environments” for every Pull Request. You get a unique URL to test your changes (like a new feature) in isolation before merging to main.

Diagnostics: When Things Break

Figure: Monitoring build and application logs.

• Build Logs: Why did the build fail? (e.g., missing dependencies).
• Deploy Logs: Why did the container crash? (e.g., migration failures).
• Web Console: Real-time feedback on migrations & startup.

• Reality Check: Your first deployment will likely fail. That’s normal.
• The Detective Work: Check the Deploy Logs. If dbmate fails (e.g., a syntax error in your migration SQL), the app won’t start.
• Wait Timeout: If the database takes too long to respond, dbmate --wait will timeout (default 60s). This is also visible in the logs.

Key Takeaways

Figure: Key takeaways for successful deployment.

• Separate Config: Use Env Vars, never hardcode secrets.
• Trust the Platform: Let PaaS handle the infrastructure.
• Automate: git push should be your only deployment command.
• Observe: Logs are your eyes and ears in production.

• Summary: We’ve transformed a local script into a global service.
• Review: We secured it with config, hosted it on a managed platform, automated updates with Git, and learned how to debug it.
• Next: Your API is now ready for real users.