Running a Chainlink Node

This guide will teach you how to run a Chainlink node locally using Docker. The Chainlink node will be configured to connect to the Ethereum Sepolia.

Requirements

• As explained in the requirements page, make sure there are enough resources to run a Chainlink node and a PostgreSQL database.
• Install Docker Desktop. You will run the Chainlink node and PostgreSQL in Docker containers.
• Chainlink nodes must be able to connect to an Ethereum client with an active websocket connection. See Running an Ethereum Client for details. In this tutorial, you can use an external service as your client.

Using Docker

Run PostgreSQL

1. Run PostgreSQL in a Docker container. You can replace mysecretpassword with your own password.

   docker run --name cl-postgres -e POSTGRES_PASSWORD=mysecretpassword -p 5432:5432 -d postgres

2. Confirm that the container is running. Note the 5432 port is published 0.0.0.0:5432->5432/tcp and therefore accessible outside of Docker.

   docker ps -a -f name=cl-postgres

   If the container is running successfully, the output shows a healthy status:

   CONTAINER ID   IMAGE      COMMAND                  CREATED         STATUS         PORTS                    NAMES
   dc08cfad2a16   postgres   "docker-entrypoint.s…"   3 minutes ago   Up 3 minutes   0.0.0.0:5432->5432/tcp   cl-postgres

Run Chainlink node

Configure your node

1. Create a local directory to hold the Chainlink data:

   Sepolia

   mkdir ~/.chainlink-sepolia

2. Run the following as a command to create a config.toml file and populate with variables specific to the network you're running on. For a full list of available configuration variables, see the Node Config page. Be sure to update the value for CHANGEME to the value given by your external Ethereum provider.

   Sepolia

   echo "[Log]
   Level = 'warn'
   
   [WebServer]
   AllowOrigins = '\*'
   SecureCookies = false
   
   [WebServer.TLS]
   HTTPSPort = 0
   
   [[EVM]]
   ChainID = '11155111'
   
   [[EVM.Nodes]]
   Name = 'Sepolia'
   WSURL = 'wss://CHANGE_ME'
   HTTPURL = 'https://CHANGE_ME'
   " > ~/.chainlink-sepolia/config.toml

3. Create a secrets.toml file with a keystore password and the URL to your database. Update the value for mysecretpassword to the chosen password in Run PostgreSQL. Specify a complex keystore password. This will be your wallet password that you can use to unlock the keystore file generated for you.

   Sepolia

   echo "[Password]
   Keystore = 'mysecretkeystorepassword'
   [Database]
   URL = 'postgresql://postgres:mysecretpassword@host.docker.internal:5432/postgres?sslmode=disable'
   " > ~/.chainlink-sepolia/secrets.toml

4. Optionally, you can create an .api file with the credentials for the node's API and Operator Interface. The node stores the credentials from the .api file in the database only the first time you run the container using the database. The .api file cannot override credentials for an existing user in the database.

   Create the file in the same directory as your TOML config files and list your API credentials. Change the values for API email and password. The user must be an email address with an @ character and the password must be 16-50 characters in length.

   Sepolia

   echo "CHANGE_THIS_EXAMPLE_EMAIL
   CHANGE_THIS_EXAMPLE_PASSWORD
   " > ~/.chainlink-sepolia/.api

5. Start the Chainlink Node by running the Docker image.

   Change the version number in smartcontract/chainlink:2.8.0 with the version of the Docker image that you need to run. For most new nodes, use version 2.0.0 or later. Tag versions are available in the Chainlink Docker hub. The latest version does not work.

   Chainlink Nodes running 2.0.0 and later require the -config and -secrets flags after the node part of the command.

   If you created an .api file with your API and Operator UI login credentials, add -a /chainlink/.api to the end of the docker run command. Otherwise, the node will ask you for these credentials when you start it for the first time. These credentials are stored in the database only when you run a container for the first time against that database. If you need to remove the .api file, delete the container, and start it again without -a /chainlink/.api.

   Sepolia

   cd ~/.chainlink-sepolia && docker run --platform linux/x86_64/v8 --name chainlink -v ~/.chainlink-sepolia:/chainlink -it -p 6688:6688 --add-host=host.docker.internal:host-gateway smartcontract/chainlink:2.8.0 node -config /chainlink/config.toml -secrets /chainlink/secrets.toml start

6. Detach from the container by pressing the Ctrl+P command and then the Ctrl-Q command. On MacOS, use ⌘-P and ⌘-Q.

7. Confirm that the container is running. Note that the 6688 port is published 0.0.0.0:6688->6688/tcp and is accessible outside of Docker.

   docker ps -a -f name=chainlink

   If the container is running, the output shows a healthy status:

   CONTAINER ID   IMAGE                           COMMAND                  CREATED         STATUS                   PORTS                                       NAMES
   867e792d6f78   smartcontract/chainlink:2.8.0   "chainlink node -con…"   2 minutes ago   Up 2 minutes (healthy)   0.0.0.0:6688->6688/tcp, :::6688->6688/tcp   chainlink

8. You can now connect to your Chainlink node's UI interface by navigating to http://localhost:6688. Use the API credentials you set up earlier to log in.

   If you are using a VPS, you can create an SSH tunnel to your node for 6688:localhost:6688 to enable connectivity to the GUI. Typically this is done with ssh -i $KEY $USER@$REMOTE-IP -L 6688:localhost:6688 -N. An SSH tunnel is recommended over opening public-facing ports specific to the Chainlink node. See the Security and Operation Best Practices page for more details about securing your node.

Configure users and roles

You can create several users with different role-based access tiers. This allows you to grant access to several users without granting admin privileges to every user. Role-based access can be configured only by using the CLI.

1. Open an interactive bash shell on the container that is running your node:

   docker exec -it chainlink /bin/bash

2. Log into the Chainlink CLI. The CLI prompts you for the admin credentials that you configured for your node.

   chainlink admin login

3. Add a user with view-only permissions on the node. The CLI prompts you for the new user's credentials.

   chainlink admin users create --email=operator-ui-view-only@test.com --role=view

   This user can now log into the UI and query the API, but cannot change any settings or jobs.

4. Confirm the current list of users:

   chainlink admin users list

5. Log out of the CLI. This prevents users with access to the shell from executing admin commands.

   chainlink admin logout

6. Exit from the container.

   exit

To learn how to modify user roles and see the full list of available roles, read the Role-Based Access Control page.