Database Manual / Self-Managed Deployments / Deploy and Manage Self-Managed Replica Sets / Deploy

Convert a Standalone Self-Managed mongod to a Replica Set

A standalone mongod instance is useful for testing and development. A standalone instance isn't a good choice for a production deployment because it can be a single point of failure. A replica set, also known as a cluster, provides redundancy and availability. Always use a replica set in production.

If you have a standalone server with data that you want to use in production, convert the standalone server to a replica set first.

Important

If you convert a development server to a replica set for production use, consult the security checklist before you expose your cluster to the internet.

You can easily migrate from a standalone server to a MongoDB Atlas cluster. MongoDB Atlas is the fully managed service for MongoDB deployments in the cloud. To learn more, see Migrate or Import Data in the MongoDB Atlas documentation.

About This Task

Server Architecture

This tutorial uses the following servers:

HostnamePortDescription

mongodb0.example.net

27017

A running standalone MongoDB Server with data.

mongodb1.example.net

27017

A new MongoDB Server to join the replica set.

mongodb2.example.net

27017

A new MongoDB Server to join the replica set.

Before You Begin

Cluster Type

Before you convert your standalone instance, consider whether a replica set or a sharded cluster is more appropriate for your workload.

A sharded cluster is a special kind of cluster. A sharded cluster provides redundancy and availability; it also distributes data across shards. Shards are usually hosted on multiple servers and allow for horizontal scaling.

Authorization

To use authorization with a replica set, you must also configure replica set members to use X.509 certificates or keyfiles to perform internal authentication.

For more information, see:

Procedure

1

Shut down the standalone instance.

Use mongosh to connect to your existing mongod instance:

mongosh "mongodb://mongodb0.example.net:27017"

Switch to the admin database and run shutdown.

use admin
db.adminCommand(
   {
      shutdown: 1,
      comment: "Convert to cluster"
   }
)
2

Configure Replica Set Members

Update the configuration file on each server and to set the replSetName setting.

replication:
  replSetName: "rs0"
3

Configure Member Authentication

Configure member authentication for each server in the replica set.

Configure the replica set to use X.509 certificates for internal member authentication.

SettingOptionDescription

net.tls.mode

--tlsMode

Sets the TLS mode to use in authentication. To configure the server to require X.509 certificate authentication, set this option to requireTLS.

net.tls.certificateKeyFile

--tlsCertificateKeyFile

Sets the path to the .pem file that contains the TLS certificate for client connections.

net.tls.CAFile

--tlsCAFile

Sets the path to the file that contains the root certificate chain for the Certificate Authority (CA).

net.tls.clusterFile

--tlsClusterFile

Sets the path to the .pem file that contains the TLS certificate for cluster member connections.

security.clusterAuthMode

--clusterAuthMode

Sets the mode used to authenticate cluster members. To use X.509 authentication, set this option to x509.

For example:

replication:
  replSetName: "rs0"
security:
  clusterAuthMode: x509
net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/mongodb/client.pem
    CAFile: /etc/mongodb/ca.pem
    clusterFile: /etc/mongodb/member.pem

Configure the replica set to use keyfiles for internal member authentication. To authenticate, each member must have a copy of the same keyfile.

SettingOptionDescription

security.keyFile

--keyFile

Sets the path to the replica set keyfile.

For example:

replication:
   replSetName: "rs0"
security:
    keyFile: /etc/mongodb/keyfile

Configures a replica set without authorization.

Warning

You should only use this configuration for internal replica sets that are not accessible through the network.

SettingOptionDescription

net.bindIp

--bind_ip

Sets the hostnames or IP addresses that MongoDB listens on for client connections. To block network access to the server, set this option to localhost.

For example:

replication:
  replSetName: "rs0"
net:
   bindIp: localhost
4

Start MongoDB

Start mongod for each member.

5

Initialize the replica set.

To initialize the replica set, use mongosh to reconnect to your server instance.

mongosh "mongodb://mongodb0.example.net:27017"

Then, run the rs.initiate() method:

rs.initiate()

You only have to initiate the replica set once.

To view the replica set configuration, use rs.conf().

To check the status of the replica set, use rs.status().

6

Add nodes to the replica set.

The new replica set has a single, primary node. The next step is to add new nodes to the replica set. Review the documentation on clusters before you add additional nodes:

To add nodes, run the rs.add() method:

rs.add("mongodb1.example.net:27017")
rs.add("mongodb2.example.net:27017")
7

Check replication status.

To check that the replica set is correctly configured, run the rs.status() method and check that the new members are listed in the members field:

rs.status()
8

Update Your Application Connection String.

After you convert the standalone server to a replica set, update the connection string used by your applications to the connection string for your replica set:

  • mongodb0.example.net:27017
  • mongodb1.example.net:27017
  • mongodb2.example.net:27017
mongodb://mongodb0.example.net:27017,mongodb1.example.net:27017,mongodb2.example.net:27017

Then, restart your applications.

Learn More