Calling all Racers for the Alteryx Grand Prix! It's time to rev your engines and race to the stage at Inspire! Sign up here.

Alteryx Server Knowledge Base

Definitive answers from Server experts.

How to Create a User-Managed MongoDB Instance


One of the three database options when setting up the Alteryx Server is to connect into a User-Managed MongoDB instance. Why would you want to set up your own implementation of MongoDB? The main benefits are to take advantage of the features of MongoDB that are not included with our embedded instance:

  • Replication - to provide data redundancy
  • Sharding - to distribute data over multiple servers

Please note that for user managed MongoDB mongoDB direct access is enabled by default. So every node needs direct access to the servers hosting the MongoDB.

Start up your own MongoDB instance

You will first need to download the software. In this example, we will use MongoDB version 4.2.23:

Unzip MongoDB in the folder of your choice. I will be using "C:\Program Files\MongoDB\Server\4.2\bin" for my own implementation. The installation of MongoDB will also create two new folders with these default directories:

C:\Program Files\MongoDB\Server\4.2\data - for the database
C:\Program Files\MongoDB\Server\4.2\log - for log files

After the installation, verify that the MongoDB service is up and running. You can confirm this by going to Task Manager > Details, and verifying that "mongod.exe" shows as "Running" in Status. If you have multiple MongoDB instances running on the same machine, you can verify that "mongod.exe" corresponds to the correct MongoDB installation directory by right-clicking on "mongod.exe", then select Properties > General and check that Location shows the correct directory.

Start MongoDB service if it is not running

  1. Open Windows Command Prompt as Administrator. I will refer to this window as the Daemon window from now on. Then, change into your MongoDB bin directory:
    cd "C:\Program Files\MongoDB\Server\4.2\bin"
  2. Next, start up the MongoDB service:
    mongod --dbpath "C:\Program Files\MongoDB\Server\4.2\data"
  3. Look for the following line, it should be at the end of the start up dialog:
    2017-01-31T09:02:04.472-0700 I NETWORK [initandlisten] waiting for connections on port 27017


Set up the MongoDB database

  1. Open a new Windows Command Prompt as Administrator. I will refer to this window as the Client window from now on. In this window, connect into the newly created database:
    mongo localhost:27017
  2. Now, create the admin database. The use command allows you to switch into another database; if a database with the name you provided does not exist, MongoDB will create it for you:
    use admin
  3. Once inside the Admin database, create the default MongoDB administrator and authenticate the account:
    db.createUser({user:"userAdmin", pwd:"password",roles:["root"]})

With the db.createUser() command we are creating the username we wish to use, the password for that user, and the database role for the account. For more information on the types of roles available to MongoDB, take a look at the following URL . The db.auth() command authenticates the username and password to the database, allowing that user to log in with the provided credentials.

We can now restart MongoDB to use our new authentication. First, let's stop the MongoDB service by entering the following in the Client window: 


Then, exit out of the database and shut it down (keep the Client window open as we will still need it). In the Client window, type the following:


If you don't already have the Daemon window open, open a new Windows Command Prompt as Administrator, which will be the Daemon window. In this window, restart the MongoDB service back up with the --auth parameter to enable authentication:

mongod --dbpath "C:\Program Files\MongoDB\Server\4.2\data" --auth

In the Client window, let's log in to the admin database with our credentials:

mongo localhost:27017/admin -u userAdmin -p password

There are three databases we need to create: "AlteryxService", "AlteryxGallery", and "AlteryxGallery_Lucene". We will create, add the same user account to each database, and authenticate the account. Run the below commands, one line at a time:

use AlteryxService
db.createUser({user:'user', pwd:'password', roles:[{role:'readWrite', db:'AlteryxService'}]})
use AlteryxGallery
db.createUser({user:'user', pwd:'password', roles:[{role:'readWrite', db:'AlteryxGallery'}]})
use AlteryxGallery_Lucene
db.createUser({user:'user', pwd:'password', roles:[{role:'readWrite', db:'AlteryxGallery_Lucene'}]})

Here is an example of what to expect when running these commands:

