diff --git a/www/apps/docs/content/deployments/server/deploying-on-railway.md b/www/apps/docs/content/deployments/server/deploying-on-railway.mdx similarity index 50% rename from www/apps/docs/content/deployments/server/deploying-on-railway.md rename to www/apps/docs/content/deployments/server/deploying-on-railway.mdx index bd9b17c562..1f280d0e15 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-railway.md +++ b/www/apps/docs/content/deployments/server/deploying-on-railway.mdx @@ -3,6 +3,10 @@ description: 'Learn step-by-step.' addHowToData: true --- +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import MimeErrorTroubleshooting from "../../troubleshooting/mime-error.md" + # Deploy Your Medusa Backend to Railway In this document, you’ll learn how to deploy your Medusa backend to Railway. @@ -13,50 +17,23 @@ In this document, you’ll learn how to deploy your Medusa backend to Railway. Railway provides a free trial (no credit card required) that allows you to deploy your Medusa backend along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes. -:::note - -If you're deploying the admin plugin along with the backend, you'll need at least the Developer plan. The resources provided by the starter plan will cause memory errors. - -::: - -If you also don't have a Medusa project, you can deploy to Railway instantly with this button: - + href="https://railway.app/template/zC7eOq?referralCode=TW4Qi0" className="img-url no-zoom-img mb-2 inline-block"> Deploy with Railway ---- + -## Prerequisites +- [Medusa backend installed locally](../../create-medusa-app.mdx) +- Production modules installed on the Medusa backend, such as [Redis Event Module](../../development/events/modules/redis.md) and [Redis Cache Module](../../development/cache/modules/redis.md). +- A [Railway](https://railway.app/) account. If you're deploying the admin plugin along with the backend, you'll need at least the Developer plan. The resources provided by the starter plan lead to memory errors. +- [A GitHub repository for your Medusa backend](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository). -### Medusa Backend + -It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx). +## Configure the Admin -Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](./../../references/medusa_config/interfaces/medusa_config.ConfigModule.mdx) to learn how to do that. - -### Production Modules - -If you're using development modules for events and caching, it's highly recommended to install production modules instead. These can be: - -- [Redis Event Module](../../development/events/modules/redis.md) -- [Redis Cache Module](../../development/cache/modules/redis.md) - -### Needed Accounts - -- A [Railway](https://railway.app/) account. -- A [GitHub](https://github.com/) account to create a repository to host your backend's codebase. - -### Required Tools - -- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](./../../development/backend/prepare-environment.mdx#git). - ---- - -## (Optional) Step 0: Configure the Admin - -If you're using the Medusa Admin plugin, you have two options to deploy it: either with the backend or separately. +You have two options to deploy the Medusa Admin: either with the backend or separately. ### Deploying with the Backend @@ -104,7 +81,14 @@ const plugins = [ This ensures that the admin isn't built or served in production. You can also change `@medusajs/admin` dependency to be a dev dependency in `package.json`. -You can alternatively remove the admin plugin for the plugins array. +Also, change the `build` command to remove the command that builds the admin: + +```json +"scripts": { + // ... + "build": "cross-env npm run clean && npm run build:server", +} +``` :::tip @@ -114,23 +98,46 @@ Refer to the [admin deployment guides on how to deploy the admin separately](../ --- -## (Optional) Step 1: Add Nixpacks Configurations +## Add Railway Configuration File -If you've created your project using `create-medusa-app`, you might receive errors during the deployment process as Railway uses NPM by default. To avoid that, you need to configure Nixpacks to either use `yarn` or add the `--legacy-peer-deps` option to `npm install`. +To avoid errors during the installation process, it's recommended to use `yarn` for installing the dependencies. Alternatively, pass the `--legacy-peer-deps` option to the npm command. -In the root of your Medusa project, add the `nixpacks.toml` file with the following content: +Add in the root of your Medusa project the file `railway.toml` with the content based on the package manager of your choice: -```toml -[phases.setup] -nixPkgs = ['nodejs', 'yarn'] + + -[phases.install] -cmds=['yarn install'] -``` + ```toml + [build] + builder = "NIXPACKS" + + [build.nixpacksPlan.phases.setup] + nixPkgs = ["nodejs", "yarn"] + + [build.nixpacksPlan.phases.install] + cmds=["yarn install"] + ``` + + + + + ```toml + [build] + builder = "NIXPACKS" + + [build.nixpacksPlan.phases.setup] + nixPkgs = ["nodejs", "npm"] + + [build.nixpacksPlan.phases.install] + cmds=["npm install --legacy-peer-deps"] + ``` + + + --- -## Step 2: Add Worker Mode Configuration +## Add Worker Mode Configuration :::note @@ -152,88 +159,53 @@ This allows you to switch between modes for different deployed Medusa instances --- -## Step 3: Create GitHub Repository +## Push Changes to GitHub Repo -Before you deploy your Medusa backend you need to create a GitHub repository and push the code base to it. - -On GitHub, click the plus icon at the top right, then click New Repository. - -You’ll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository. - -### Push Code to GitHub Repository - -The next step is to push the code to the GitHub repository you just created. - -After creating the repository, you’ll be redirected to the repository’s page. On that page, you should see a URL that you can copy to connect your repository to a local directory. - -Copy the link. Then, open your terminal in the directory that holds your Medusa backend codebase and run the following commands: - -```bash -git init -git remote add origin -``` - -Where `` is the URL you just copied. - -Then, add, commit, and push the changes into the repository: - -```bash -git add . -git commit -m "initial commit" -git push -``` - -After pushing the changes, you can find the files in your GitHub repository. +Before proceeding further, push all changes you've made to your GitHub repository so that it's included in the deployment process. --- -## Step 4: Deploy to Railway - -In this section, you’ll create the PostgreSQL and Redis databases first, then deploy two instances of the Medusa backend: one having a `server` runtime mode, and another having a `worker` runtime mode. - -### Create the PostgreSQL Database +## Create Project + PostgreSQL Database On the Railway dashboard: -1. Click on the ”New Project**”** button. -2. Choose from the dropdown the ”Provision PostgreSQL” option. +1. Click on the ”New Project” button. +2. Choose from the list the ”Provision PostgreSQL” option. -A new database will be created and, after a few seconds, you will be redirected to the project page where you will see the newly-created database. +A new database will be created and, after a few seconds, you'll be redirected to the project page where you'll see the newly-created database. -### Create the Redis Database +--- + +## Create the Redis Database In the same project view: -1. Click on the New button. -2. Choose the Database option. -3. Choose Add Redis. +1. Click on the New button. +2. Choose the Database option. +3. Choose Add Redis. A new Redis database will be added to the project view in a few seconds. Click on it to open the database sidebar. -### Note about Modules +--- -If you use modules that require setting up other resources, make sure to add them at this point. This guide does not cover configurations specific to a module. +## Module Services and Variables -### Deploy Medusa in Server Mode +If you use modules that require setting up other services or environment variables, make sure to add them at this point. This guide doesn't cover configurations specific to a module. + +--- + +## Deploy Medusa in Server Mode In this section, you'll create a Medusa backend instance running in `server` runtime mode. In the same project view: -1. Click on the New button. -2. Choose the ”GitHub Repo” option. -3. If you still haven't given GitHub permissions to Railway, choose the ”Configure GitHub App” option to do that. +1. Click on the New button. +2. Choose the ”GitHub Repo” option. +3. If you still haven't given GitHub permissions to Railway, choose the ”Configure GitHub App” option to do that. 4. Choose the repository from the GitHub Repo dropdown. -:::tip - -If the GitHub repositories in the dropdown are stuck on loading and aren't showing, you might need to delete the project and start over. This only happens before you configure your account with GitHub. - -::: - -It will take the backend a few minutes for the deployment to finish. It may fail since you haven't added the environment variables yet. - -#### Configure Backend Environment Variables +### Configure Backend Environment Variables To configure the environment variables of your Medusa backend: @@ -247,7 +219,6 @@ JWT_SECRET=something COOKIE_SECRET=something DATABASE_URL=${{Postgres.DATABASE_URL}} REDIS_URL=${{Redis.REDIS_URL}} -DATABASE_TYPE=postgres MEDUSA_WORKER_MODE=server ``` @@ -255,39 +226,40 @@ Notice that the values of `DATABASE_URL` and `REDIS_URL` reference the values fr :::warning -It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`. +It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`. ::: Make sure to add any other environment variables that are relevant for you here. For example, you can add environment variables related to Medusa Admin or your modules. -#### Change Backend's Start Command +### Change Backend's Start Command -The start command is the command used to run the backend. You’ll change it to run any available migrations, then run the Medusa backend. This way if you create your own migrations or update the Medusa backend, it's guaranteed that these migrations are run first before the backend starts. +The start command is the command used to run the backend. You’ll change it to run any available migrations, then run the Medusa backend. This way if you create your own migrations or update the Medusa backend, it's guaranteed that these migrations run first before the backend starts. To change the start command of your Medusa backend: 1. Click on the GitHub repository’s card. 2. Click on the Settings tab and scroll down to the Deploy section. -3. Paste the following in the Start Command field: +3. Click on the Start Command button. +4. Paste the following in the shown input: ```bash medusa migrations run && medusa start ``` -### Deploy Medusa in Worker Mode +--- + +## Deploy Medusa in Worker Mode You'll now create another Medusa instance that'll be in `worker` runtime mode. In the same project view: -1. Click on the New button. -2. Choose the ”GitHub Repo” option. +1. Click on the New button. +2. Choose the ”GitHub Repo” option. 3. Choose the same repository from the GitHub Repo dropdown. -It will take the worker backend a few minutes for the deployment to finish. It may fail since you haven't added the environment variables yet. - -#### Configure Environment Variables for Worker Mode +### Configure Environment Variables for Worker Mode To configure the environment variables of the Medusa instance running in worker mode: @@ -301,7 +273,6 @@ JWT_SECRET=something COOKIE_SECRET=something DATABASE_URL=${{Postgres.DATABASE_URL}} REDIS_URL=${{Redis.REDIS_URL}} -DATABASE_TYPE=postgres MEDUSA_WORKER_MODE=worker ``` @@ -309,49 +280,60 @@ Notice that the values of `DATABASE_URL` and `REDIS_URL` reference the values fr :::warning -It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`. +It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`. ::: Make sure to add any other environment variables that are relevant for you here. -#### Change Worker's Start Command +### Change Worker's Start Command The start command is the command used to run the Medusa instance in worker mode. To set it: 1. Click on the worker’s card. 2. Click on the Settings tab and scroll down to the Deploy section. -3. Paste the following in the Start Command field: +3. Click on the Start Command button. +4. Paste the following in the shown input: ```bash medusa start ``` -### Add Domain Name +--- + +## Add Domain Name The last step is to add a domain name to your Medusa backend. To do that: -1. Click on the GitHub repository’s card. +1. Click on the Medusa server runtime's card. 2. Click on the Settings tab and scroll down to the Environment section. 3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain. --- -## Step 5: Test the Backend +## Deploy Changes -Every change you make to the settings redeploys the backend. You can check the Deployments of the backend by clicking on the GitHub repository’s card and choosing the Deployments tab. +At the top center of your project's dashboard page, there's a Deploy button that deploys all the changes you've made so far. -After the backend is redeployed successfully, open the app in your browser using the domain name. For example, you can open the URL `/store/products` which will return the products available on your backend. +Click on the button to trigger the deployment. The deployment will take a few minutes before it's ready. -:::tip +--- -If you generated a random domain, you can find it by clicking on the GitHub repository’s card → Deployment tab. +## Test the Backend -::: +Once the deployment is finished, you can access the Medusa backend on the custom domain/domain you've generated. + +For example, you can open the URL `/store/products` which returns the products available on your backend. + + + +Even if the deployment is successful, you might see a "Railway Not Found" error when accessing your URL. Give it a couple of minutes for the changes to actually take effect and try again. + + ### Health Route -You can access `/health` to get health status of your deployed backend. +Access `/health` to get health status of your deployed backend. ### Testing the Admin @@ -371,17 +353,21 @@ If you run into any issues or a problem with your deployed backend, you can chec This error may be thrown by a module that uses Redis. If you see it in your build or deploy logs, make sure that your Redis configurations are correct. +### Mime Error + + + --- -## Run Commands on the Backend +## Run Commands on the Deployed Services -To run commands on your backend, you can use [Railway’s CLI tool to run a local shell and execute commands](https://docs.railway.app/develop/cli#local-shell). +[Railway’s CLI tool](https://docs.railway.app/develop/cli#local-shell) allows you to run commands locally, but using environment variables from your projects. -For example, you can run commands on the backend to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.mdx). +For example, you can use it to run Medusa commands such as running migrations or creating a user, and it'll use the database environment variables from Railway to perform the action on the production database. ### Create Admin User -You can create an admin user by running the following command in the root of your Medusa project: +To create an admin user in your deployed backend, run the following command in the root of your Medusa project: ```bash railway run npx medusa user --email admin@medusa-test.com --password supersecret diff --git a/www/apps/docs/content/development/worker-mode/index.mdx b/www/apps/docs/content/development/worker-mode/index.mdx index 180a19db94..a3bc3eec5a 100644 --- a/www/apps/docs/content/development/worker-mode/index.mdx +++ b/www/apps/docs/content/development/worker-mode/index.mdx @@ -47,6 +47,6 @@ In this case, it's best to set the `worker_mode` configuration's value to an env :::tip -Check out the [Railway Deployment Guide](../../deployments/server/deploying-on-railway.md) as an example. +Check out the [Railway Deployment Guide](../../deployments/server/deploying-on-railway.mdx) as an example. ::: diff --git a/www/apps/docs/content/troubleshooting/mime-error.md b/www/apps/docs/content/troubleshooting/mime-error.md new file mode 100644 index 0000000000..4cc713f083 --- /dev/null +++ b/www/apps/docs/content/troubleshooting/mime-error.md @@ -0,0 +1,17 @@ +--- +title: "Mime Error" +--- + +The following error can occur when running the `build` command either locally or in an deployed Medusa backend: + +``` +Cannot find type definition file for 'mime' +``` + +This error typically occurs when using yarn v1 in an older Medusa setup. + +To resolve the error, install v1.3.5 of `@types/mime` as a development dependency in your Medusa backend: + +```bash npm2yarn +npm install @types/mime@1.3.5 --save-dev +``` diff --git a/www/apps/docs/sidebars.js b/www/apps/docs/sidebars.js index 611ab942c5..95fbe282a5 100644 --- a/www/apps/docs/sidebars.js +++ b/www/apps/docs/sidebars.js @@ -2181,6 +2181,11 @@ module.exports = { type: "category", label: "Medusa Backend", items: [ + { + type: "doc", + id: "troubleshooting/mime-error", + label: "Mime Error", + }, { type: "doc", id: "troubleshooting/eaddrinuse", diff --git a/www/apps/docs/src/theme/MDXComponents/index.tsx b/www/apps/docs/src/theme/MDXComponents/index.tsx index 36fc131388..f4377a0433 100644 --- a/www/apps/docs/src/theme/MDXComponents/index.tsx +++ b/www/apps/docs/src/theme/MDXComponents/index.tsx @@ -2,7 +2,7 @@ import MDXComponents from "@theme-original/MDXComponents" import CloudinaryImage from "@site/src/components/CloudinaryImage" import MDXA from "./A" -import { Kbd, DetailsSummary } from "docs-ui" +import { Kbd, DetailsSummary, Note } from "docs-ui" import H1 from "./H1" import MDXCode from "./Code" import MDXDetails from "./Details" @@ -22,6 +22,7 @@ const components = { h1: H1, DocCard, DocCardList, + Note, } export default components diff --git a/www/packages/docs-ui/src/components/Note/Layout/index.tsx b/www/packages/docs-ui/src/components/Note/Layout/index.tsx index 0914809083..594f937243 100644 --- a/www/packages/docs-ui/src/components/Note/Layout/index.tsx +++ b/www/packages/docs-ui/src/components/Note/Layout/index.tsx @@ -43,7 +43,7 @@ export const NoteLayout = ({ {title && (