# Nodes

Nodes are optional and only required in the case that the application that you want to deploy should run on different servers but be managed from a certain master. By default a master is itself a node as well where applications can be deployed to.

Nodes must be initialized on the corresponding machines (or on the same machine using non-default ports; the default port is 7701). The command is similar to the one used to initialize the master. Pass (for example) --port=7702 to change the default port to some other value to avoid conflicts. Running multiple BDeploy nodes on the same machine is supported for testing, but not recommended for productive setups (as the master can be deployed to directly anyway - no need for an explicit node).

bdeploy init --root=</path/to/root> --hostname=<hostname> --nodeIdentFile=node-ident.txt --port=7702 --mode=node

Note the --nodeIdentFile parameter given to the init command: this file is created during init, and will contain the required access information for this node. You need it to register the node with the master, so make sure you will have it available when doing so.

After the initialization - which only has to be done once - the node can be started with the following command:

bdeploy start --root=</path/to/root>

To register, remove or manage a node on the master you can either use the command line interface or the administrative web UI on the master.

Use the CLI to register, remove and manage a node on the master (see the bdeploy remote-node --help command for more information).

bdeploy remote-node --remote=https://<hostname>:7701/api --tokenFile=master-token.txt --add=<node-name> --nodeIdentFile=node-ident.txt

The node is now registered as 'node-name'. This is the name which is reported when querying nodes from the master. This is also the name displayed when configuring applications to run on certain nodes later on.

The administrative Web UI provides the ability to add, remove, repair, and otherwise manage nodes.

To add a new node, click the Add Node... button. In the resulting panel you can drag and drop the node-ident.txt file created during the initialization step. This will prefill the panel with the required information. You can change node-name and URI according to your needs before saving.

When editing an existing node by selecting it in the list, you can also drop the same node-ident.txt file to update the information. This way you can create nodes before they actually exist - using a dummy URI and authentication - and later on update the node administration with the actual configuration. This allows to configure instances to their future nodes without them existing yet.

BDeploy supports replacing and restoring nodes. This is primarily meant to restore nodes after a catastrophic failure of the node in question. This feature is capable of reinstalling all required node configurations of all instances which are/were deployed on the node.

Replacing can be performed via the Administrative Web UI, much the same as editing a node. The steps to replace a node are:

1. Find the node in the Administrative Web UI and click it to open the node details panel.
2. In the panel, click [ Replace... ]. This will bring up the Replace Node panel.
3. Initialize the new node on the target system. This can be done at any time up until now in preparation.
4. Drag & drop the node-ident.txt file to the drop zone in the Replace Node panel. The URI and authentication information will be prefilled.
5. Click the [ Save ] button. The panel will enter loading state. You can follow the progress of the operation in the Activities panel from the main menu.
6. Once the operation completes, you will be brought back to the node details panel.
7. Replacing and restoring has been performed and all instances which use this node are available again.

Existing STANDALONE and MANAGED servers can be migrated to type NODE. This can be handy if software needs to run standalone on a NODE before the actual master server is available. In this case, setup a STANDALONE server on the node, configure all the required software, and migrate the server to NODE type later.

To convert an existing server:

1. Open the Administrative Web UI on both servers in separate browser tabs.
2. On the new master server, click [ Add Node... ] in the toolbar to bring up the Add Node panel.
3. On the to-be-migrated server, click the master node in the list of nodes. Click the [ Convert to Node... ] button.
4. Now drag the yellow node identification card from the to-be-migrated server to the new masters drop zone.
5. Information about the server is pre-filled in the form. Double check the information and press [ Save ] to start the migration.
6. You will be prompted to confirm the migration. Click [ Migrate ] to continue.

After the migration is complete, the server will be available as a NODE on the new master server. All the Instances have been migrated to the new master server.