Saturn L1 nodes are CDN edge caches in the outermost layer of the Filecoin Saturn Network. L1 nodes serve CIDs and CID byte ranges to retrieval clients. Cache misses are served by Saturn L2 nodes.
We're also looking for early L1 node operators to run L1 nodes and earn Filecoin (FIL). Do you have a server meeting the requirements below? If you do, follow the setup instructions below to get started.
We'd love your feedback in #filecoin-saturn on Filecoin Slack.
- Filecoin wallet address
- Email address
- Linux server with a public IPv4 address
- Root access / passwordless sudo user (How to)
- Ports 80 and 443 free
- Docker installed (Instructions here)
- CPU with 6 cores (12+ cores recommended). CPU Mark of 8,000+ (20,000+ recommended)
- 10Gbps upload link minimum1
- 32GB RAM minimum (128GB+ recommended)
- 1TB SSD storage minimum (4TB+ recommended)2
2 Bigger disk → bigger cache → greater FIL earnings
If you are switching networks, please see the Switching networks section below.
-
Install Docker. Instructions here
-
Set FIL_WALLET_ADDRESS and NODE_OPERATOR_EMAIL env variables in
.bashrc(user) and/etc/environment(global), and load them- If Main network: Set
SATURN_NETWORKtomaintoo - By default, Saturn volume is mounted from
$HOME. It can be changed by setting$SATURN_HOMEenv variable
- If Main network: Set
-
Change directory to $SATURN_HOME (default:
$HOME) to download therun.shandupdate.shscripts in steps 4 and 8 -
Download the
run.shscript and make it executablecurl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/run.sh -o run.sh chmod +x run.sh
-
Run the script:
./run.sh
-
Check logs with
docker logs -f saturn-node -
Check there are no errors, registration will happen automatically and node will restart once it receives its TLS certificate
-
Download the
update.shscript and make it executablecurl -s https://raw.githubusercontent.com/filecoin-saturn/L1-node/main/update.sh -o update.sh chmod +x update.sh
-
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>&1Make sure to have env variables set in
/etc/environmentfor 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 sec 10000 urity 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.12 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.
-
Clone this repository and
cdinto 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_userandansible_ssh_passfor your target host in your inventory file. See more here. - Setup an
authorized_keysfile 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 env var values where appropriate and export them.
- If Main network: Set
SATURN_NETWORKtomain - If you are switching networks check Switching networks and rerun step 4 and 5.
- You can define a host-specific
SATURN_HOMEby setting asaturn_rootvariable 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.yamlTo gracefully stop a node a not receive a penalty, run:
sudo docker kill --signal=SIGTERM saturn-node
sleep 600 # wait for 10 minutes to drain all requests
sudo docker stop saturn-nodeIf 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 env variable
SATURN_NETWORKtomain, ortest, in/etc/environmentand.bashrc. - Delete contents in
$SATURN_HOME/shared/ssl(default:$HOME/shared/ssl). - Start the node again with
run.shscript.
For answers to common questions about operating a node, see the L1 node docs/faq.md page.
You need to own a Filecoin wallet to receive FIL payments.
-
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
-
Mobile wallets
When payments are scheduled to be sent out, your Filecoin wallet will receive a FIL payment.
- https://dashboard.strn.network - View historical data on your bandwidth contributions, FIL earnings, and more.
- https://orchestrator.strn.pl/stats - View detailed, realtime stats on every Saturn node.
- Run orchestrator locally
- Self-signed 256-bit ECC certificate (Instructions here) in
shared/ssl
Build the docker image with
./node buildRun the docker container with
./node run./node build runOnly changes to container/ and Dockerfile trigger a build
- To deploy to test network, just push to
main. - To deploy to main network, create a tag and push it, example:
git checkout main git pull git tag $(date +%s) git push --follow-tags
In development, to avoid an automatic CI/CD deployment to the test network when any change is made to the container/ directory, include [skip ci] in the git commit message. Like:
git commit -m "my commit message [skip ci]"nginx/ contains the nginx configuration of the caching proxy
shim/ contains the necessary code to fetch CIDs and CAR files for nginx to cache
Dual-licensed under MIT + Apache 2.0