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 or Goerli testnet.

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
   
   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:

   SepoliaGoerli

   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.

   SepoliaGoerli

   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.

   SepoliaGoerli

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

4. Start the Chainlink Node. Now you can run the Docker image. Change the version number in smartcontract/chainlink:2.0.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. Versions 1.13.1 and earlier require the -config and -secrets flags to be placed before node start.

   SepoliaGoerliSepolia on Nodes <=1.13.1Goerli on Nodes <=1.13.1

   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.0.0 node -config /chainlink/config.toml -secrets /chainlink/secrets.toml start

   The first time running the image, the node asks you to enter an API Email and Password. This will be used to expose the API for the GUI interface, and will be used every time you log into your node.

5. Check the container is running. Note the 6688 port is published 0.0.0.0:6688->6688/tcp and therefore accessible outside of Docker.

   docker ps -a -f name=chainlink
   
   CONTAINER ID   IMAGE                            COMMAND                CREATED         STATUS                   PORTS                    NAMES
   feff39f340d6   smartcontract/chainlink:1.13.0   "chainlink node start" 4 minutes ago   Up 4 minutes (healthy)   0.0.0.0:6688->6688/tcp   chainlink

6. You can now connect to your Chainlink node's UI interface by navigating to http://localhost:6688. If 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 on securing your node.