---
title: "Deploy Mage AI — Self-Hosted Notebook-Style Data Pipelines"
description: "Self-host Mage — notebook-style data pipelines, Airflow alternative"
category: "Analytics"
url: https://railway.com/deploy/mage-ai-data-pipelines
---

# Deploy Mage AI — Self-Hosted Notebook-Style Data Pipelines

Self-host Mage — notebook-style data pipelines, Airflow alternative

**[Deploy Mage AI — Self-Hosted Notebook-Style Data Pipelines on Railway](https://railway.com/template/mage-ai-data-pipelines)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/mage-ai-data-pipelines/manifest.json

- **Creator:** SB
- **Category:** Analytics

## Template content

### Mage https://raw.githubusercontent.com/mage-ai/assets/main/logo/m1.svg

- **Source:** gridalpha/mage-railway
- **Public domain:** Yes

### Redis https://cdn.sanity.io/images/sy1jschh/production/0ce0bfdcfbdbf69662b1116671f97c2dd788b655-157x157.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### Postgres https://devicons.railway.app/i/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

## Documentation

# Deploy and Host Mage AI on Railway

Mage AI is an open-source data pipeline tool for building, scheduling, and monitoring data workflows — a modern, notebook-style alternative to Airflow. Each pipeline step is a block of Python, SQL, or R whose output you preview as you write it, chained into a pipeline the built-in scheduler runs on a cron with retries and per-run logs. This template deploys the official Mage image with PostgreSQL for orchestration state, a persistent volume for your pipelines, authentication on, and the numpy boot fix that makes it actually start on Railway.

---

## What This Template Deploys

| Service | Purpose |
| --- | --- |
| **Mage AI** | The notebook-style pipeline editor, scheduler, and API on port `6789` |
| **PostgreSQL** | Users, triggers, pipeline runs, block runs, and encrypted secrets |
| **Redis** | The job-queue liveness key and the scheduler's distributed lock |

All connect over Railway's private network. Mage serves the UI and runs the scheduler in one container, PostgreSQL holds orchestration state, Redis coordinates the scheduler, and a persistent volume stores your pipeline code — a working data-engineering stack from the first deploy.

---

## About Hosting

Mage is powerful, and three specifics decide whether it deploys cleanly and securely on Railway — all handled here.

**The numpy boot fix — why this template starts where a plain deploy doesn't.** Every published `mageai/mageai` image ships a numpy build that mis-registers its ufuncs on the hardware Railway runs on: Mage imports scikit-learn on startup, scipy falls over on the broken numpy, and the server dies before it ever binds a port. This template reinstalls numpy from PyPI at boot, which is why it starts reliably where a plain `docker run` of the same image crashes on Railway — the difference between a Mage that deploys here and one that doesn't.

**Authentication is on — Mage executes arbitrary code.** This is critical: a Mage instance is a web UI that runs arbitrary Python, SQL, and shell commands, with a built-in terminal, on a public domain. Mage's own default requires authentication, yet some Railway templates turn it back off — leaving an open remote-code-execution surface. This template keeps `REQUIRE_USER_AUTHENTICATION` on and creates an owner from `DEFAULT_OWNER_EMAIL`/`DEFAULT_OWNER_PASSWORD`, so your instance is behind a login from the first deploy. Change the password after signing in.

**Two things persist — pipelines and orchestration state.** Mage stores your pipelines and project as code files on a volume at `/home/src`, while orchestration data (triggers, runs, block runs, encrypted secrets) lives in PostgreSQL via `MAGE_DATABASE_CONNECTION_URL`. Both matter: without the volume you lose pipeline code, and without Postgres (the default SQLite is ephemeral on a PaaS) you lose run history. This template wires both, so your work and history survive redeploys.

**Blocks run in the server container — size for your heaviest pipeline.** Mage executes block code in the same container as the server, so memory should be sized for the largest pipeline you expect, not the UI. Pipelines loading large pandas frames are the usual reason to raise RAM. The image is around 1.3 GB, so the first deploy spends a few minutes pulling it.

**Preview output as you build.** Mage's signature is the interactive, notebook-style editor: each block previews its output as you write, so a broken join is visible in the editor rather than three tables downstream. Blocks connect into a pipeline the scheduler runs, and Mage integrates dbt, connectors, and custom blocks.

Typical cost: **~$10–20/month** on Railway for Mage, Postgres, and Redis, scaling with pipeline memory. Mage is Apache-2.0 and free — no seat, run, or connector limits.

---

## How It Compares

| | Mage AI (self-hosted) | Airflow | Prefect | Cron jobs |
| --- | --- | --- | --- | --- |
| Authoring | Notebook-style blocks | Python DAGs | Python decorators | Shell scripts |
| Preview as you build | Yes | No | No | No |
| Languages | Python, SQL, R | Python-centric | Python | Any |
| Built-in dbt + connectors | Yes | Plugins | Some | No |
| Data ownership | Full — your infra | Full | Full | Full |
| Self-hostable | Yes | Yes | Yes | N/A |

Airflow is powerful but heavy and DAG-centric, with no interactive preview. Prefect is Pythonic but code-first without a notebook UI. A pile of cron jobs has no dependencies, alerting, or run history. Mage's edge is the notebook-style experience — write a block in Python, SQL, or R and see its output immediately, chain blocks into scheduled pipelines with retries and logs, and use built-in dbt and connectors — self-hosted, on infrastructure you own.

---

## Deploy in Under 5 Minutes

1. Click **Deploy on Railway** — Mage, PostgreSQL, and Redis build and wire together (~5 minutes, large image)
2. Confirm `REQUIRE_USER_AUTHENTICATION` is on and `MAGE_DATABASE_CONNECTION_URL` points at Postgres
3. Open your Railway URL on port `6789` and sign in with your owner credentials
4. Create a pipeline, add a Python or SQL block, and preview its output as you write
5. Chain blocks, set a schedule with retries, and watch runs in the monitoring view

---

## Common Use Cases

- **Scheduled ETL into a warehouse** — pull from an API or database, transform in Python or SQL, load into Postgres, BigQuery, or Snowflake on a cron
- **Data prep for analytics and ML** — chain transformation blocks with previewed output at each step
- **dbt orchestration** — run and schedule dbt models alongside Python and SQL blocks

---

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `REQUIRE_USER_AUTHENTICATION` | Pre-set | On — Mage runs arbitrary code, so keep it behind a login |
| `DEFAULT_OWNER_EMAIL` / `DEFAULT_OWNER_PASSWORD` | Required | Owner account created on first boot — change the password after |
| Storage volume | Pre-set | Persistent volume at `/home/src` for pipeline code and project data |

> **Auth is on and both stores persist.** Mage executes arbitrary Python/SQL/shell, so `REQUIRE_USER_AUTHENTICATION` stays on with an owner account. Pipelines live on the `/home/src` volume and orchestration state in Postgres (not ephemeral SQLite) — both wired here.
> **Size RAM for your pipelines.** Blocks run in the server container, so provision memory for your heaviest pipeline, not the UI. The ~1.3 GB image takes a few minutes to pull on first deploy.

---

## Dependencies for Mage AI Hosting

- Railway account — ~$10–20/month for Mage, Postgres, and Redis, scaling with pipeline memory
- PostgreSQL for orchestration state (included and wired)
- Redis for the scheduler lock (included)
- A persistent volume at `/home/src` for pipeline code (included)

### Deployment Dependencies

- [Mage AI GitHub Repository](https://github.com/mage-ai/mage-ai)
- [Mage AI Documentation](https://docs.mage.ai/)
- [Mage AI Production Auth](https://docs.mage.ai/production/authentication/overview)
- [Railway Private Networking](https://docs.railway.com/guides/private-networking)

### Implementation Details

The template runs the official `mageai/mageai` image on port `6789`, serving the UI and API and running the scheduler in the same container, with PostgreSQL (users, triggers, pipeline runs, block runs, encrypted secrets) and Redis (job-queue liveness key and scheduler lock) over the private network, plus a persistent volume at `/home/src` for pipeline code. `MAGE_DATABASE_CONNECTION_URL` uses the `postgresql+psycopg2://` scheme; the default SQLite store is ephemeral on a PaaS.

A key adaptation makes it start at all: every published `mageai/mageai` image ships a numpy that mis-registers its ufuncs on Railway's hardware, so Mage's startup import of scikit-learn triggers a scipy failure on the broken numpy and the server dies before binding a port. The template reinstalls numpy from PyPI at boot to fix this. Authentication is enabled via `REQUIRE_USER_AUTHENTICATION` with an owner account from `DEFAULT_OWNER_EMAIL`/`DEFAULT_OWNER_PASSWORD`, because a Mage instance executes arbitrary Python, SQL, and shell with a built-in terminal and must not be public without a login. Block code runs in the server container, so size memory for the heaviest pipeline; the image is ~1.3 GB, so the first deploy pulls for a few minutes. PostgreSQL and the `/home/src` volume are the backup targets.

---

## Frequently Asked Questions

**Why does Mage crash on other Railway deploys?** The published `mageai/mageai` images ship a numpy that mis-registers its ufuncs on Railway's hardware, so Mage's startup import of scikit-learn fails and the server dies before binding a port. This template reinstalls numpy at boot, so it starts reliably.

**Is my Mage instance secure?** Yes — this template keeps `REQUIRE_USER_AUTHENTICATION` on with an owner account. That matters because Mage runs arbitrary Python, SQL, and shell with a built-in terminal; some templates disable auth, leaving an open code-execution surface. Change the password after first login.

**How is Mage different from Airflow?** Mage is notebook-style — you write blocks in Python, SQL, or R and preview each block's output as you build, rather than authoring Python DAGs with no interactive feedback. It's lighter to run and includes dbt and connectors.

---

## Why Deploy Mage AI on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Mage AI on Railway you get a notebook-style data pipeline tool with the hard parts solved — the numpy boot fix so it actually starts, authentication on, PostgreSQL for orchestration state, and a volume for your pipelines. Build, schedule, and monitor data workflows in Python, SQL, and R, self-hosted on infrastructure you own.

## Similar templates

- [Typesense vs Meilisearch](https://railway.com/deploy/typesense-vs-meilisearch) — self-hosted Typesense vs Meilisearch
- [Betterlytics](https://railway.com/deploy/betterlytics) — Betterlytics is a cookieless analytics platform GDPR-compliant.
- [Finance Tracker](https://railway.com/deploy/finance-tracker-1) — Private multi-user household finance ledger with budgets and CSV import.

Open this page in a browser: https://railway.com/deploy/mage-ai-data-pipelines