Running a Cluster in Single-Server Mode

2 minute read

Several rarely-used CloudBees CD operations are not supported in clustered mode. For any these operations, you must restart the server in single-server mode:

  • Changing the database configuration This operation can be done in the web UI using Administration > Database Configuration or with ectool. After performing this operation, you must rerun ZKConfigTool to upload the changed configuration from the local database.properties file to ZooKeeper before switching back to clustered mode.

  • Doing a full import using ectool

  • Doing a full export using the safe mode with either of these options:

    • Restart

    • Shutdown

To run a CloudBees CD machine in single-server mode:

  1. Identify the machine you need to work on and shut down the other machines in the CloudBees CD cluster.

  2. Verify that the database.properties, keystore, passkey, and commander.properties configuration files on the machine you are working on are up to date and match those that were uploaded to ZooKeeper.

  3. Add:

    wrapper.java.additional.261=-DCOMMANDER_IGNORE_SERVER_MISMATCH=1

    to the wrapper.conf file of the machine that you are working on. Ensure that the number 261 is unique within the file. If not, change the number to a unique ID. This line prevents server mismatch errors after the switch from multi-node cluster mode to single-node standalone mode.

  4. Switch the remaining CloudBees CD machine to single-server mode by running the following command:

    ecconfigure --serverEnableClusteredMode=0

    The commanderAgent and commanderServer services restart.

  5. Complete your work on the CloudBees CD machine.

  6. If you changed the database configuration, use ZKConfigTool to upload the updated database.properties file to ZooKeeper.

  7. If you used the eccert tool (for added trusted agents, revoked certificates, and so on), use ZKConfigTool to upload the updated keystore file and/or the conf/security folder to ZooKeeper.

  8. If you updated the commander.properties file, use ZKConfigTool to upload it to ZooKeeper.

  9. Switch the remaining CloudBees CD machine back to clustered mode by entering:

    ecconfigure --serverEnableClusteredMode=1

  10. Restart the other nodes in the CloudBees CD cluster.