Ctrl+K

Run and manage a node on macOS#

This guide describes how to run and manage a node on macOS. You can also run a node using Docker, Ubuntu, or Windows.

Prerequisites#

Note

Subscribe to the Mainnet status page or Testnet status page and the release information on Discourse to stay informed about updates and changes that may affect you as a node runner, including node software releases and protocol updates.

To subscribe to updates on the Mainnet/Testnet status page click Subscribe to get all updates or click Get updates to choose to get all updates or only updates for specific products.

Install/upgrade and run a node#

Note

Node version 4.5.0 introduced the GRPC V2 interface which is enabled by default on new installations. However on upgrading an existing node the configuration is not updated. To enable the new API environment variables CONCORDIUM_NODE_GRPC2_LISTEN_PORT CONCORDIUM_NODE_GRPC2_LISTEN_ADDRESS must be set in the node.plist settings files for the relevant network as documented below. The default ports set on a fresh install for mainnet and testnet are 20000 and 20001, respectively.

Example for Mainnet

<!-- Address of the GRPC V2 server. -->
<key>CONCORDIUM_NODE_GRPC2_LISTEN_ADDRESS</key>
<string>0.0.0.0</string>

<!-- Port of the GRPC V2 server. -->
<key>CONCORDIUM_NODE_GRPC2_LISTEN_PORT</key>
<string>20000</string>

Example for Testnet

<!-- Address of the GRPC V2 server. -->
<key>CONCORDIUM_NODE_GRPC2_LISTEN_ADDRESS</key>
<string>0.0.0.0</string>

<!-- Port of the GRPC V2 server. -->
<key>CONCORDIUM_NODE_GRPC2_LISTEN_PORT</key>
<string>20001</string>

Note

When upgrading, you can only upgrade one minor version at a time, or from the last release of major version X to major version X+1. You cannot skip versions. For patches, you can skip versions e.g. X.X.0 to X.X.3, or X.1.1 to X.2.3. To download previous node versions, see Previous node versions.

Mainnet

Note

See Change the node startup settings for information about how to change the service configuration settings. See Run a validator node on macOS for information about how to set the location of validator credentials.

  1. Go to Downloads, and download the latest macOS installer package (.pkg file).

  2. In the folder where you downloaded the .pkg file, double-click the .pkg file. The Install Concordium Node program opens.

  3. Click Allow to the message saying: This package will run a program to determine if the software can be installed. If you have a M1 based Mac, the installer might ask you to install Rosetta if you haven’t already. Click Install if that’s the case.

  4. If you already have a version of the node installed, click OK to the message saying Previous Installation Detected.

  5. Click Continue on the Introduction page.

  6. Click Continue on the License page, and then Agree to accept the license agreement.

  7. On the Configuration page you have the following options.

../../_images/Node-setup-mac-1.png

  • Run a [mainnet/testnet] node at start-up: When selected, the node runs when the system starts. Choose this option when you plan to use the node frequently and need it to be up-to-date at short notice. If you don’t select this option, you’ll have to start the node manually when required, for example, when you want to use the Desktop Wallet or Concordium Client. If you choose to start the node manually, it might take longer for the node to get up-to-date with the blockchain depending on when the node was last up-to-date.

  • Start the node after installation is complete: The node will automatically start running after the installation is complete. Do not choose this option if you want to make further configuration changes before starting the node.

  • Report to the network dashboard: Select this option if you want to publish your node statistics to the relevant dashboard when the node is running. Deselect this option if you don’t want your node displayed on the dashboard. If selected, you can view the statistics at the mainnet dashboard.

  • Public node name: Specify the name of your node as you want it to appear on the network dashboard if the node reports to the network dashboard. You must enter a name for at least one of the nodes.

  1. Once configured, click Continue to go to the Installation Type page.

  2. Click Install and enter your administrator password. The installer needs the password because it installs the node for all users and runs it as a system service.

  3. Once installed, click Close. The following helper applications are now available on your computer (you can view them in the LaunchPad or in the /Applications/Concordium Node folder):

  • Concordium Node Start Mainnet

  • Concordium Node Stop Mainnet

Testnet

Note