connecting to: localhost:27017/admin  > use AlteryxService switched to db AlteryxService > db.createUser({user:'user', pwd:'password', roles:[{role:'readWrite', db:'AlteryxService'}]}) Successfully added user: {
         "user" : "user",
         "roles" : [
                         "role" : "readWrite",
                         "db" : "AlteryxService"

After creating the databases and user accounts, close down the MongoDB client:


Feel free to close this Command Prompt as well.

Set up Windows Service and configuration file for MongoDB, if lacking

Verify if a Windows Service for MongoDB exists. Go to Task Manager > Services and look for a Service named "MongoDB". If the Windows Service is present and running, you can skip ahead to the next section Connect Alteryx Server to the User-Managed MongoDB. Else, proceed with the rest of this section.

Shut down the MongoDB daemon (Ctrl+C again - but keep this Command Prompt open) and create a Windows Service for MongoDB if there isn't one already. To do this, open a text document and add the following text. Modify any folder listings in your own document to match where you have MongoDB installed:

  destination: file
  path: C:\Program Files\MongoDB\Server\4.2\log\mongod.log
  dbPath: C:\Program Files\MongoDB\Server\4.2\data
  port: 27017

For more information on the parameters you can set in this file, please visit this link . Save the file in the "bin" folder in the MongoDB directory you set up and name it "mongod.cfg". In the Command Prompt, run the following command making any modifications to the folder you installed MongoDB and the mongod.cfg file:

"C:\Program Files\MongoDB\Server\4.2\bin\mongod.exe" --config "C:\Program Files\MongoDB\Server\4.2\bin\mongod.cfg" --install

Be sure to include the full path for both files. The Windows Services will not be able to find these files if you use relative paths. After entering the command, there will be a MongoDB entry in your Windows Services list. Open the Windows Services and start up MongoDB.


Connect Alteryx Server to the User-Managed MongoDB

Now we can connect the Alteryx Service into our new User-Managed MongoDB instance:

  • Open the System Settings Configuration and click Next to Controller > Persistence
  • Select User-managed MongoDB from the Database Type
  • Under Host, enter the server name and port you have MongoDB installed on. On default, MongoDB will user 27017 to communicate
  • Enter in the Username and Password created for the "AlteryxService" database

Click Next through the rest of the configuration and Finish to restart the service. When the Alteryx Service starts up, it will populate the database with the required collections.

Feel free to verify your Scheduler and Gallery instances are up and running. If you experience any problems, please contact Alteryx Support .

Common Issues

Alteryx Service does not start after configuring the MongoDB. When starting MongoDB in Command Prompt, it gives the warning: "Access control is not enabled for the database. Read and write access to data configuration is unrestricted."

Ensure the following has been completed:
  1. Create the admin database
  2. Create a user administrator
  3. Authenticate the user administrator account
The details for these steps are covered in the Set up the MongoDB database section above.


I had trouble using the instructions above to create the Windows service.

This command worked for me:

mongod --dbpath="C:\MongoDB\data" --logpath="C:\MongoDB\log\mongod.log" --install

9 - Comet

Hi @CristianoJ,


Thanks for that final line of code, it works fine and saved my day getting mongodb installed and running!




9 - Comet

If you are installing MongoDB in a different machine where you are running Alteryx Server, kindly note that you should include an extra line in the mongod.cfg file in order to tell MongoDB to accept external connections, MongoDB binds to localhost by default. Also use the command stated in the article to make sure MongoDB service is created pointing to the config file.


"C:\MongoDB\4.0\bin\mongod.exe" --config "C:\MongoDB\4.0\mongod.cfg" --install


I sorted this by adding the following command in the cfg file.


  destination: file
  path: C:\MongoDB\log\mongod.log
  dbPath: C:\MongoDB\data
bindIP: port: 27017




5 - Atom

Hello @MattH



Do you know if there's an official way to connect do Document DB (MongoDB compatible) with TLS ennabled?


In the Alteryx Gallery persistence/search connection string configuration, I'm writing the connection string provided from AWS, like the example ahed, but It's not working. 





I've already registered the certificates (the entire chain) in the Windows Server and got an successfull connection with Mongo Shell or the Mongo Client in Alteryx/bin folder.


Searching around google, I've read about Alteryx Server not supporting TLS connections (with certificate) for database providers, is it true?

8 - Asteroid

I am trying to setup the same but using MongoDB on an RPM-based Linux system on AWS. I have repeated the above steps but creating just a new database, and assigning user rights to it, but not adding an entry to it, is making it disappear.


Also, after finishing the setup, I am not able to start the Gallery URL.


Please advise on what step to take next and if it is feasible to use User Managed MongoDB instance from a Linux system


Hi @fardeen9983 , 


The steps in this article are meant for setting up a user-managed MongoDB in a Windows environment. They have not been validated in a Linux environment.


As I understand, it seems you did not follow through all of the above steps and therefore the setup was not successful. If any part of the above steps cannot be carried out in the Linux environment, I am afraid that is beyond the scope of this article.