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 which can be downloaded here .
Unzip MongoDB in the folder of your choice. I will be using "C:\Program Files\MongoDB\Server\4.2\bin" for my own implementation. Completion of the proceeding steps to setup the user-managed 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
- 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"
- Next, start up the MongoDB service:
mongod --dbpath "C:\Program Files\MongoDB\Server\4.2\data"
- 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
- Open a new Windows Command Prompt as Administrator. I will refer to this window as the Client window from now on. In this window, change change into your MongoDB bin directory:
cd "C:\Program Files\MongoDB\Server\4.2\bin"
- Connect into the newly created database:
mongo localhost:27017
- 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
- 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 MongoDB documentation here . 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:
db.shutdownServer()
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:
exit
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
The databases we need to create are "AlteryxService" and "AlteryxGallery". If you are using Server 2022.3 or an older version, then in addition you will also have to create the "AlteryxGallery_Lucene" database. 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'}]})
Only for Server 2022.3 or an older version:
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, exit the MongoDB on the client:
exit
Feel free to close this Command Prompt as well.
Set up Windows Service and configuration file for MongoDB
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:
systemLog: destination: file path: C:\Program Files\MongoDB\Server\4.2\log\mongod.log storage: dbPath: C:\Program Files\MongoDB\Server\4.2\data net: port: 27017 security: authorization: enabled
For more information on the parameters you can set in this file, see the MongoDB documentation here. Save the file in the "bin" folder in the MongoDB directory you set up and name it "mongod.cfg". In the Command Prompt, run one of the following commands (depending on if you your instance will be TLS-enabled) making any modifications to the folder you installed MongoDB as well as the mongod.cfg file:
For non-TLS:
"C:\Program Files\MongoDB\Server\4.2\bin\mongod.exe" --config "C:\Program Files\MongoDB\Server\4.2\bin\mongod.cfg" --install
For TLS:
This command assumes the following about your mongo instance:
- Mongo instance is Windows-based
- The mongod.cfg from the section "" the has already been configured
- Your certificate meets the pre-requisites for Mongo TLS
- The certificate chain has been added properly to the Windows Certificate Store
mongod --config "\mongo\install\path\mongod.cfg" --tlsCertificateSelector subject=mongdb.extendthereach.com --setParameter tlsUseSystemCA=true -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:
- Create the admin database
- Create a user administrator
- Authenticate the user administrator account
The details for these steps are covered in the Set up the MongoDB database section above.