L1-node
L1-node copied to clipboard
Filecoin Saturn L1 Node β’ The edge cache layer of Filecoin's decentralized CDN πͺ
Saturn L1 Node πͺ
Saturn L1 nodes are CDN edge caches in the outermost layer of the Filecoin Saturn network. L1 nodes serve CAR files to retrieval clients as requested by their CIDs. Cache misses are served by the IPFS Network and Filecoin Storage Providers.
Saturn is live. Do you have a server that meets the minimum hardware requirements? If so, follow the setup instructions below to get started. You can run an L1 node, contribute bandwidth to the network, and earn Filecoin (FIL) today.
Beyond running a node, Saturn is a community run project and we'd love for you to get involved. Come say hi in #filecoin-saturn on Filecoin Slack! π
Table of Contents
-
Requirements
- General requirements
- Node hardware requirements
- Set up a node
- Set up a node with Ansible
- Stopping a node
- Switch networks between test net and main net
-
Node operator guide
- Obtaining a Filecoin wallet address
- Claiming your node's earnings
- Node monitoring
- Community Tools
- License
Requirements
General requirements
- Filecoin wallet address
- Email address
Node hardware requirements
- Linux server with a static public IPv4 address in a unique /24 CIDR block
- Root access / passwordless sudo user (How to)
- Ports 80 and 443 free and public to the internet
- Docker installed (Instructions here) with Docker Compose v2
- CPU with 6 cores (12+ cores recommended). CPU Mark of 8,000+ (20,000+ recommended)
- 10Gbps upload link minimum1 (Why 10Gbps?)
- 32GB RAM minimum (128GB+ recommended)
- 4TB SSD storage minimum (16TB+ NVMe recommended)2
Only one node per physical host is allowed. If you want to run multiple nodes, you need to run them on dedicated hardware.
Multi-noding (Sharing CPU, RAM, Uplink or storage among nodes) is not allowed.
2 Bigger disk β bigger cache β greater FIL earnings
Set up a node
If you want to switch your node from test net to main net, or vice versa, see Switch networks below.
-
Install
- Docker: instructions here
- Docker compose v2: instructions here
-
Change directory to
$SATURN_HOME
(default:$HOME
) to download the required filescd ${SATURN_HOME:-$HOME}
-
Download the
.env
fileNote: the
.env
file does not take precedence over env variables set locally.- Set the mandatory
FIL_WALLET_ADDRESS
andNODE_OPERATOR_EMAIL
environment variables in the.env
file. - Set the
SATURN_NETWORK
environment variable in the.env
file.- To join Saturn's Main network and earn FIL rewards, make sure to set
SATURN_NETWORK
tomain
. - To join Saturn's Test network, which doesn't earn FIL rewards, set
SATURN_NETWORK
totest
. Note that this is the default value!
- To join Saturn's Main network and earn FIL rewards, make sure to set
- By default, the Saturn volume is mounted from
$HOME
. It can be changed by setting the$SATURN_HOME
environment variable.
curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/.env -o .env
You can use the text editor of your choice (e.g.
nano
orvim
on Linux) - Set the mandatory
-
Download the
docker-compose.yml
file:curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/docker-compose.yml -o docker-compose.yml
-
Download the
docker_compose_update.sh
script and make it executable:curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/docker_compose_update.sh -o docker_compose_update.sh chmod +x docker_compose_update.sh
-
Set up the cron job to auto-update the
docker-compose.yml
file:(crontab -l 2>/dev/null; echo "*/5 * * * * cd $SATURN_HOME && sh docker_compose_update.sh >> docker_compose_update.log 2>&1") | crontab -
-
Launch it:
sudo docker compose up -d
-
Check logs with
docker logs -f -n 100 saturn-node
-
Check for any errors. Registration will happen automatically and the node will restart once it receives its TLS certificate
In most instances speedtest does a good job of picking "close" servers but for small networks it may be incorrect.
If the speedtest value reported by speedtest seems low, you may want to configure SPEEDTEST_SERVER_CONFIG to point to a different public speedtest server. You will need to install speedtest CLI in the host and fetch close servers' IDs by doing speedtest --servers
, then setting SPEEDTEST_SERVER_CONFIG="--server-id=XXXXX"
Update a node
We are using a Watchtower container to update the saturn-node container.
Your node will be updated automatically. You can see the update logs with docker logs -f saturn-watchtower
.
Make sure to setup the cron job to auto-update docker-compose.yml
as well (see above).
Set up a node with Ansible
From here:
"Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates."
This playbook is meant as a bare-bones approach to set up an L1. It simply automates running the steps described above. A consequence of this is that when run it will restart a crashed L1 node docker container. It also presents a basic approach to server hardening which is by no means thorough.
Note: The security of your servers is your responsibility. You should do your own research to ensure your server follows security best practices.
If you're looking for a playbook which covers server hardening, monitoring and logging please check out https://github.com/hyphacoop/ansible-saturn-l1.
Currently, this playbook runs on the following Linux distros:
- Ubuntu
- Debian
- CentOS
These instructions are to be run in a machine with Ansible >= 2.14 installed. This machine is known as your control node and it should not be the one to run your L1 node.
Most commands are run as root and your ssh user should have root access on the target machine.
- Install the required Ansible modules
ansible-galaxy collection install community.docker
-
Clone this repository and
cd
into it. -
For target host connectivity, ssh keys are recommended and this playbook can help you with that.
Note: Using the playbook for this is completely optional.
- Make sure you have configured
ansible_user
andansible_ssh_pass
for your target host in your inventory file. See more here. - Setup an
authorized_keys
file with your public ssh keys in the cloned repository root. - Run
ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=config,harden,run playbooks/l1.yaml
- Make sure you have configured
-
Ensure your control node has ssh access to your target machine(s).
- Make sure to specify which hosts you want to provision in your inventory file.
ansible -vvv -i <path_to_your_inventory> <host_label> -m ping
- Replace the environment variable values where appropriate and export them.
- If Main network: Set
SATURN_NETWORK
tomain
- If you are switching networks check Switching networks and rerun step 4 and 5.
- You can define a host-specific
SATURN_HOME
by setting asaturn_root
variable for that host on your inventory file. See more here.
export FIL_WALLET_ADDRESS=<your_fil_wallet_address>; export NODE_OPERATOR_EMAIL=<your_email>; export SATURN_NETWORK=test
- Run the playbook
- Feel free to use host labels to filter them or to deploy incrementally.
- We're skipping the bootstrap play by default, as it deals with setting authorized ssh keys on the target machine. See 2 for more info.
ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=bootstrap playbooks/l1.yaml
- To skip the hardening step run this instead:
ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=bootstrap,harden playbooks/l1.yaml
Stopping a node
To gracefully stop a node and not receive a penalty, run:
sudo docker stop --time 1800 saturn-node
or if you are in your $SATURN_HOME
folder with the Saturn docker-compose.yml
file:
sudo docker compose down
We are setting the stop_signal
and the stop_grace_period
in our Docker compose file to avoid issues.
If you have a custom setup, make sure to send a SIGTERM to your node and wait at least 30 minutes for it to drain.
Switch networks between test net and main net
If you want to switch your node from Saturn's test network (aka test
) to Saturn's main network (aka main
), or vice versa, follow these steps:
- Gracefully halt your node as explained in Stopping a node.
- Set the network environment variable
SATURN_NETWORK
tomain
, ortest
, in your$SATURN_HOME/.env
file (default:$HOME/.env
). - Delete contents in
$SATURN_HOME/shared/ssl
(default:$HOME/shared/ssl
). - Start the node again with
docker compose -f $SATURN_HOME/docker-compose.yml up -d
. - Check logs with
docker logs -f saturn-node
Node operator guide
For answers to common questions about operating a node, see the L1 node FAQ page.
Network Uptime Requirement
To be eligible for the end of month earnings on the Saturn Network, nodes must satisfy a minimum uptime requirement each month. Having an uptime requirement has the following benefits:
- Addresses node churn on the network. Node churn reduced performance and the stability of the network. Having a minimum uptime requirement incentivizes nodes to remain online for longer periods.
- Certain malicious nodes on the network run on compromised cloud accounts. Those usually have a lifetime of ~3 days. The uptime requirement ensures that those nodes do not receive earnings.
The current uptime requirement is as follows:
- For a node operator to qualify for earnings at the end of the month, their node must be online for at least 14 days during the month. It is important to note that earnings for nodes STILL get calculated before the node satisfies the uptime requirement.
- When a node first registers during a given month, its uptime requirement check will be postponed to the following month to give a fair opportunity for each node to meet the uptime requirement. Its earnings will remain pending until it has satisfied the uptime requirement. If the node satisfied the uptime requirement during the same month it registers, it will be eligible to receive earnings that month.
- Nodes that do not satisfy the uptime requirement in the months after their registration month will forfeit their earnings for the given month. Their forfeited earnings will be added to the network reward pool for the following month.
- The uptime requirement must be satisfied on a monthly basis after the registration month is over.
Note: Beginning July 1st, 2023, Saturnβs monthly node uptime requirement increased from 7 days to 14 days. This means that for a node to qualify for earnings on August 1st, 2023, that node must have been online and operational for at least 14 contiguous days in July.
Read more about Saturn's node uptime requirement in the docs, here.
Obtaining a Filecoin wallet address
You need to own a Filecoin wallet to receive FIL payouts.
-
If you have an account on a Centralized Exchange (Coinbase, Binance, etc.) that supports Filecoin, go through the steps to deposit Filecoin and you'll be given a wallet address. This is recommended if you don't want to manage your wallet's seed phrase.
-
Web wallets
- Filfox wallet
- Glif - Supports Ledger
-
Desktop wallets
-
Mobile wallets
β οΈ Please follow crypto wallet best practices. Never share your seed phrase with anyone or enter it into websites. The Saturn team will never DM you or ask you to verify/validate/upgrade your wallet. If you need assistance, please ask in public channels such as the #filecoin-saturn Slack.
Claiming your earnings
Each month, your node's earnings, in FIL, are calculated by the network based on various factors such as the amount of bandwidth it served, the number of requests it handled, its performance metrics like TTFB and upload speed, and its availaility and uptime. These earnings are then sent to a payout FVM smart contract by the 7th day of the following month. For example, earnings for December 2022 would be transferred to a payout smart contract by January 7th, 2023.
After your node's earnings are in the payout FVM smart contract, you can claim them on payouts.saturn.tech. Claiming your earnings moves the Filecoin your node(s) earned from the smart contract to your personal Filecoin wallet.
Node monitoring
- https://dashboard.saturn.tech - View detailed, real-time stats on every Saturn node.
- https://dashboard.saturn.tech/address - View historical data on your bandwidth contributions, FIL earnings, and more.
- https://explorer.saturn.tech - View a 3D geospatial visualization of the Saturn network, along with nodes and network statistics.
Community Tools
These Saturn tools are maintained by community members outside the Saturn core team.
- https://github.com/31z4/saturn-moonlet - Self-hosted Saturn monitoring using Prometheus and Grafana. View detailed, real-time and historical data on your nodes and earnings, setup alerts, and more.
License
Dual-licensed under MIT + Apache 2.0