Setup

You can either continue using your Modelence project as it is, or connect it to Modelence Cloud.

We’ve built Modelence Cloud to seamlessly host and monitor Modelence applications, and it’s designed for both scalable production apps as well as local development environments. By connecting your local project, you can use a free remote MongoDB database without having to set up your own, and you will also get access to logs, metrics and performance insights of your locally running application.

If you want to skip this for now, feel free to ignore the “Connecting to Modelence Cloud” section below and continue with the MongoDB setup section.

Connecting to Modelence Cloud

1. Create a Modelence Account

   First, you need to create a free Modelence account by going to Modelence Cloud.

2. Create an Application

   After you’ve logged in, create a new application and name it after your project.

3. Create an Environment

   After you’ve created an application, create a new environment. There are 2 types of environments: cloud and local. The cloud environment will provision and deploy your application to Modelence Cloud servers, while the local environment will only provision a remote MongoDB database for your local development.

   You can also connect to an external MongoDB database instead of using Modelence’s provisioned database. See the “Setting up MongoDB” section below for more details.

4. Connect Your Project

   After you’ve created a new environment, open its Settings page and click on Setup Local Environment button.

   It will open a modal with 2 steps. The first step creates a project (it’s optional) by running the following command.

   npx create-modelence-app@latest testenv --template ai-chat
   

   The second command should be executed in the project directory and it connects the project to Modelence Cloud. Here is how the command looks like:

   npx modelence@latest setup --token <token>
   

   It will automatically create a .modelence.env file with the necessary environment variables.

5. Starting The Development Server

   Run the following command in the project directory npm run dev to start the development server.

   Now, if everything is set up correctly, you should see your environment status go from inactive to active in the Modelence Cloud dashboard.

Deploy to Modelence Cloud

To deploy your Modelence application to the cloud, follow these steps:

1. Create a Cloud Environment

   In your Modelence Cloud dashboard, navigate to your application and create a new environment. This time, select cloud as the environment type instead of local. Cloud environments will provision infrastructure and deploy your application to Modelence Cloud servers.

2. Open Environment Settings

   After creating the cloud environment, navigate to its Settings page. You’ll find deployment configuration and commands here.

3. (Optional) Create a New Project

   If you don’t have an existing project, you can create one using the command from Step 1 in the settings modal:

   npx create-modelence-app@latest my-app --template ai-chat
   

   Replace my-app with your preferred project name and choose the template that fits your needs.

4. Deploy Your Project

   Copy the deployment command from Step 2 in the settings page. The command will look like this:

   npx modelence@latest deploy --app <app-name> --env <env-name>
   

   Run this command in your project directory to deploy your application to Modelence Cloud. The deployment process will:

   • Build your application
   • Upload it to Modelence Cloud
   • Provision necessary resources (MongoDB database, server infrastructure)
   • Start your application

   Once deployment completes, your environment status will change to active and you’ll receive a URL to access your deployed application.

Cloud deployments include automatic scaling, monitoring, and a production-ready MongoDB database. You can view logs, metrics, and manage your deployment from the Modelence Cloud dashboard.

Setting up MongoDB

If you’ve connected your local project to Modelence Cloud, as described in the section above, no more setup is needed - you are automatically set up with a MongoDB database that is included with your remote environment and can skip this section.

If you skipped the Modelence Cloud setup, the easiest way to set up MongoDB is to use the MongoDB Atlas free tier. While you can set up your own local MongoDB instance, we recommend Atlas because it eliminates the need for local installation and provides cloud storage for your development data, protecting it from local environment issues or data loss.

Setting up MongoDB with Atlas

Create an Atlas Account

• Go to MongoDB Atlas
• Sign up for a new account or log in if you already have one

For more detailed instructions, you can refer to the MongoDB Atlas documentation

Create a Free Cluster

• Click “Build a Database”
• Choose the “FREE” tier (labeled as “Shared” or “M0”)
• Select your preferred cloud provider and region
• Click “Create” to deploy your cluster (this may take a few minutes)

Set up Database Access

• In the Security Quickstart page, select “Username and Password” authentication
• Enter a username in the first text field
• For the password, either:
  • Enter your own secure password, or
  • Click “Autogenerate Secure Password” to let Atlas create one
• Click “Create User”

For more detailed instructions, you can refer to the MongoDB user setup guide

Configure Network Access

• In the Security Quickstart page, select “My Local Environment”
• In the “Add entries to your IP Access List” section, you can either:
  • Click “Add My Current IP Address” to add your current IP
  • For development, click “Allow Access from Anywhere” (0.0.0.0/0)
• Click “Finish and Close”

For more detailed instructions, you can refer to the MongoDB network access guide

Get Your Connection String

• Return to the “Database” page
• Click “Connect” on your cluster
• Select “Drivers” under “Connect Your Application”
• Choose the latest Node.js version and copy the connection string
• Replace the <username> and <password> in the string with your database user’s username and password
• Add your desired database name to the connection string (otherwise it will default to test), so it looks like this:

mongodb+srv://<username>:<password>@<cluster_name>.mongodb.net/<database-name>?retryWrites=true&w=majority

For more detailed instructions, you can refer to the MongoDB connection string guide

Do not load sample data into your newly created database if prompted - Modelence already provisions what you need and will work perfectly with an empty database on the first run.

Configure Environment Variables

Without the Modelence Cloud setup, you need to manually add your database configuration. Once you have your connection string, you’ll need to add it to your Modelence environment variables. Create a .modelence.env file in your project root (if it doesn’t exist already) and add:

MONGODB_URI="<your_connection_string_here>"

Make sure that your .modelence.env file is added to your .gitignore to keep your credentials secure.

Next Steps

Todo App Tutorial

Check out an example Todo app