Skip to main content

MongoDB Setup

Cyrus Panel requires a MongoDB connection URI to store user accounts, server definitions, node allocations, vouchers, and billing records.

MongoDB Atlas is the easiest and most reliable method. It provides a permanently free managed cloud cluster (M0 Free Tier) that includes automated backups and requires zero server maintenance.

Step 1: Create an Account & Deploy a Free Cluster​

  1. Go to MongoDB Atlas and sign up or log in.
  2. In your dashboard, click "Build a Database" (or "Create").
  3. Under the plan options, select the M0 Free (Shared) tier.
  4. Choose a Cloud Provider (AWS, Google Cloud, or Azure) and select the Region geographically closest to your panel server.
  5. Leave the cluster name as Cluster0 (or name it as you prefer) and click "Create Deployment" (or "Create Cluster").

Step 2: Create a Database User​

  1. In the left navigation sidebar under Security, click Database & Network Access.
  2. Click the "Add New Database User" button.
  3. Select Password as the authentication method.
  4. Enter a Username (e.g. cyrus).
  5. Enter a strong password or click "Autogenerate Secure Password".
  6. Under Database User Privileges, ensure it is set to "Read and write to any database" (or Atlas Admin on M0).
  7. Click "Add User" and save your password in a safe place.

Step 3: Configure Network Access (IP Whitelist)​

Atlas blocks all inbound traffic by default until you configure network permissions:

  1. In the left navigation sidebar under Security, click Database & Network Access.
  2. Select IP Access List under Network Access in the navigation sidebar.
  3. Click the green "Add IP Address" button.
  4. Type one of the following in the Access List Entry Input box:
    • Allow Access from Anywhere (0.0.0.0/0): Recommended if your server has a dynamic IP or you connect from multiple locations.
    • Your Panel Server's IP: Enter your host server's static public IPv4 address for maximum security.
  5. Click "Confirm". It will take a few seconds to apply.

Step 4: Get Your Connection String​

  1. In the left sidebar under Database, click Clusters.
  2. On your cluster card, click the "Connect" button.
  3. In the modal, select "Drivers" under Connect your application.
  4. Ensure the driver is set to Node.js.
  5. Copy the provided connection string (starts with mongodb+srv://):
mongodb+srv://<username>:<password>@cluster0.xxxxxxx.mongodb.net/?retryWrites=true&w=majority
Auto-Generated or Default Username

MongoDB Atlas may automatically pre-fill the username in the connection string with an auto-created user or the first database user it detects (for example, testuser_db_user). Ensure you replace it with the actual user you created in Step 2 (e.g. cyrus).

Step 5: Format the URI for Cyrus Panel​

  1. Replace <username> (or any prefilled username like testuser_db_user) with your database username (e.g. cyrus).
  2. Replace <password> with your user's actual password.
  3. Add /cyrus right before the ? query parameters to set the database name:
mongodb+srv://cyrus:YOUR_SECURE_PASSWORD@cluster0.xxxxxxx.mongodb.net/cyrus?retryWrites=true&w=majority
Special Characters in Passwords

If your password contains special characters (such as @, :, /, ?, #, [, ]), they must be URL-encoded. For example, @ becomes %40 and # becomes %23. Alternatively, use an alphanumeric password.

Paste this final string into the Cyrus Panel CLI Setup Wizard or into your .env under MONGO_URI.

Option 2: Docker Container (Local Self-Hosted)​

If you prefer keeping the database on your own host without cloud services, running MongoDB inside a Docker container is the fastest self-hosted method.

Run the following command to start an isolated MongoDB container bound only to 127.0.0.1:

docker run -d \
  --name cyrus-mongodb \
  --restart unless-stopped \
  -p 127.0.0.1:46666:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=cyrus \
  -e MONGO_INITDB_ROOT_PASSWORD='your_secure_password' \
  -v cyrus-mongodb-data:/data/db \
  mongodb/mongodb-community-server:latest
Choose a Secure Password

Replace 'your_secure_password' with your own strong database password before executing the command.

Resulting Connection URI​

Based on the command above, your local MongoDB connection URI will be:

mongodb://cyrus:your_secure_password@127.0.0.1:46666/cyrus?authSource=admin
Automatic Connection Verification

When starting Cyrus Panel (npm run start), the interactive setup wizard will automatically test your MongoDB URI to verify that authentication and network access succeed before saving.