This section describes how to install the Fleek Network Lightning on supported operating systems. The installation can be made quicker by running the assisted installer or by following the manual installation if you want a bit more control.
If you'd like to participate in the alpha Testnet, you have to go through the onboarding process. Check the requirements and find the onboarding instructions to enable you to proceed and install a network node successfully.
Assisted installer
The assisted installer is a script written in Bash (Unix shell) that is available as a curl command line.
Prerequesites
- A basic knowledge of command line interface (CLI)
- A supported Linux server
Connect to your server
Connect to the Linux server where the Node's going to be installed via SSH by opening a shell session there.
If you have set up a public SSH key for the machine, connecting to the server should be as simple as:
ssh <USERNAME>@<REMOTE_HOST>
Check the cloud provider for instructions to understand how to setup an ssh connection and connect to it remotely. Some other users might have local access to a supported Linux server. To keep this guide short, we'll assume you've rented a VPS from a cloud provider.
Create a user
We recommend creating a non-root user with administrative privileges. It'll allow us to install any system requirements.
You can create a new user and add to the sudo group by running:
For our example, we'll be using the name lgtn but you can pick whichever you'd like. If you already have a sudoer account, you can skip this step.
sudo adduser lgtn
After completing the adduser steps, execute the usermod to add the user to the sudo group, as follows:
sudo usermod -aG sudo lgtn
Switch to the new user by using the command:
su lgtn
Change the directory to the new user's home, as follows:
cd /home/lgtn
Run the script for a quick install
Copy and paste it to the server host terminal and execute it to launch the assisted installation process, as follows:
curl https://get.fleek.network | bash
On success, you should be greeted by the following welcome screen:
⭐️ Fleek Network Lightning CLI installer ⭐️
zeeeeee-
z$$$$$$"
d$$$$$$"
d$$$$$P
d$$$$$P
$$$$$$"
.$$$$$$"
.$$$$$$"
4$$$$$$$$$$$$$"
z$$$$$$$$$$$$$"
"""""""3$$$$$"
z$$$$P
d$$$$"
.$$$$$"
z$$$$$"
z$$$$P
d$$$$$$$$$$"
*******$$$"
.$$$"
.$$"
4$P"
z$"
zP
z"
/
★★★★★★★★★ 🌍 Website https://fleek.network
★★★★★★★★★ 📚 Documentation https://docs.fleek.network
★★★★★★★★★ 💾 Git repository https://github.com/fleek-network/lightning
★★★★★★★★★ 🤖 Discord https://discord.gg/fleek
★★★★★★★★★ 🐤 Twitter https://twitter.com/fleek_net
★★★★★★★★★ 🎨 Ascii art by https://www.asciiart.eu
...
Remaining output omitted for brevity, you'll not see this text line
Follow the installation wizard to have the Fleek Network Lightning CLI and service installed on the supported server.
After creating the service, launch the service by executing the following command:
sudo systemctl start lightning.service
To learn more about Systemctl commands, visit the section Use Systemctl to manage the Lightning Service
Find the timeline of events for the Lightning service by checking the log files. Learn about it in the section Log Messages.
Once the installation is complete, do a health check! Check the section Health Check to learn how to do a node health checkup.
About the process
The installation process is open source and transparent. The source is available in the get.fleek.network or the origin repository here.
"Get Fleek Network" is an attempt to make our software more accessible. By providing scripts to automate the installation process of our software, we believe that it can help improve the onboarding experience of our users.
The installer assists the node operator by automating the Lightning CLI build from the open-source code and setting up the system service. A node operator should use the assisted installer to ease onboarding, reduce repetition,
At a high level, the installer will:
- Install required dependencies, e.g. rust toolchain
- Pull the source code from the origin repository
- Build the binary, e.g. a
lightning CLI(lgtn) is compiled from source code - Setup a Systemd service named lightning
- Announces staking requirement
- Opt-in to join network
- Provide instructions to launch, stop the Fleek network via the Systemd lightning service
Remember that if you use the assisted installer, you won't have to do the manual installation process as described in the next section. On success, the assisted installer should provide the same result as following the manual instructions.
Manual installation
The following section will walk through the dependencies and Rust installation process for Linux. If you're on Windows, we recommend to setup Windows Subsystem Linux, reading the Ubuntu tutorial or picking another supported distro. The WSL will let you use Linux applications, utilities and bash command tools you'll find in the tutorial.
We're only supporting Linux operating system (server edition). Find the list of supported OS here.
Prerequisites
To follow the guide, you will need the following:
- Familiarity with the command-line interface
- Git
You're required to have some experience with the command-line interface and have Git installed; Also, you should be happy to troubleshoot, since versions might differ from the time of writing and reading. Most times, a simple web search provides the best answers.
If you don't have Git installed, learn more about it and the instructions by reading the Git documentation.
Create a user
We recommend creating a non-root user with administrative privileges. It'll allow us to install any system requirements.
You can create a new user and add to the sudo group by running:
For our example, we'll be using the name lgtn but you can pick whichever you'd like. If you already have a sudoer account, you can skip this step.
sudo adduser lgtn
After completing the adduser steps, execute the usermod to add the user to the sudo group, as follows:
sudo usermod -aG sudo lgtn
Switch to the new user by using the command:
su lgtn
Change the directory to the new user's home, as follows:
cd /home/lgtn
Install Rust with Rustup tool
Visit the Rust website getting started guide, to find, copy and run the Rustup tool for installation and version management.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Alternatively, if you have installed Rust in the past, you may want to update it 👌.
rustup update
During the installation process, if asked about preferences, select the default option!
You can uninstall at any time with rustup self uninstall and
these changes will be reverted.
Current installation options:
default host triple: x86_64-unknown-linux-gnu
default toolchain: stable (default)
profile: default
modify PATH variable: yes
1) Proceed with installation (default)
2) Customize installation
3) Cancel installation
Once complete, you'll have to restart your current shell or reload the "PATH" environment variable to include Cargo's bin directory $HOME/.cargo/bin. This is required to let you use "cargo" command globally.
To configure your current shell, run:
source "$HOME/.cargo/env"
From then on, the latest version of Cargo (Rust's build and package manager tool) should be installed. Learn more about Cargo, here.
Check the version to confirm's working correctly:
cargo --version
Here's the output we got (beware that our version might differ to yours, it's expected 😅).
cargo 1.75.0 (1d8b05cdd 2023-11-20)
In order to successfully build the Fleek Network Lightning CLI, you need to have version 1.75.0 or higher installed.
Lightning installer rust dependencies
Rustup subcommands deal with toolchains, a collection of programs required to compile a Rust application.
rustup toolchain list
For example, on Linux Ubuntu we generally have it set to the default:
stable-x86_64-unknown-linux-gnu (default)
While on macOS:
stable-x86_64-apple-darwin (default)
Make sure you have Rustup set to the desired toolchain as default if required 💁♀️!
rustup default <TOOLCHAIN-LIST-NAME>
To build Fleek Network Lightning CLI, version >= 1.75.0 is required. Get the latest version by running the command:
cargo update
Linux dependencies
On Linux (we'll stick with Ubuntu as the Linux distro example), start by updating the package information in the source list and then upgrade all the installed packages with the latest versions (do the equivalent for your Linux distro), as follows:
sudo apt-get update
sudo apt-get upgrade
You can optionally pass the y flag to skip any user prompts e.g. sudo apt-get update -y to any remaining apt-get commands.
Install the build-essentials packages, necessary for compiling general software and for our use-case Lightning CLI.
sudo apt-get install build-essential
Followed by the required tools to compile the application (cmake, clang, pkg-config and libssl-dev ).
sudo apt-get install cmake clang pkg-config libssl-dev gcc-multilib
For Debian, you should install gcc, as follows:
sudo apt-get update
sudo apt-get install gcc
Now install the Protobufer Compiler.
sudo apt-get install protobuf-compiler
Ensure the compiler version is 3+
protoc --version
Installing Lightning CLI
If you haven't already, clone the Fleek Network's Lightning repository to your machine.
You have several ways of doing this:
- Clone via HTTPS
- Clone via SSH
- Download via Github CLI
- Download the zip package from the repository
We recommend HTTPS because it is the easiest to set up in the wild, and by users who are new to all this. Although, we strongly recommend using an SSH connection when interacting with GitHub. If you are to this and are interested read more about it here.
git clone -b testnet-alpha-1 https://github.com/fleek-network/lightning.git <DIRECTORY-NAME>
At time of writing, we are checking the branch name testnet-alpha-1 that corresponds to the testnet phase.
Here's an example of what it'd look like when sticking to the recommended path location:
git clone -b testnet-alpha-1 https://github.com/fleek-network/lightning.git ~/fleek-network/lightning
When git clone completes 👍, change directory to the project directory e.g. we cloned to the default name ~/fleek-network/lightning:
cd ~/fleek-network/lightning
The ~/fleek-network/lightning or $HOME/fleek-network/lightning directory is the default or recommended location to store the repository. If you like to follow conventions, then is best to stick with the recommendation, to avoid confusion and make it easier to follow our documentation.
If you list (ls) the files in the directory, it should be similar to:
.
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── Cargo.lock
├── Cargo.toml
├── LICENSE
├── README.md
├── codecov.yml
├── core
├── docs
├── lib
├── lightning.toml
├── rust-toolchain
├── rustfmt.toml
├── services
└── target
At this point, you should be able to run the install command successfully.
If you already had Rust installed, or the project before, and skipped instructions directly here, there might be case where you get errors. So, make sure to clear your work directory:
cargo clean
cargo update
Start the install process by running the command:
cargo +stable install --locked --path core/cli --features services
The installation process is long, as it compiles the application binary for us from the source code.
🌈 Here's the output when successful! Note, that the output might differ slightly from time of writing.
Finished release [optimized] target(s) in 11m 22s
Installing /home/lgtn/.cargo/bin/lightning
Installed package `lightning v0.1.0 (/crates/lightning)` (executable `lightning`)
Once Rust generates the binary lightning-node, you can find it in the directory $HOME/.cargo/bin/lightning-node. The location can be overridden if $CARGO_HOME is set. Alternatively, if you've run the cargo build command and depending on the usage of +stable flag, the binary should be located at ~/fleek-network/lightning/target/debug/lightning-node or ~/fleek-network/lightning/target/release/lightning-node.
You can create a lgtn symbolic link to /usr/local/bin to make it available globally.
sudo ln -s "/home/lgtn/.cargo/bin/lightning-node" /usr/local/bin/lgtn
After completing, you'll have the ability to type lgtn to execute the binary anywhere for your user account. Other users might find it better to copy or create an alias instead.
Run the lgtn help sub-command as a checkup:
Usage: lightning-node [OPTIONS] <COMMAND>
Commands:
run Start the node
keys Handle keys
print-config Print the loaded configuration
help Print this message or the help of the given subcommand(s)
Options:
-c, --config <CONFIG> Path to the toml configuration file [default: lightning.toml]
--with-mock-consensus Determines that we should be using the mock consensus backend
-v... Increases the level of verbosity (the max level is -vvv)
--log-location Print code location on console logs
-h, --help Print help
-V, --version Print version
Beware that your output might differ a bit, as Lightning is in constant development. Note that you'll have to "re-install" every time you want to pull updates from the source repository, as the update at the time of writing is done manually and not automatically.
Key generator
Before starting the node, you should generate a public and private key.
lgtn keys generate
The keys will be generated and placed under the system directory ~/.lightning/keystore. The private key is the user's responsibility and no one else can generate or recover it for you, including Fleek Network or any team member. Your keys, your responsibility!
Set user path in config.toml
You should be following the create a user recommendation. For our example, we have the username lgtn.
If you have chosen a different username, replace lgtn by the correct username you have selected.
In the config.toml you'll find some and more of the following:
[BLANK]
[application]
db_path = "~/.lightning/data/app_db"
[consensus]
store_path = "~/.lightning/data/narwhal_store"
[fsstore]
root = "~/.lightning/blockstore"
[resolver]
store_path = "~/.lightning/data/resolver_store"
[signer]
consensus_key_path = "~/.lightning/keystore/consensus.pem"
node_key_path = "~/.lightning/keystore/node.pem"
Find and replace all instances of ~ in the config file /home/lgtn/.lightning/config.toml. Here's an example using sed:
sed -i "s|~/.lightning|/home/lgtn/.lightning|g" "/home/lgtn/.lightning/config.toml"
The config.toml example below is a shorter version of what you'll encounter, yours might look different. We do this to keep the guide simple to read. Do not copy and replace with the version demonstrated here.
Once changed, all the instances of ~/ should be replaced by your user path e.g. /home/lgtn/. For our example, the output would look like the following:
[BLANK]
[application]
db_path = "/home/lgtn/.lightning/data/app_db"
[consensus]
store_path = "/home/lgtn/.lightning/data/narwhal_store"
[fsstore]
root = "/home/lgtn/.lightning/blockstore"
[resolver]
store_path = "/home/lgtn/.lightning/data/resolver_store"
[signer]
consensus_key_path = "/home/lgtn/.lightning/keystore/consensus.pem"
node_key_path = "/home/lgtn/.lightning/keystore/node.pem"
Set testnet in config.toml
Set the testnet attribute to true in the config.toml located in the path ~/.lightning/config.toml.
[application]
db_path = "~/.lightning/data/app_data"
mode = "Prod"
storage = "RocksDb"
testnet = true
...
The configuration file should have more content, which was omitted here to keep it short and to the point. You're interested in the testnet property name only.
Network participation
The Node Operator has to explicitly opt-in for a node to participate in the Network, regardless of whether the node Lightning Service is running.
Node participation can be true or false (online or offline) throughout an Epoch. Participation is in a transient state when the operator requests to opt in or out, and the network has yet to end the undergoing Epoch. Once the Epoch ends, the Node participation transitions to true or false. Therefore, a Node Operator can expect a Node state to be online, offline, opted in or out during an Epoch lifetime.
Before starting the service, make sure to opt-in or opt-out of network participation, through the available subcommand opt in the CLI.
The quickest way to find help is to run the help subcommand as follows:
lgtn opt help
To learn more, read the Lightning-CLI section for command opt.
Amongst other motives, the ability to control if a node participates in the Network gives the operator a chance to shut it down gracefully at the end of the Epoch without incurring reputation penalties. For example, a node that opted in should actively participate, not down and unresponsive.
Therefore, to participate in the Network, a Node Operator must send a request via the command opt of the Lightning CLI. The options available are in, out and status.
To make an opt-in request, the operator should execute the command:
lgtn opt in
Upon success, the operator receives a confirmation text message about the node inclusion in the next Epoch.
To learn more about network participation visit the Opt section in the Lightning CLI page.
Start the node
To participate in the alpha Testnet, you have to through the onboarding process. Make sure you request access by following the onboarding instructions. If you fail to enable your node for testnet, it'll not run!
To start the node, you should execute the sub-command run. Noteworthy that while it launches the node, you're recommended to set up a systemd service to run it for a long period.
lgtn run
We recommend setting up the process as a systemd service, as it's a long-running process. Instructions to setup a systemd service are available in the section Systemd Service Setup.
Great! You have successfully installed all the required packages, and libraries and have compiled and installed lightning. Check the section Health Check to learn how to do a node health checkup.
Systemd Service Setup
Create a new Systemd service file:
sudo touch /etc/systemd/system/lightning.service
Open the file and put the following content:
[Unit]
Description=Fleek Network Node lightning service
[Service]
Type=simple
MemoryHigh=32G
RestartSec=15s
Restart=always
ExecStart=lgtn -c /home/lgtn/.lightning/config.toml -vv run
ExecStop=killall -9 lgtn
StandardOutput=append:/var/log/lightning/output.log
StandardError=append:/var/log/lightning/diagnostic.log
Environment=TMPDIR=/var/tmp
[Install]
WantedBy=multi-user.target
Notice that we're using lgnt as the username. If you have a different custom username change it accordingly. Beware that we've recommended using a non-root user, as described in the section create a user.
The flag -c in the lightning.service ExecStart, is to provide the toml configuration file path e.g. defaults to ~/.lightning/config.toml. This is to avoid the path being determined dynamically (given path base ~ or $HOME), as users might control the systemctl service as a user or sudoer. For example, a sudoer would have the configuration set to /root/.lightning/config.toml or /home/username/.lightning/config.toml depending on using sudo which might cause some confusion to some users.
Change the file permissions for the service:
sudo chmod 644 /etc/systemd/system/lightning.service
After creating the service file, you should reload the Systemd process, to apply the newly created service. You can do this by executing:
sudo systemctl daemon-reload
To start the service at boot, use the enable command:
sudo systemctl enable lightning.service
Create the directory where the log message will be stored, as follows:
sudo mkdir -p /var/log/lightning
You may want to create empty placeholders for the stdout and stderr log files:
sudo touch /var/log/lightning/output.log
sudo touch /var/log/lightning/diagnostic.log
We're assuming that you've created a new user and can start the service operating without sudo.
Start the service by:
sudo systemctl start lightning.service
Find the timeline of events for the Lightning service by checking the log files. Learn about it in the section Log Messages.
To learn more, visit the section Use Systemctl to manage the Lightning Service
Docker installation
In this section we'll describe how to run a Fleek Network Lightning Node as a Docker Service. We're going to assume that you have Docker installed and running. If you need help to install Docker, check the guide running a node in docker.
a) We can easily pull and run the Lightning Docker image from our registry to run the Docker Container quickly.
b) Build the Docker image from the repository source code
Optionally, wrap the Docker Container as a Systemd Service.
The Docker images are built for particular CPU architectures (x64) and as declared in the requirements, we're mainly supporting GenuineIntel, as there has been reports of failure to build and run the binary on AMD. If you're running on a AuthenticAMD, provide us feedback on our Discord.
Quick pull and run
You can pull and run the Lightning pre-built Docker image from our GitHub and run the Docker container quickly.
First, create the ~/.lightning in the host, which will be bound to the container, as follows:
mkdir $HOME/.lightning
After, execute the following command:
sudo docker run \
-e OPT="in" \
-p 4200-4299:4200-4299 \
-p 4300-4399:4300-4399 \
--mount type=bind,source=$HOME/.lightning,target=/home/lgtn/.lightning \
--mount type=bind,source=/var/tmp,target=/var/tmp \
--name lightning-node \
-it ghcr.io/fleek-network/lightning:latest
The command has a list of ports -p values that map ports in the container on the Docker host. While we try to keep the information across our documentation in sync with the latest changes or requirements e.g. port number changes, make sure that you check the section ports to find the latest updates.
Build from source
Clone the repository located at https://github.com/fleek-network/lightning.
You have several ways of doing this:
- Clone via HTTPS
- Clone via SSH
- Download via Github CLI
- Download the zip package from the repository
We recommend HTTPS because it is the easiest to set up in the wild, and by users who are new to all this. Although, we strongly recommend using an SSH connection when interacting with GitHub. If you are to this and are interested read more about it here.
git clone -b testnet-alpha-1 https://github.com/fleek-network/lightning.git <DIRECTORY-NAME>
At time of writing, we are checking the branch name testnet-alpha-1 that corresponds to the testnet phase.
Here's an example of what it'd look like when sticking to the recommended path location:
git clone -b testnet-alpha-1 https://github.com/fleek-network/lightning.git ~/fleek-network/lightning
Change directory to the project source code directory, e.g. the default ~/fleek-network/lightning.
cd ~/fleek-network/lightning
Build the image named as lightning from our Dockerfile:
sudo docker build -t lightning -f ./Dockerfile .
Take note of the Docker image name lightning, as that's the name we'll use and pass to the Docker run to be successful. You can name it differently if that's your preference.
Once the image is built, you can launch the Docker Container with a --name such as lightning-node from the lightning image we just created by running:
sudo docker run \
-e OPT="in" \
-p 4200-4299:4200-4299 \
-p 4300-4399:4300-4399 \
--mount type=bind,source=$HOME/.lightning,target=/home/lgtn/.lightning \
--mount type=bind,source=/var/tmp,target=/var/tmp \
--name lightning-node \
-it lightning
The command has a list of ports -p values that map ports in the container on the Docker host. While we try to keep the information across our documentation in sync with the latest changes or requirements e.g. port number changes, make sure that you check the section ports to find the latest updates.
If a ~/.lightning directory or ~/.lightning/keystore doesn't exist, one is created for you on docker run. You'll need to have the directory populated with the config.toml and keystore if you want to use a particular identity. Learn more about managing the keystore here.
Docker Container as a Systemd Service
Create a unit configuration file:
sudo touch /etc/systemd/system/docker-lightning.service
Open the docker-lightning.service file in your favourite text editor and put the content:
[Unit]
Description=Fleek Network Node lightning service
After=docker.service
Requires=docker.service
[Service]
Restart=always
RestartSec=5
TimeoutStartSec=0
ExecStartPre=-/usr/bin/docker kill lightning-node
ExecStartPre=-/usr/bin/docker rm lightning-node
ExecStartPre=/usr/bin/docker pull ghcr.io/fleek-network/lightning:latest
ExecStart=/usr/bin/docker run -e OPT="in" -p 4200-4299:4200-4299 -p 4300-4399:4300-4399 --mount type=bind,source=/home/skywalker/.lightning,target=/home/lgtn/.lightning --mount type=bind,source=/var/tmp,target=/var/tmp --name lightning-node ghcr.io/fleek-network/lightning:latest
ExecStop=/usr/bin/docker stop lightning-node
StandardOutput=append:/var/log/lightning/output.log
StandardError=append:/var/log/lightning/diagnostic.log
[Install]
WantedBy=multi-user.target
Change the file permissions by running the command:
sudo chmod 644 /etc/systemd/system/docker-lightning.service
Next, reload the Systemctl Daemon:
sudo systemctl daemon-reload
Enable the service on startup when the system boots:
sudo systemctl enable docker-lightning.service
Learn how to manage the Systemd Service by reading the section systemd service.
Frequently Used Commands (Quick Reference)
A quick reference of the most Frequently Used Commands are available for Native and Docker setups. If you'd like a more in depth explanation of the commands, check the health check, analyzing logs, systemd service and guides sections separately.