See Change the node startup settings for information about how to change the service configuration settings. See Run a validator node on macOS for information about how to set the location of validator credentials.

  1. Go to Downloads, and download the latest macOS installer package (.pkg file).

  2. In the folder where you downloaded the .pkg file, double-click the .pkg file. The Install Concordium Node program opens.

  3. Click Allow to the message saying: This package will run a program to determine if the software can be installed. If you have a M1 based Mac, the installer might ask you to install Rosetta if you haven’t already. Click Install if that’s the case.

  4. If you already have a version of the node installed, click OK to the message saying Previous Installation Detected.

  5. Click Continue on the Introduction page.

  6. Click Continue on the License page, and then Agree to accept the license agreement.

  7. On the Configuration page you have the following options.

../../_images/Node-setup-mac-11.png

  • Run a [mainnet/testnet] node at start-up: When selected, the node runs when the system starts. Choose this option when you plan to use the node frequently and need it to be up-to-date at short notice. If you don’t select this option, you’ll have to start the node manually when required, for example, when you want to use the Desktop Wallet or Concordium Client. If you choose to start the node manually, it might take longer for the node to get up-to-date with the blockchain depending on when the node was last up-to-date.

  • Start the node after installation is complete: The node will automatically start running after the installation is complete. Do not choose this option if you want to make further configuration changes before starting the node.

  • Report to the network dashboard: Select this option if you want to publish your node statistics to the relevant dashboard when the node is running. Deselect this option if you don’t want your node displayed on the dashboard. If selected, you can view the statistics on the testnet dashboard.

  • Public node name: Specify the name of your node as you want it to appear on the network dashboard if the node reports to the network dashboard. You must enter a name for at least one of the nodes.

  1. Once configured, click Continue to go to the Installation Type page.

  2. Click Install and enter your administrator password. The installer needs the password because it installs the node for all users and runs it as a system service.

  3. Once installed, click Close. The following helper applications are now available on your computer (you can view them in the LaunchPad or in the /Applications/Concordium Node folder):

  • Concordium Node Start Testnet

  • Concordium Node Stop Testnet

Verify that the node is running#

The node runs as a background service with no user interface. To verify that it’s running, use the Activity Monitor.

  1. Open the Activity Monitor application from the LaunchPad.

  2. Look at the list and verify that the following is running:

    • concordium-node for each node you are running. For example, if you’re running a node on both testnet and mainnet, you’ll see two instances of concordium-node.

    • node-collector for each node that reports to a network dashboard.

  3. If the node is running properly with reporting to the network dashboard enabled, you can see the name of the node on the mainnet dashboard or the testnet dashboard.

Connect a node to the Desktop Wallet#

You can also verify that a node is running by connecting it to the Desktop Wallet.

  1. In the Desktop Wallet, go to Settings, and then select Node settings.

    • If you’re running the mainnet version of the Desktop Wallet, you must connect to a mainnet node. In the Address field, enter 127.0.0.1 and in the Port field enter 20000.

    • If you’re running the testnet version of the Desktop Wallet, you must connect to a testnet node. In the Address field, enter 127.0.0.1 and in the Port field enter 20001.

  2. Select Set connection. If the connection works and the node is running properly, there’s a message saying Successfully connected.

Enable inbound connections#

If you are running your node behind a firewall, or behind your home router, then you will probably only be able to connect to other nodes, but other nodes will not be able to initiate connections to your node. This is perfectly fine, and your node will fully participate in the Concordium network. It will be able to send transactions and, if so configured, to produce blocks.

However you can also make your node an even better network participant by enabling inbound connections. By default, concordium-node listens on port 8888 for inbound connections on Mainnet and on port 8889 for inbound connections on Testnet. Depending on your network and platform configuration you will either need to forward an external port to 8888 or 8889 on your router, open it in your firewall, or both. The details of how this is done will depend on your configuration.

Change the node startup settings#

If you want to change whether the node services start automatically, you have two options.

  • If you’re not familiar with using a terminal, the easiest option is to reinstall the macOS node and configure it differently.

  • If you’re familiar with using a terminal, the following options are available:

    Note

    The dollar sign ($) in a codeblock means that you should run the command that follows the $ in a terminal.

    • Enable automatic startup of the node by running:

      • For mainnet:

        $sudo ln -s "/Library/Concordium Node/LaunchDaemons/software.concordium.mainnet.node.plist" "/Library/LaunchDaemons/"

      • For testnet:

        $sudo ln -s "/Library/Concordium Node/LaunchDaemons/software.concordium.testnet.node.plist" "/Library/LaunchDaemons/"

    • Enable automatic startup of the node-collector by running:

      • For mainnet:

        $sudo ln -s "/Library/Concordium Node/LaunchDaemons/software.concordium.mainnet.node-collector.plist" "/Library/LaunchDaemons/"

      • For testnet:

        $sudo ln -s "/Library/Concordium Node/LaunchDaemons/software.concordium.testnet.node-collector.plist" "/Library/LaunchDaemons/"

    • Disable automatic startup of the node by running:

      • For mainnet:

        $sudo rm "/Library/LaunchDaemons/software.concordium.mainnet.node.plist"

      • For testnet:

        $sudo rm "/Library/LaunchDaemons/software.concordium.testnet.node.plist"

    • Disable automatic startup of node-collector by running:

      • For mainnet:

        $sudo rm "/Library/LaunchDaemons/software.concordium.mainnet.node-collector.plist"

      • For testnet:

        $sudo rm "/Library/LaunchDaemons/software.concordium.testnet.node-collector.plist"

