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. Check the container is running (Status Up). 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 an environment file and populate with variables specific to the network you’re running on. For a full list of available configuration variables, click here. Be sure to update the value for CHANGEME to the value given by your external Ethereum provider. Update the value for mysecretpassword to the chosen password in Run PostgreSQL.

   SepoliaGoerli

   echo "LOG_LEVEL=debug
   ETH_CHAIN_ID=11155111
   CHAINLINK_TLS_PORT=0
   SECURE_COOKIES=false
   ALLOW_ORIGINS=*
   ETH_URL=CHANGEME
   DATABASE_URL=postgresql://postgres:mysecretpassword@host.docker.internal:5432/postgres?sslmode=disable" > ~/.chainlink-sepolia/.env

3. Start the Chainlink Node. Now you can run the Docker image. Replace <version> with your desired version. Tag versions are available in the Chainlink docker hub. The latest version does not work.

   SepoliaGoerli

   cd ~/.chainlink-sepolia && docker run --platform linux/x86_64/v8 --name chainlink  -v ~/.chainlink-sepolia:/chainlink -it --env-file=.env -p 6688:6688 --add-host=host.docker.internal:host-gateway smartcontract/chainlink:<version> local n

   The first time running the image, it will ask you for a password and confirmation. This will be your wallet password that you can use to unlock the keystore file generated for you. Then, you’ll be prompted 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. When running the node again, you can supply the -p option with a path to a text file containing the wallet key password, and a -a option, pointing to a text file containing the API email and password. Instructions on how to do that are here.

4. Check the container is running (Status Up). 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.12.0   "chainlink local n"   4 minutes ago   Up 4 minutes (healthy)   0.0.0.0:6688->6688/tcp   chainlink

5. You can now connect to your Chainlink node’s UI interface by navigating to http://localhost:6688. If using a VPS, you can create a 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. A SSH tunnel is recommended over opening up ports specific to the Chainlink node to be public facing. See the Security and Operation Best Practices page for more details on how to secure your node.