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 currently served by the IPFS Gateway. In the future, cache misses will be served by Saturn L2 nodes 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
  • Receiving FIL payments
  • Node monitoring
• License

Requirements

General requirements

• Filecoin wallet address
• Email address

Node hardware requirements

• Linux server with a static public IPv4 address
• Root access / passwordless sudo user (How to)
• Ports 80 and 443 free and public to the internet
• Docker installed (Instructions here)
• CPU with 6 cores (12+ cores recommended). CPU Mark of 8,000+ (20,000+ recommended)
• 10Gbps upload link minimum¹ (Why 10Gbps?)
• 32GB RAM minimum (128GB+ recommended)
• 1TB SSD storage minimum (4TB+ recommended)²

_{¹ The more you can serve → greater FIL earnings
² 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.}

1. Install Docker. Instructions here

2. Set the FIL_WALLET_ADDRESS and NODE_OPERATOR_EMAIL environment variables in .bashrc (user) and /etc/environment (global) and then load them

   • If you want your node to join Saturn's Main network and earn FIL rewards, set SATURN_NETWORK to main. If you want your node to join Saturn's Test network, which doesn't earn FIL rewards, set SATURN_NETWORK to test
   • By default, Saturn volume is mounted from $HOME. It can be changed by setting $SATURN_HOME environment variable

3. Change directory to $SATURN_HOME (default: $HOME) to download the run.sh and update.sh scripts in steps 4 and 8

4. Download the run.sh script and make it executable

   curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/run.sh -o run.sh
   chmod +x run.sh

5. Run the script:

   ./run.sh

6. Check logs with docker logs -f saturn-node

7. Check there are no errors, registration will happen automatically and node will restart once it receives its TLS certificate

In most intsances 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"

8. Download the update.sh script and make it executable

   curl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/update.sh -o update.sh
   chmod +x update.sh

9. Setup the cron to run every 5 minutes:

   crontab -e

   Add the following text replacing the path:

   */5 * * * * /path/to/saturn/home/update.sh >> /path/to/saturn/home/l1-cron.log 2>&1
   

   Make sure to have environment variables set in /etc/environment for auto-update to work

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.

1. Install the required Ansible modules

ansible-galaxy collection install community.docker

2. Clone this repository and cd into it.

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

   1. Make sure you have configured ansible_user and ansible_ssh_pass for your target host in your inventory file. See more here.
   2. Setup an authorized_keys file with your public ssh keys in the cloned repository root.
   3. Run ansible-playbook -i <path_to_your_inventory> -l <host_label> --skip-tags=config,harden,run playbooks/l1.yaml

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

5. Replace the environment varariable values where appropriate and export them.

• If Main network: Set SATURN_NETWORK to main
• If you are switching networks check Switching networks and rerun step 4 and 5.
• You can define a host-specific SATURN_HOME by setting a saturn_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

6. 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 kill --signal=SIGTERM saturn-node
  sleep 1800 # wait for 30 minutes to drain all requests
  sudo docker stop saturn-node

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:

1. Gracefully halt your node as explained in Stopping a node.
2. Set the network environment variable SATURN_NETWORK to main, or test, in /etc/environment and .bashrc.
3. Delete contents in $SATURN_HOME/shared/ssl (default: $HOME/shared/ssl).
4. Start the node again with run.sh script.

Node operator guide

For answers to common questions about operating a node, like about receiving your filecoin payouts, see the L1 node FAQ page.

Obtaining a Filecoin wallet address

You need to own a Filecoin wallet to receive FIL payments.

• Official Filecoin wallet documentation

• 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 an 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

  • Exodus

• Mobile wallets

  • FoxWallet

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

Receiving FIL payments

When payments are scheduled to be sent out, your Filecoin wallet will receive a FIL payment.

Node monitoring

• https://dashboard.strn.network - View historical data on your bandwidth contributions, FIL earnings, and more.
• https://orchestrator.strn.pl/stats - View detailed, real-time stats on every Saturn node.

License

Dual-licensed under MIT + Apache 2.0