Helpful Skills
Running a pool server will require some advanced technical knowledge. The following are some of the skills that may be required in running a successful pool server:
- General docker understanding. (https://docker.com)
- Running commands on the command line, on Windows or Linux.
- Understanding of general networking, firewalls, and internet router configurations.
- Looking at logs of data events to help with troubleshooting.
Before Starting
Before starting, check that your network supports port forwarding natively. The check takes a minute and is described under Check Your Network First on the first page of this guide. If it shows more than one "hop", contact your internet provider before going further.
Create Pool Server Config
A node owner’s player account has a section for managing pool servers: Manage Pools. Open it and click “Create Pool”.
Enter the name of the pool. The name of the pool should be a concise description of the pool. This is especially important if the player will likely be running multiple pool servers and even running one or more public servers.
Once the pool server is created, a secret access key will be presented. This key will be used in running the pool server. This is how the pool server software will know its configurations and provide performance information for its nodes that will yield rewards. Store this key in a safe place.
Refreshing Pool Server Access Key
The pool access key does need to be kept secret, but if there is any reason that a node owner suspects that the key has been compromised, go to the pool management section of the player account. Click to see the details of the pool server in question. Click on the button to refresh the access key. The access key will be shown one time only. It is recommended that the access key be replaced in the docker-compose.yml configuration immediately since the old access key will no longer work. Once the configuration is updated, restart the docker container with the command docker compose up -d .
Delegate File Node
The last step in creating a new pool server is to delegate a node. It is possible to run a pool server without a node. However, no work will be allocated to the pool unless at least one node is delegated to the pool.
To delegate a node, open Manage Nodes in your player account, pick a node that has not been delegated and click its delegate button. The delegation wizard lists the available pools, including your own; choose your pool and confirm. Node Delegation walks through each step.
Installing Docker
The pool server is delivered as a Docker image. Docker was chosen for several reasons:
- Isolation: docker runs containers that will not allow host applications to affect the container and the container cannot negatively affect the host applications.
- Ease of configuration: Most of the setup and configuration is done when the image is created. To containerize the image, only a few variables need to be set to get the docker to work as expected.
- Platform choice: Docker runs on Windows, Linux and Mac, on many NAS devices and on many cloud servers. Note: Infinity Rising does not test every platform. Stick with Windows or Linux for the best support. The images will run in other setups, but watch your performance metrics.
Windows
Running docker on windows is best facilitated using docker desktop. Use the following URL to download and install the tool. If you are new to docker, there should be a lot of information available to give you confidence that it is a safe and useful tool.
https://www.docker.com/products/docker-desktop/
Docker Desktop also runs on Mac and desktop Linux; the same page has installers for both.
Linux
Running docker on Linux might be a little more complicated. It is possible to run Docker Desktop on desktop Linux. However, these instructions will focus on a command line installation of docker engine. Think of this as the “server” approach. These instructions will help to deploy to home linux servers and cloud servers. Obviously, there are many distributions and versions of Linux, and this document is not meant to be exhaustive. Instead, refer to the docker documentation for latest information on installing docker engine.
https://docs.docker.com/engine/install/
Once the installation is complete, running docker ps should return an empty list of running containers.
Creating Public Access
Creating public access to a pool server might be the trickiest part of this setup. It is important to make this right because it might open up your private network to the public Internet. Do this at your own risk. Also, please only forward necessary ports to your internal host. Redirecting all Internet traffic to an internal host is NOT recommended. (Some routers may have this option)
First, determine the public port number. If running behind a NAT (like at home), configure port forwarding for port 8001/tcp on the router. The port should be forwarded to the internal ip address that the pool server is running on and port 8001/tcp. For example, configure 8001/tcp on the router to forward to 192.168.1.22 port 8001/tcp. Note that some networks may change the internal IP address unexpectedly, so it is best practice to configure the internal host to have a static IP address.
The IP address and ports may differ in various configurations, and the pool server configuration should be able to accommodate many different configurations.
On a cloud server, allow TCP access to port 8001 in its firewall. On AWS, that is the instance’s security group.
The following is a video that might help setting up a port forward.
Choosing Cache Storage
Choose a location on the computer that can hold all of the cache files. Here are some of the considerations:
- Which drive has enough free space? The cache is 100 GB by default and can be set higher with
FILENODES_POOL_MAX_CACHE_SIZE, described below. - Drive speed matters. A fast drive such as an NVMe is ideal, though a spinning drive may make the most sense for the space. Note that validating cache files takes longer on a spinning drive.
Now that the cache folder is chosen, the container can be started.
Starting the Container
There are several ways to run the container. A long command in the terminal and creating the container in the desktop application were both considered: the long command is error prone, and creating the container in the desktop application is cumbersome and error prone too. Docker Compose is the best way to give and follow instructions for running this container. Some terms first:
Docker Image: An image is the template for which a container will run. All of the software and dependencies have been packaged up and downloaded as an image.
Docker Container: A container is an image that has been run. Once an image has been run, it creates a state, and that state is stored as a container. If a new image is available, a container needs to be recreated in order to take advantage of the updated image.
YAML: Docker Compose reads its settings from a file called docker-compose.yml, also called the compose file or the YAML file after its file type.
Before starting the container, take a look at the variables that need to be updated. These variables will be in the docker compose configuration file, and can be changed easily.
Environment Variables
| Variable | Value | Description |
|---|---|---|
FILENODES_POOL_API_URL | https://filenodes.api.cornucopiasweb.io | Not Recommended: This is the hostname that will be used to receive instructions. The hostname will change when moving from staging to production, for example. |
FILENODES_POOL_ACCESS_KEY | Unique key from pool server creation. Example: gvgA??????????????????????????????????????yJY | Each pool server will have its own unique key that authenticates and authorizes it for participation in the file nodes network. |
FILENODES_POOL_PUBLIC_PORT | 8001 | Each pool server will tell the API server how the client should access the files it is caching. This would be a public IP and port. |
FILENODES_POOL_PUBLIC_HOST | None | Not Recommended: Use this environment variable if the IP is not determined correctly by the filenodes service. |
FILENODES_POOL_PUBLIC_PATH | cache | Not Recommended: Use this environment variable to change the base URL path to access cached files. |
FILENODES_POOL_MAX_CACHE_SIZE | 100 | Maximum cache size in gigabytes (GB). Set based on your available disk space. |
FILENODES_POOL_CONCURRENT_DOWNLOADS | 1 | Number of simultaneous chunk downloads. Increase for faster cache population on high-bandwidth connections. Higher concurrency can help system pools retrieve the cache faster. The intent is for the propagation to be slow and steady. Keep it a 1 unless you have a specific need to download the cache faster. |
FILENODES_POOL_DOWNLOAD_BATCH_SIZE | 50 | Chunks downloaded and activated per batch. Larger batches reduce API calls but smaller batches make your chunks available to other pools sooner. Use the default. |
Docker Compose Configuration
The pool server is configured in a file named “docker-compose.yml”, kept in a folder on a drive with plenty of free space (100 GB to 250 GB). The steps below create that folder and file from the sample further down this page; you then set the access key, public port and cache path in it.
Step by Step Docker Configuration
Follow these steps to deploy a pool server.
- Create a working folder. For example: “D:\CornPoolServer”.
- Open up explorer to where you would like to create your working folder.
- Right click in the open space and select new, then folder.
- Name your folder then hit enter.
- Double click on the folder to go into that newly created folder.
- Create a folder inside that folder for the pool server cache. For example: “D:\CornPoolServer\Cache”
- Right click in the open space and select new, then folder.
- Name your folder (Cache) then hit enter.
- Do not double click on this folder for the next step. In the future, you may navigate to the folder to watch all of the cache files being created.
- Use a text editor or notepad to create a docker-compose.yml file inside the working folder. For example: “D:\CornPoolServer\docker-compose.yml” Note: If using notepad you will need to “save as”, then select “all files” and make sure the file name ends in .yml
- Copy and paste the docker compose template below into the docker-compose.yml file. Note: indentation and spacing matter.
- Should the container always restart? For testing or manual management, change the restart value to “no”.
- Update the access key. Copy and paste the access key that was provided.
- Make sure the public port matches the port you forwarded on your router.
- Configure the cache folder. Update the path of the mapping to the internal docker path with a filesystem path. For example: “D:\CornPoolServer\Cache:/cache”.
Sample docker-compose.yml with cache configured to path
name: cornucopias
services:
pool-server:
image: public.ecr.aws/cornucopias/nodes/pool-server:latest
ports:
- "8001:8001"
restart: unless-stopped # if you want to manually start the pool server replace “unless-stopped” with “no”
environment:
FILENODES_POOL_ACCESS_KEY: <PASTE ACCESS KEY HERE>
FILENODES_POOL_PUBLIC_PORT: 8001
volumes:
- D:\CornPoolServer\Cache:/cacheStarting Docker
Starting Docker is easy; do not be put off by the command line. If you get stuck, ask for help on Discord.
Open powershell or cmd.
Change to working folder:
Start pool server using the command “docker compose up -d”