Deploy Mage AI

Deploy and Host Mage AI on Railway

Mage AI is an open source data pipeline tool that data and analytics engineers use to build, schedule and monitor the jobs moving data between systems. Each step is a block of Python, SQL or R written in a notebook-style editor; you connect the blocks into a graph, preview each block's output as you go, then attach a trigger and let the built-in scheduler run it. It covers ground that usually takes three tools: loading through its connectors, transformation in code, and orchestration with retries, backfills and run history. Teams pick it over older orchestrators because you see real data at every step while writing the pipeline.

Deploy Mage AI on Railway and this template gives you the workspace wired together. The mage service runs the web server and scheduler in one container, on a 5 GB volume holding pipeline code, block outputs, run logs and the key Mage encrypts stored secrets with. A managed Postgres holds orchestration metadata: users, triggers, pipeline runs and block runs. A managed Redis gives the job queue a liveness key and the scheduler a distributed lock. Only mage gets a public domain; Postgres and Redis stay private, reached through reference variables.

Getting Started with Mage AI on Railway

Set DEFAULT_OWNER_EMAIL, DEFAULT_OWNER_USERNAME and DEFAULT_OWNER_PASSWORD before you deploy: Mage reads them once, on first boot, to create the owner account. There is no anonymous registration, so the owner adds every other user from Settings. Open the public URL, sign in at /sign-in, and you arrive at the Overview dashboard. Mage scaffolds a project called default_repo on the volume and ships a working example_pipeline for confirming everything is connected: open it from Pipelines and you get three blocks that fetch the Titanic dataset, fill in missing values and export the cleaned frame. On the Triggers tab press Run@once, then Run now. Watch the Runs tab until the row reads Done with 3/3 block runs: that proves the scheduler dispatches work, metadata reaches Postgres and the volume is writable. Then use New pipeline to start your own, and Settings to add users. Warehouse credentials go in io_config.yaml.

About Hosting Mage AI

Self-hosting Mage AI means running the editor, API, scheduler and execution kernel yourself, so pipeline code and the data it touches never leave infrastructure you control. That matters when pipelines carry customer records or reach a private database.

Key features:

• Notebook-style editor with per-block output previews and charts
• Batch, streaming and data integration pipeline types
• Cron, event and API triggers, plus backfills
• Sources and destinations built on the Singer spec
• Native dbt support, so existing dbt models run as blocks
• Block-level tests, per-block run logs and role-based access control

The architecture is deliberately small. Mage's server forks the scheduler at startup and runs each block in its own subprocess, so one container handles the UI and the work. Postgres stores what the orchestrator needs to survive a restart; Redis lets the queue recover an orphaned job.

Why Deploy Mage AI on Railway

Railway removes the setup work self-hosting an orchestrator involves.

• Postgres and Redis provisioned and connected, no connection strings to copy
• Volume mounted and sized, so pipeline code and secrets survive redeploys
• HTTPS and a public domain issued automatically
• Private networking keeps the database and cache off the internet
• Logs, metrics and rollbacks built in
• Vertical scaling is a slider, not a migration

Common Use Cases

• Warehouse ELT — pull from Postgres, Stripe or an API on a schedule, land raw data in Snowflake or BigQuery, then transform it with SQL blocks or dbt models.
• Replacing cron scripts — move a folder of Python jobs onto a scheduler that records every run and retries failures.
• Reverse ETL — push modelled tables back to the tools your team uses when the upstream job finishes.
• Feature and reporting pipelines — build ML features or daily reporting tables, with block-level tests that fail the run on bad data.

Dependencies for Mage AI

• mage — built from gridalpha/mage-railway, one layer over the official mageai/mageai image. Serves the UI and API on port 6789 and runs the scheduler in the same container.
• Postgres — Railway's managed ghcr.io/railwayapp-templates/postgres-ssl image, holding users, triggers, pipeline runs, block runs and encrypted secrets.
• Redis — Railway's managed redis image, used for the job queue's client-liveness key and the scheduler's distributed lock.

Environment Variables Reference

Deployment Dependencies

• Source repository: gridalpha/mage-railway
• Upstream project: mage-ai/mage-ai
• Docker image: mageai/mageai
• Documentation: docs.mage.ai

Hardware Requirements for Self-Hosting Mage AI

Block runs execute in the same container as the server, so size for the heaviest pipeline you expect, not the UI.

The image is around 1.3 GB compressed, so the first deploy spends a few minutes pulling it. Pipelines loading large pandas frames are the usual reason to raise memory. The runtime is Python 3.10.

Self-Hosting Mage AI with Docker

To run Mage locally against SQLite, mount a project directory and start the image:

docker run -it -p 6789:6789 \
  -v $(pwd)/mage_project:/home/src \
  -e REQUIRE_USER_AUTHENTICATION=1 \
  -e DEFAULT_OWNER_EMAIL=you@example.com \
  -e DEFAULT_OWNER_PASSWORD=change-me \
  mageai/mageai:latest /app/run_app.sh mage start default_repo

Beyond a laptop, point Mage at Postgres so orchestration state survives a restart. The following is a Docker Compose definition:

services:
  mage:
    image: mageai/mageai:latest
    ports:
      - "6789:6789"
    volumes:
      - ./mage_project:/home/src
    environment:
      MAGE_DATABASE_CONNECTION_URL: postgresql+psycopg2://user:pass@db:5432/mage
      REDIS_URL: redis://cache:6379/0
      REQUIRE_USER_AUTHENTICATION: "1"

How Much Does Mage AI Cost to Self-Host?

Mage AI is free and open source under the Apache 2.0 licence, with no seat limits, no run limits and no paid tier gating the scheduler or the connectors. The company sells Mage Pro, a hosted product, but nothing here depends on it. On Railway you pay only for the compute, memory and storage the services use.

FAQ

What is Mage AI?

An open source data pipeline tool for building, scheduling and monitoring data workflows. Each step is a block of Python, SQL or R whose output you preview as you write it, connected into a pipeline the scheduler runs.

What does this Railway template deploy?

Three services: mage, running the web server and scheduler on a 5 GB volume behind a public HTTPS domain; a managed Postgres for orchestration metadata; and a managed Redis for the job queue and scheduler lock.

Why does the template include Postgres and Redis?

Without an external database Mage keeps triggers, runs and users in SQLite, a poor fit for a container recreated on every deploy. Redis gives the job queue a liveness key so an orphaned job is re-queued, and is required before running a second scheduler.

How do I log in to self-hosted Mage AI the first time?

Set DEFAULT_OWNER_EMAIL, DEFAULT_OWNER_USERNAME and DEFAULT_OWNER_PASSWORD before the first deploy and sign in at /sign-in. Mage creates that owner only while none exists, so a later password change in the UI is permanent.

How do I connect Mage AI to my warehouse?

Edit io_config.yaml in the project file browser, add a profile with your Snowflake, BigQuery, Redshift or Postgres credentials, then reference it from a loader or exporter block. Values can be read from environment variables.

Is Mage AI a good Airflow alternative?

For teams whose pipelines are mostly extraction and transformation, yes: Mage gives you the editor, connectors and scheduler in one tool with immediate output previews, where Airflow expects you to build and test code elsewhere. Airflow still wins on ecosystem breadth and very large DAG counts.