# Migrate Railway app: Next.js

Move Next.js compute from Railway app to Ample, one component at a time. Destination verified on Ample: the app built, started and answered on its public HTTPS URL with encrypted configuration delivered.

## Source procedure: 
Export variables from the Railway service (Variables tab or `railway variables`) into an env file kept out of the repository. Not migrated automatically: Railway cron schedules, volumes and private networking are not migrated; persistent data belongs in a managed database, a bucket or an Ample volume.

## Cutover: 
Add the custom domain with `ample domain add`, update DNS from the Railway target, keep the Railway service until verified, then remove it.

## Rollback: 
Keep the source untouched until you confirm; nothing at the source is changed or deleted by this guide.

## Prerequisites
- Authorized access to the Railway app source and its export tooling.
- An inventory of every component in scope and out of scope.
- A validated backup or copy before any cutover.
- An Ample account token with servers:write, databases:read.

## Workflow Steps
1. **Inventory the source**  
   List what Railway app provides beyond the component you are moving. Out of scope: Railway cron schedules, volumes and private networking are not migrated; persistent data belongs in a managed database, a bucket or an Ample volume.

2. **Source step 1**  
   Export variables from the Railway service (Variables tab or `railway variables`) into an env file kept out of the repository.

3. **Source step 2**  
   Translate `railway.json`/Nixpacks settings into the repository's build and start commands; Ample detects Node and Python builds itself.

4. **Source step 3**  
   Note Railway-only features in use: cron schedules, volumes, private networking, templates.

5. **Deploy on Ample in parallel**  
   Run `next build` then `next start -H 0.0.0.0 -p $PORT` on the node-22 template. Pass the exported variables with --env; keep the source running.
   ```
   ample deploy . --name  --public --env-file .env.production
   ```

6. **Validate before cutover**  
   Run the app's own checks and, for data, compare counts and checksums; the example checks are the pattern self-tests (/p/configuration-secrets, /p/relational-records).

7. **Cut over**  
   Add the custom domain with `ample domain add`, update DNS from the Railway target, keep the Railway service until verified, then remove it.

8. **Rollback**  
   Point DNS or configuration back to the source. The source was never modified; deletion is a separate step after validation.

## Success Checks
- **destination app responds on its public URL**  
  Expected: `ample canary next js patterns`.
- **configuration-secrets check**  
  Expected: see the pattern fixture checks from the destination example.
- **relational-records check**  
  Expected: see the pattern fixture checks from the destination example.
- **data or object counts and checksums match the source**  
  Expected: manual comparison before cutover.

## Limitations
- Documentation only: nothing is executed automatically and no execution binding is offered. 
- The source-side procedure is documented from Railway app's standard tooling and was not executed in this catalog's evidence.
- No full source-product parity is claimed: Railway cron schedules, volumes and private networking are not migrated.

## Cost Estimate
- **Currency**: USD
- **Monthly Amount**: 10.0
- **Components**:
  - App server: size `s-1vcpu-1gb`, quantity 1.0, monthly amount 5.0.
  - Managed PostgreSQL database: size `s-1vcpu-1gb`, quantity 1.0, monthly amount 5.0.
- **Note**: Destination always-on monthly price of the tested sizes; apps auto-pause when idle.

## Examples
- **Next.js pattern fixture (destination)**  
  Verified destination basis: Next.js compute. 
  Source Reference: `tests/deploy-canaries/next-js-patterns`.

## Evidence Summary
- **Canary Run**:  
  Destination side verified: the Next.js pattern fixture deployed on Ample and its checks passed.

## Last Verified At
  2026-09-21T02:34:39Z.