This is a guide for deploying a Medusa project on DigitalOcean App Platform.
In this document, you'll learn how to deploy your Medusa server to a DigitalOcean App.
:::note
DigitalOcean is a reliable hosting provider that provides different ways to host websites and servers. One way to host a server is using their DigitalOcean App Platform.
It is assumed, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../../usage/create-medusa-app.mdx) for a small walkthrough.
## Prerequisites
:::
### Medusa Server
### 1. Configure Medusa
It is assumed that you already have a Medusa server installed locally. If you don’t, please follow our [quickstart guide](../../quickstart/quick-start.md).
Before jumping into DigitalOcean, your Medusa application needs to be configured.
Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Server documentation](../../usage/configurations.md) to learn how to do that.
#### Update `medusa-config.js`
### Needed Accounts
Instead of using a single environment variable for the database, `DATABASE_URL`, set `DB_*` variables and declare `DATABASE_URL` like so:
[Sign in](https://cloud.digitalocean.com/login) to your DigitalOcean Account or [create a new one](https://cloud.digitalocean.com/registrations/new).
### 3. Create an App
Navigate to the top-right dropdown **Create** and select **Apps**.
### 4. Connect you Git repository
Choose **GitHub** or **GitLab** and select the repository that holds your Medusa project. Check **Autodeploy code changes**, if you want DigitalOcean to deploy on every push to your repository.
- A [DigitalOcean](https://cloud.digitalocean.com/registrations/new) account. You need to provide a payment method on sign up.
- A [GitHub](https://github.com/) account to create a repository to host your server’s codebase.
:::tip
It's important, that DigitalOcean is pointing to the directory holding the Medusa store engine as it is only this which that will be deployed (If you followed the quickstart guide this will simply be the created project, and if you used the npx command this will be the backend folder inside of the newly created project).
If you want to use another Git Provider supported by DigitalOcean, it’s possible to follow along with this guide but you’ll have to perform the equivalent steps in your Git Provider.
:::
### 5. Configure environment variables
### Required Tools
The default settings for your app should be sufficient. We only need to change environment variables to hold the following:
- Git’s CLI tool. You can followthis documentation to learn how to install it for your operating system.
```shell=
## Create GitHub Repository
Before you can deploy your Medusa server 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.
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 server codebase and run the following commands:
```bash
git init
git remote add origin <GITHUB_URL>
```
Where `<GITHUB_URL>` 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 origin master
```
After pushing the changes, you can find the files in your GitHub repository.
## Deploy to DigitalOcean App
After logging into your account, click on the Create button at the top right, then choose App.
### Choose Repository
In the Create App page, choose GitHub from the Service Provider list.
If you haven’t given DigitalOcean access before, click on Manage Access under Source Code. You’ll then be redirected to GitHub to give DigitalOcean access.
Once DigitalOcean have access to your GitHub account, you should see a Repository input. Click on it and search for the repository you created earlier.
Additional inputs will show up to choose the Branch, Source Directory, and Autodeploy options.
If you host your Medusa server in a monorepo, you should change the Source Directory to the directory the server is available in the repository. Otherwise, it can be left as is.
Once you’re done, click Next to move on to the next step.
### Specify Web Service Resources
In the next step, you’ll see the resources to create.
If you have a Dockerfile available in the server’s codebase (which is available by default), you’ll have two resources showing. You can remove it by clicking on the trash icon at the right of the resource.
By default, DigitalOcean hosts the web service in a sub-path of the domain name of the created App. To change it to the root of the domain, click on the edit icon at the right of the Web Service resource.
Then, scroll to HTTP Request Routes and expand it by clicking on Edit at its right. Change the value of the Routes input to `/`.
Once you’re done click Save. You’ll be taken back to the Resources page.
### Specify Database Resources
On the same page, expand the Add Resources section, choose Database, then click Add.
In the new page, you’ll be shown a PostgreSQL database to be created. Notice that it’s important to choose a name that you’ll remember as you’ll need the name in next steps. You can leave the name as is if it’s not necessary to change it.
Once you’re done, click Create and Attach. You’ll be redirected back to the previous page with the database added to the resources.
Once you’re done, click Next to move on to the next step.
### Set Environment Variables
In this section, you’ll add environment variables that are essential to your Medusa server.
You should see 2 ways to add environment variables: Global or specific to the Web Service.
Click Edit on the second row to add environment variables specific to the Web Service. Add the following environment variables:
```bash
DB_USERNAME=${db.USERNAME}
DB_PASSWORD=${db.PASSWORD}
DB_HOST=${db.HOSTNAME}
DB_PORT=${db.PORT}
DB_DATABASE=${db.DATABASE}
REDIS_URL=${redis.DATABASE_URL}
JWT_SECRET=your-jwt-secret
COOKIE_SECRET=your-cookie-secret
JWT_SECRET=secret
COOKIE_SECRET=secret
NPM_CONFIG_PRODUCTION=false
NODE_ENV=production
```
:::tip
Notice how for database environment variables you access the values from the database you created earlier `db`. If you changed the name of the database, you must change `db` here to the name you supplied to the PostgreSQL database.
Make sure to use actual secrets in a production environment
Another thing to note here is that you added a `REDIS_URL` environment variable that uses a`redis` resource to retrieve the URL. You’ll be creating this resource in a later section.
:::caution
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
:::
### 6. Set up a Database
Once you’re done click Save.
Click **Add a Database**. If you named your database instance something different than `db`, make sure your environment variable reflect this. See our use of `db` below.
### Finalize App
```shell=
DB_USERNAME=${db.USERNAME}
In the next section, you’ll be shown the app info and the region it will be deployed to. You can leave it all as is or make changes if you find it necessary.
Once you’re done, click Next to go to the next step.
In the final step, you can see a review of everything you created. If everything looks good, scroll down and click Create Resource.
### Create Redis Resource
While the server is being deployed, you can create the Redis resource.
Click the Create button at the top right and choose Database from the dropdown.
In the new page under Choose a database engine, choose Redis.
Then, scroll down to the “Choose a name” input. Since you used the name `redis` in the `REDIS_URL` environment variables, change the value to `redis` here.
Once you’re done, click on Create Database Cluster.
### Attach Redis Database
Once the Redis database is created go back to the App you created earlier by choose Apps in the sidebar then clicking on the App name.
Click at the white Create button at the top right and choose Create/Attach Database.
In the new page, click on the Previously Created DigitalOcean Database radio button. Then, under Database Cluster select the Redis database you just created.
Once you’re done click Attach Database. This will add the Redis database to the list of resources of your App and will trigger a redeploy of the App.
## Test your Server
Once the redeployment is complete, copy the URL of the App which can be found under the App’s name.
Then, go to `<YOUR_APP_URL>/store/products`. If the deployment was successful, you should receive a JSON response.
## Run Commands on Your Server
To run commands on your server, you can access the console on the App’s page by choosing the Console tab. This opens a console in your browser where you can run commands on your server.
For example, you can run the following commands to create a new admin user:
```bash
npm install @medusajs/medusa-cli -g
medusa user --email <EMAIL> --password <PASSWORD>
```
### 7. Give your app a name
Make sure to replace `<EMAIL>` and `<PASSWORD>` with the credentials you want to give the user.
Enter a name for your app and select the most suitable region for your setup.
### 8. Finalize the setup
## Add Environment Variables
Choose a plan for your App. For just getting started, the Basic plan should be sufficient. For a production environment, the **Pro plan** is recommended.
You’ll likely need to add environment variables later such as Admin CORS and Store CORS variables.
Finally, launch the app.
To add environment variables, on the App’s page click on Settings and choose the Web Service component.
### 9. Add a Redis Database
The following steps will add a Redis database to your Medusa setup.
Then, scroll down and find Environment Variables. You can expand the environment variables by clicking Edit on the right. Here, you can edit, add, and remove environment variables.
1. Navigate to the top-right dropdown **Create** and select **Databases**
2. Select **Redis**
3. Select the same region you chose for your App
4. Leave VPC Network as it is
5. Choose a name for your Redis Database
Similarly to our other database, if you choose to name Redis something different than `redis`, you should udpdate the environment variable as well. See our use of `redis` below.
Once you click Save, the environment variables will be saved and a redeployment will be triggered.
```shell=
REDIS_URL=${redis.DATABASE_URL}
```
## What’s Next 🚀
6. Create the Redis database for your project
### 10. Configure Redis for your App
1. In the navbar on the left, click **Apps** and select your Medusa App
@@ -33,7 +33,7 @@ Furthermore, your Medusa server should be configured to work with PostgreSQL and
- Git’s CLI tool. You can follow[this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
- Heroku's CLI tool. You can follow [Heroku's documentation to learn how to install it for your operating system](https://devcenter.heroku.com/articles/heroku-cli).
## How to Deploy Your Medusa Server on Heroku
## Deploy to Heroku
### 1. Login to Heroku from your CLI
@@ -226,17 +226,41 @@ git push heroku HEAD:master
This triggers a redeploy of the Medusa server with all the new configurations.
## Troubleshooting: Inspect Build Logs
## Test your Server
To test your server, run the following command to retrieve the server's URL:
```bash
heroku apps:info -a <APP_NAME>
```
Where `<APP_NAME>` is the name of the app. You should see as the output a bunch of info of the app.
The server's URL is available under "Web URL". You can copy it and perform requests to it to test it out.
For example, you can send a request to `<YOUR_SERVER_URL>/store/products` and you should receive a JSON response with the products in your store.
### Troubleshooting: Inspect Build Logs
If an error occurs during the deployment, you can explore your Heroku app build logs using the following command in the root directory of your Medusa server:
```bash
heroku logs -n 500000 --remote heroku --tail
heroku logs -n 500000 --remote heroku --tail -a <APP_NAME>
```
## Create a User
Where `<APP_NAME>` is the name of the app.
As an optional extra step, you can create a user to use when your admin dashboard is up and running:
## Run Commands on Your Server
To run commands on your server, you can use the following command:
```bash
heroku run -a <APP_NAME> -- <COMMAND>
```
Where `<APP_NAME>` is the name of the app and `<COMMAND>` is the command you want to run.
For example, to create an admin user you can run the following command:
```bash
heroku run -a <APP_NAME> -- medusa user -e "<EMAIL>" -p "<PASSWORD>"
@@ -244,6 +268,18 @@ heroku run -a <APP_NAME> -- medusa user -e "<EMAIL>" -p "<PASSWORD>"
Where `<APP_NAME>` is the name of your Heroku app, and `<EMAIL>` and `<PASSWORD>` are the credentials you want to use to log in to the Medusa admin dashboard.
## Add Environment Variables
You’ll likely need to add environment variables later such as Admin CORS and Store CORS variables.
To set or change an environment variable's value, you can use the following command:
```bash
heroku config:set <ENV_NAME>=<ENV_VALUE> -a <APP_NAME>
```
Where `<APP_NAME>` is the name of your Heroku app, `<ENV_NAME>` is the name of the environment variable, and `<ENV_VALUE>` is the value.
## What's Next :rocket:
- Learn how to [deploy your Medusa admin](../admin/index.mdx).
You’ll be asked to either confirm the existing context or choose a new context.
After choosing your Medusa app in the context, you should be able to execute any command in the directory of your Medusa server. For example, you can run the [`user` command using Medusa’s CLI tool to create a new user](../../cli/reference.md#user).
After choosing your Medusa app in the context, you should be able to execute any command in the directory of your Medusa server. For example, you can run the [`user` command using Medusa’s CLI tool to create a new user](../../cli/reference.md#user):
Where `<YOUR_ADMIN_CORS>` is the URL of your admin dashboard.
:::tip
Make sure that the URL is without a backslash at the end. For example, you should use `http://localhost:7000` instead of `http://localhost:7000/`.
:::
## Storefront CORS
Medusa uses CORS to only allow specific origins to access the server. To make sure your Storefront dashboard can access the Medusa server, set this configuration:
@@ -279,6 +285,12 @@ STORE_CORS=<YOUR_STORE_CORS>
Where `<YOUR_STORE_CORS>` is the URL of your storefront.
:::tip
Make sure that the URL is without a backslash at the end. For example, you should use `http://localhost:8000` instead of `http://localhost:8000/`.
:::
## Plugins
On your Medusa server, you can use Plugins to add custom features or integrate third-party services. For example, installing a plugin to use Stripe as a payment provider.
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Shahed Nasser
GitHub