Node collector configuration#

Since version 5.3.2 of the node, the collector uses the GRPC V2 interface. Therefore, in order to run the collector, it is required that the node which the collector connects to has the GRPC V2 interface enabled.

Note

If the node is configured with TLS, then CONCORDIUM_NODE_COLLECTOR_GRPC_HOST must be configured such that it uses the domain of the certificate.

Since the GRPC V2 port is different than the GRPC V1 port, you need to change it in the node configuration:

Example for Mainnet

<!-- gRPC host to collect from. -->
<key>CONCORDIUM_NODE_COLLECTOR_GRPC_HOST</key>
<string>http://localhost:20000</string>

Example for Testnet

<!-- gRPC host to collect from. -->
<key>CONCORDIUM_NODE_COLLECTOR_GRPC_HOST</key>
<string>http://localhost:20001</string>

Configure a node as a validator#

For information about validation on a MacOS node, see Run a validator node on macOS.

View node logs#

There are two ways to view the logs:

  • With the Console.app you can start recording logs and view them, but you can’t see logs from the past.

    • Open the Console app, click on the Start button to begin recording logs.

    • In the search bar, enter the following and press enter:

      • For mainnet logs: software.concordium.mainnet.node

      • For testnet logs: software.conordium.testnet.node

    • Then click on the small Any button in the search bar and select Subsystem from the list of options.

  • With a terminal and log show you can view logs from the past and as they are logged.

    • Open a terminal.

    • Use the log command by entering:

      • For mainnet logs: log show --predicate 'subsystem == "software.concordium.mainnet.node"'

      • For testnet logs: log show --predicate 'subsystem == "software.concordium.testnet.node"'

    • You can filter the logs with additional parameters, such as start and end date. Enter log show --help to see the parameters available.

Synchronize a node with the network#

When you start a node for the first time, it can take a while to synchronize the node with the rest of the network, since it has to get all blocks from its peers. That is why all node distributions since 6.1 come with out of band catchup enabled. This will speed up the initial catchup and during out of band catchup the node will not have any peers.

The out of band catchup can be kept enabled even after the node is caught up, but is not necessary. If you wish to disable it do the the following:

  1. Remove the environment variables from the configuration file:

    • For mainnet:

      • Edit "/Library/Concordium Node/LaunchDaemons/software.concordium.mainnet.node.plist" as an administrator and remove the following in the EnviromentVariables section:

        <key>CONCORDIUM_NODE_CONSENSUS_DOWNLOAD_BLOCKS_FROM</key>
<string>https://catchup.mainnet.concordium.software/blocks.idx</string>

    • For testnet:

      • Edit "/Library/Concordium Node/LaunchDaemons/software.concordium.testnet.node.plist" as an administrator and remove the following in the EnviromentVariables section:

        <key>CONCORDIUM_NODE_CONSENSUS_DOWNLOAD_BLOCKS_FROM</key>
<string>https://catchup.testnet.concordium.com/blocks.idx</string>

  2. Restart the appropriate node by running the application Concordium Node Stop [Mainnet/Testnet] (if running) and then Concordium Node Start [Mainnet/Testnet].

Uninstall a macOS node#

  1. Press Cmd + Space on your keyboard to open Spotlight Search or click the Spotlight icon in the menu bar.

  2. Search for Concordium Node Uninstaller and open the application that is found.

  3. You now have two options:

    • To delete the node and keep the data and keys, click Yes.

    • To delete the node as well as data and keys, click Yes, and delete data. (Make sure to back up your keys beforehand).

Was this article helpful?
On this page
Edit on GitHub

© Copyright 2021 - 2024, Concordium Software ApS.

Legal information