Chainlink Developers

Welcome to the Chainlink documentation site. You'll find comprehensive guides and documentation to help you start working with Chainlink as quickly as possible, as well as support if you get stuck. Click here for an introductory walkthrough on how to create a Chainlink request on the Ropsten test network!

Building on Chainlink? Click here to get started!

Get Started

Running a Chainlink Node

In this section, we'll explain the requirements and basics for running your own Chainlink node.

It's important to note that nodes can fulfill requests for open APIs out-of-the-box using our core Adapters without needing any additional configuration.

If you would like to provide data from an authenticated API, you can add an external adapter to enable connectivity through the Chainlink node.

The Chainlink node is middleware, operating between the blockchain and external data. More information on our architecture is available here.

Using Docker

It's recommended to run the Chainlink node with Docker. This is because we continuously build and deploy the code from our repository on Github, which means you don't need a complete development environment to run a node.

📘

Docker Tags

Chainlink follows a Gitflow based release process for our tagged Docker images. That the means that latest represents the most recent stable build on our master branch. New releases are tagged with the version number and can also be considered stable. Before we cut a release, we may tag candidate-* to test out and deploy a new version; these tags should not be considered stable. The latest version of our development branch is available as the develop tag and is also not considered stable.

Requirements

  • Docker-CE. Quick instructions for setting up Docker is below:
sudo amazon-linux-extras install -y docker
sudo systemctl start docker
sudo gpasswd -a $USER docker
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo systemctl start docker
sudo usermod -aG docker $USER
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo usermod -aG docker $USER
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo systemctl start docker
sudo usermod -aG docker $USER
exit
# log in again
curl -sSL https://get.docker.com/ | sh
sudo usermod -aG docker $USER
exit
# log in again

Create a Directory

Once you have your Ethereum client running and fully synced, you're ready to run the Chainlink node.

Create a local directory to hold the Chainlink data:

mkdir ~/.chainlink-rinkeby
mkdir ~/.chainlink-kovan
mkdir ~/.chainlink

Create an Environment File

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.

echo "ROOT=/chainlink
LOG_LEVEL=debug
ETH_CHAIN_ID=4
MIN_OUTGOING_CONFIRMATIONS=2
LINK_CONTRACT_ADDRESS=0x01BE23585060835E02B77ef475b0Cc51aA1e0709
CHAINLINK_TLS_PORT=0
SECURE_COOKIES=false
GAS_UPDATER_ENABLED=true
ALLOW_ORIGINS=*" > ~/.chainlink-rinkeby/.env
echo "ROOT=/chainlink
LOG_LEVEL=debug
ETH_CHAIN_ID=42
MIN_OUTGOING_CONFIRMATIONS=2
LINK_CONTRACT_ADDRESS=0xa36085F69e2889c224210F603D836748e7dC0088
CHAINLINK_TLS_PORT=0
SECURE_COOKIES=false
GAS_UPDATER_ENABLED=true
ALLOW_ORIGINS=*" > ~/.chainlink-kovan/.env
echo "ROOT=/chainlink
LOG_LEVEL=debug
ETH_CHAIN_ID=1
CHAINLINK_TLS_PORT=0
SECURE_COOKIES=false
GAS_UPDATER_ENABLED=true
ALLOW_ORIGINS=*" > ~/.chainlink/.env

Set your Ethereum Client URL

🚧

Using an external Ethereum client?

If you're using a 3rd party service to connect to the blockchain, skip to the External Provider section to set the ETH_URL environment variable. We provide general guidance, but you will need to obtain the websocket connection string to add to your environment file.

Ethereum Client on the Same Machine

Next you need to get the URL for the Ethereum client. The command below will help you obtain the IP address of the container that your Ethereum client is running on. This will only work if you have started an Ethereum client on the same machine as your Chainlink node.

ETH_CONTAINER_IP=$(docker inspect --format '{{ .NetworkSettings.IPAddress }}' $(docker ps -f name=eth -q))

Then run the following command to add the Ethereum client's URL to your environment file. If you are using an external Ethereum client, use the External tab below, and update $ETH_CONTAINER_IP to the websocket address used for connectivity.

echo "ETH_URL=ws://$ETH_CONTAINER_IP:8546" >> ~/.chainlink-rinkeby/.env
echo "ETH_URL=ws://$ETH_CONTAINER_IP:8546" >> ~/.chainlink-kovan/.env
echo "ETH_URL=ws://$ETH_CONTAINER_IP:8546" >> ~/.chainlink/.env

Ethereum Client as an External Provider

If you are using an external provider for connectivity to the Ethereum blockchain or you are running an Ethereum client on a separate instance, you may use the command below for your network. Be sure to update the value for CHANGEME to the value given by your provider or the address and port of your separate instance.

echo "ETH_URL=CHANGEME" >> ~/.chainlink-rinkeby/.env
echo "ETH_URL=CHANGEME" >> ~/.chainlink-kovan/.env
echo "ETH_URL=CHANGEME" >> ~/.chainlink/.env

Set the Remote DATABASE_URL Config

You will need to connect your Chainlink node with a remote PostgreSQL database. See the Connecting to a Remote Database page for more information. Use the example below to configure your DATABASE_URL setting in your environment file, replacing $VARIABLES with their actual values.

  • $USERNAME: The database username (must be owner)
  • $PASSWORD: The user's password
  • $SERVER: The server name or IP address of the database server
  • $PORT: The port that the database is listening on
  • $DATABASE: The database to use for the Chainlink node

🚧

If you're testing you can add ?sslmode=disable to the end of your DATABASE_URL. However you should never do this on a production node.

echo "DATABASE_URL=postgresql://$USERNAME:[email protected]$SERVER:$PORT/$DATABASE" >> ~/.chainlink-rinkeby/.env
echo "DATABASE_URL=postgresql://$USERNAME:[email protected]$SERVER:$PORT/$DATABASE" >> ~/.chainlink-kovan/.env
echo "DATABASE_URL=postgresql://$USERNAME:[email protected]$SERVER:$PORT/$DATABASE" >> ~/.chainlink/.env

For a primary/secondary Chainlink node architecture, you may also want to set the DATABASE_TIMEOUT configuration as well. Setting DATABASE_TIMEOUT to 0 allows a secondary node to wait for the lock to be released on the database indefinitely.

echo "DATABASE_TIMEOUT=0" >> ~/.chainlink-rinkeby/.env
echo "DATABASE_TIMEOUT=0" >> ~/.chainlink-kovan/.env
echo "DATABASE_TIMEOUT=0" >> ~/.chainlink/.env

Start the Chainlink Node

Now you can run the Docker image:

cd ~/.chainlink-rinkeby && docker run -p 6688:6688 -v ~/.chainlink-rinkeby:/chainlink -it --env-file=.env smartcontract/chainlink local n
cd ~/.chainlink-kovan && docker run -p 6688:6688 -v ~/.chainlink-kovan:/chainlink -it --env-file=.env smartcontract/chainlink local n
cd ~/.chainlink && docker run -p 6688:6688 -v ~/.chainlink:/chainlink -it --env-file=.env smartcontract/chainlink local n

📘

Local Database

If you're running a local database you may need to add --network host to the end of the command above.

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

📘

You will need to send some ETH to your node's address in order for it to fulfill requests. You can view your node's ETH address when the node starts up or on the Configuration page of the GUI.

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 [email protected]$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 our Best Security and Operating Practices page for more details on how to secure your node.

Updated 6 days ago


Running a Chainlink Node


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.