Setting Up a MedusaJS Project with Coolify

Medusa is a modern open-source e-commerce framework that helps developers create complex and customized online stores. With its modular architecture and a wide range of built-in features, MedusaJS enables rapid development and easy scaling of e-commerce projects.

Coolify is an open-source self-hosting platform that simplifies hosting and managing applications. Coolify allows developers to host their projects on their own servers without dealing with the setup and management of infrastructure.

Combining MedusaJS and Coolify facilitates efficient development, deployment, and management of e-commerce projects. In this blog post, I present a step-by-step guide to setting up a MedusaJS project with Coolify.

Prerequisites

Before we begin, ensure the following prerequisites are met to follow this tutorial:

• Basic knowledge of web development and JavaScript/TypeScript.
• A server with Coolify already installed. If Coolify is not installed yet, you can find the installation guide on the official website.
• A GitHub account.

Optional but helpful:

• Prior experience with MedusaJS and/or Coolify.
• An existing Medusa project.

Preparation (Optional)

Before setting up MedusaJS, we need to install and configure the required databases since the database credentials will be needed during the setup.

On Windows with WSL:

1. Install WSL and a Linux distribution of your choice from the Microsoft Store.
2. Open the Linux distribution and install Postgres and Redis using your distribution's package manager.
3. Start the services and note down the PostgreSQL credentials.

On Linux:

1. Install Postgres and Redis using your distribution's package manager.
2. Start the services and note down the PostgreSQL credentials.

Installing and Setting Up MedusaJS

Note: If you already have a Medusa project, you can skip this step.

We will now create a new Medusa project. Ensure Node.js and Yarn are installed on your computer, and then run the following commands to create a new Medusa project and navigate to the project directory:

pnpm dlx create-medusa-app@latest

cd my-medusa-project

If the installation is successful, your .env file should look like this:

DATABASE_TYPE=postgres
DATABASE_URL=postgres://postgres:yourpassword@localhost/medusa-5n1w
MEDUSA_ADMIN_ONBOARDING_TYPE=default
STORE_CORS=http://localhost:8000,http://localhost:7001

If you encounter a database error with create-medusa-app (e.g., incorrect Postgres credentials), you can use the --skip-db option to set up the database after creating the Medusa server. When using the --skip-db option, you must manually provide the database credentials in the .env file.

Modifications to medusa-config.ts

In the medusa-config.js file, we need to make some configuration changes. Uncomment the eventBus and cacheService within the modules object:

const modules = {
   eventBus: {
      resolve: "@medusajs/event-bus-redis",
      options: {
         redisUrl: REDIS_URL
      }
   },
   cacheService: {
      resolve: "@medusajs/cache-redis",
      options: {
         redisUrl: REDIS_URL
      }
   },
};

Redis is a prerequisite for production deployments! Enable Redis in line 80:

const projectConfig = {
  jwtSecret: process.env.JWT_SECRET,
  cookieSecret: process.env.COOKIE_SECRET,
  store_cors: STORE_CORS,
  database_url: DATABASE_URL,
  admin_cors: ADMIN_CORS,
  // Uncomment the following lines to enable REDIS
  redis_url: REDIS_URL // <-- Uncomment this line
};

With the necessary configuration changes complete, we can proceed to test the Medusa server locally.

Local Testing

Once the databases and the Medusa server are set up, you can test the Medusa project locally. Ensure all configurations in the medusa-config.js file are correct, and start the Medusa server using one of the following commands:

yarn start
# or
medusa develop

Now visit the Admin Panel at http://localhost:9000/app (when using yarn start) or http://localhost:7001 (when using medusa develop). You can also test the product endpoint of the server to ensure you receive a response: http://localhost:9000/store/products

Upload Project to GitHub

After creating your Medusa project, the next step is to push it to GitHub. Depending on your development environment or tools, the process for uploading the project to GitHub may vary. Regardless of the method, you should have a new GitHub repository with your Medusa project by the end.

Setting Up Coolify Services

Coolify provides a convenient way to self-host and create all the services required for a Medusa server, including Postgres, Redis, Meilisearch, and more. In this section, we will set up the databases needed for our Medusa project on Coolify.

Create Databases

1. Log in to your Coolify server.
2. Navigate to "Create new resource" and select "Databases."
3. Choose "Postgresql" from the list of available database types. Follow the instructions and then start the database.
4. Repeat the same process for Redis by selecting "Redis" from the list of available database types.

The databases are now ready and running, and we can proceed to set up our Medusa project on Coolify.

Setting Up the Medusa Server on Coolify

With the necessary databases set up and running, we can now set up the Medusa server on Coolify.

Create Application

1. Navigate to "Create new resource" and select "Application."
2. For "Integrated with Git App," select the account where the Medusa project is pushed.
3. Choose the appropriate repository and branch, then click "Save."
4. In the next step, select the Build Pack. Since Medusa runs on Node.js, choose "Node.js" from the list of available Build Packs.

Configuration

1. Provide an FQDN URL where the server will be accessible, e.g., medusa.yourdomain.dev (ensure proper DNS records are set).
2. Enable the toggle "Generate SSL for www and non-www?"
3. In the "Configurations" section:
   • Enter the build and install commands.
   • Set the Node version in "Deployment Image" to the desired version if necessary.
   • Click "Save" at the top to save the configuration.

Add Secrets

1. Navigate to "Secrets" in the left sidebar.
2. Add the .env variables: For REDIS_URL and DATABASE_URL, copy and paste the connection strings from the databases you started earlier.

Note: If you encounter issues connecting Redis to the Medusa server, you may need to add a colon in the connection string. For example, redis://BCDK9... should be changed to redis://:BCDK9....

Deployment

To deploy the Medusa server, follow these steps:

1. Navigate to "Build" in the left sidebar and enable the "Enable debug logs" checkbox.
2. Click "Deploy" in the top-right corner and monitor the deployment process.

If no build issues occur during the deployment process, the deployment is successful, and the server will be accessible at the specified FQDN URL.

Summary and Conclusion

In this tutorial, we walked through the process of setting up a MedusaJS project with Coolify step by step. We discussed the prerequisites, prepared the databases, set up and tested the Medusa project locally, and finally deployed the project on Coolify.

By leveraging Coolify, developers can take advantage of a self-hosted system while reducing the complexity of infrastructure management. MedusaJS and Coolify together form a powerful and flexible solution for developing, deploying, and managing e-commerce projects.

Congratulations! You now have a running MedusaJS project hosted with Coolify. With the knowledge gained, you can start developing and optimizing your own online store. The possibilities are endless, and there is much more to discover and learn in the world of MedusaJS and Coolify.

Good luck with your new MedusaJS project!