Pool Server Setup

Pool Server Setup

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. This could be 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 the setup process you might want to check to make sure your network supports port forwarding natively. To do this, start by finding your public IP address. Most search engines like Google will provide this information if you search "What is my IP?". Next, open your command prompt (cmd on Windows). Type the command tracert X.X.X.X replacing the X's with your public IP address. Trace route (or tracert)will show the "hops" from your location to another IP address. If there is only one "hop" or line then your should be able to use port forwarding. If you see more than one "hop", then you should contact your ISP before proceeding.

Example:

tracert [your_ip_address]

Expected Result:

1 <1 ms <1 ms <1 ms 199-119-153-199-119-153-27.cpe.sparklight.net [199.118.152.28]

(the numbers don't matter, but you should only have 1 line)

Create Pool Server Config

If the player is a node owner, then they should be able to see a section in the UI for managing their pool servers. Click on the link to manage pool servers, and click “Create Pool Server”.

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.

In order to delegate a node, go to the Node section of the player account, and choose a node that has not been delegated. Click the button that says delegate node. When a dialog box appears, it should allow the selection of available pools. Choose a pool and click ok.

Installing Docker

Docker is the chosen technology to roll out the pool server technology. This was chosen for several reasons:

  1. Isolation: docker runs containers that will not allow host applications to affect the container and the container cannot negatively affect the host applications.

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

  3. Platform choice: Docker can run on Windows, Linux, and Mac. It can also run on many NAS devices and on many cloud servers. Note: Cornucopias will not test every platform. Stick with Windows and Linux for the best support. We will not prevent the images to be run in other configurations. However, 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 will run on Linux and Mac. Follow these instructions for Mac and Desktop Linux.

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 the command docker ps should return an empty set 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.

If running in the AWS cloud, configure the security group to allow tcp access to port 8001/tcp.

The following are some videos 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:

  1. Which drive contains enough free space? There could be 100G of cache files as the project starts getting up to speed.

  2. Drive speed can be important. NVMe drives are much faster thanIt would be nice if the storage was on a fast drive such as an NVME. However, using a spinning drive might make the most sense. Note that the validation of cache files will take long on these drives. This will not be a long term issue because it is on the roadmap to fix.

Now that the cache folder is chosen, the container can be started.

Starting the Container

There are various ways that the container can be managed. A long command on the terminal or creating the container in the desktop application are both options that have been considered. The long command is too error prone, and believe it or not, the desktop creation of the container is cumbersome and error prone as well. Docker compose is the strategy that is the best solution for giving and receiving instructions for how to run this container. How about some terminology?

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 uses a file called docker-compose.yml. Call this the docker compose file or the yaml file. This is just the phonetic way to refer to the 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.

Environmental Variables

Variable

Value

Description

FILENODES_POOL_API_URL

https://filenodes.api.conucopiasweb.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 environmental variable if the IP is not determined correctly by the filenodes service.

FILENODES_POOL_PUBLIC_PATH

cache

Not Recommended: Use this environmental variable to change the base URL path to access cached files.

Docker Compose Configuration

The following is an example docker compose configuration. Please create a folder on your computer that will have plenty of free disk space (100G-250G), and create the file “docker-compose.yml”. Copy and paste the template below, and carefully update the access key, public url, and cache path. Save the file and move to starting the container.

Step by Step Docker Configuration

Each will be discussed in the step by step approach for deploying a pool server.

  1. Create a working folder. For example: “D:\CornPoolServer”.

    1. Open up explorer to where you would like to create your working folder.

    2. Right click in the open space and select new, then folder.

    3. Name your folder then hit enter.

    4. Double click on the folder to go into that newly created folder.

  2. Create a folder inside that folder for the pool server cache. For example: “D:\CornPoolServer\cache”

    1. Right click in the open space and select new, then folder.

    2. Name your folder(cache) then hit enter.

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

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

  4. Copy and paste the docker compose template below into the docker-compose.yml file. Note: indentation and spacing matter.

  5. Should the container always restart? For testing or manual management, change the restart value to “no”.

  6. Update the access key. Copy and paste the access key that was provided.

  7. Ensure that the public port matches port forward port.

  8. 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:/cache

Starting Docker

Starting docker is pretty easy. Do not get intimidated by using the command line. Ask for help.

Open powershell or cmd.

Change to working folder:

Start pool server using the command “docker compose up -d”

PreviousIntroductionNextUpdating and Verifying Pool Server

Last updated