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

   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:

   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. Create an .api file with your API credentials. The API email and password will be used to expose the API for the GUI interface, and you will use these credentials every time you log into your node.

   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, making sure that the password is 16-50 characters in length.

   SepoliaGoerli

   echo "CHANGE_THIS_API_EXAMPLE_EMAIL@example.com
   CHANGE_THIS_EXAMPLE_TEST_API_PASSWORD
   " > ~/.chainlink-sepolia/.api

   In the next step, when you run the Docker image, include the .api file at the end of the docker run command using the -a flag:

   docker run \
   ...
   node start \
   -a /chainlink/.api

5. Start the Chainlink Node by running 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 the node start portion of the command.

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

   cd ~/.chainlink-sepolia && docker run --platform linux/x86_64/v8 --name chainlink-4 -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 -a /chainlink/.api

6. 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
   feff39f340d6   smartcontract/chainlink:1.13.0   "chainlink node start" 4 minutes ago   Up 4 minutes (healthy)   0.0.0.0:6688->6688/tcp   chainlink

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