{"id":18375771,"url":"https://github.com/factomproject/factomd-authority-toolkit","last_synced_at":"2025-04-06T20:31:12.138Z","repository":{"id":50206621,"uuid":"132811151","full_name":"FactomProject/factomd-authority-toolkit","owner":"FactomProject","description":null,"archived":false,"fork":false,"pushed_at":"2022-12-08T02:11:04.000Z","size":79,"stargazers_count":2,"open_issues_count":2,"forks_count":6,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-03-22T06:26:27.138Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FactomProject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-09T20:47:17.000Z","updated_at":"2021-11-23T22:11:52.000Z","dependencies_parsed_at":"2023-01-25T03:15:22.322Z","dependency_job_id":null,"html_url":"https://github.com/FactomProject/factomd-authority-toolkit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FactomProject%2Ffactomd-authority-toolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FactomProject%2Ffactomd-authority-toolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FactomProject%2Ffactomd-authority-toolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FactomProject%2Ffactomd-authority-toolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FactomProject","download_url":"https://codeload.github.com/FactomProject/factomd-authority-toolkit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247547304,"owners_count":20956531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T00:20:17.397Z","updated_at":"2025-04-06T20:31:11.878Z","avatar_url":"https://github.com/FactomProject.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Factomd Control Plane\n\nThis repository is responsible for maintaining the control plane for factomd M3.\n\nIt includes 3 containers:\n  1. Factomd\n  \u003e Runs the factom node\n  2. SSH\n  \u003e Permits ssh access only to _this specific container_. Mounts the factomd database volume for debugging purposes.\n  3. Filebeat\n  \u003e Reports stdout/stderr of all docker containers to our elasticsearch instance\n\n# Install docker\n\nPlease follow the instructions [here](https://docs.docker.com/install/linux/docker-ce/ubuntu/) to install docker-ce to your machine. If you run Ubuntu 18.04 you can use the docker.io package `sudo apt-get install docker.io` as it's recent enough to support swarm and iptables without modification.\n\nThen, run `usermod -aG docker $USER` and make sure you do logout/login, as otherwise your current terminal session will not be updated.\n\n\n# Configure Docker\n\nIn order to join the swarm, first ensure that your firewall rules allow access on the following ports. All swarm communications occur over TLS using a self-signed TLS certificate. Due to the way iptables and docker work you cannot use the `INPUT` chain to block access to apps running in a docker container as it's not a local destination but a `FORWARD` destination. By default when you map a port into a docker container it opens up to `any` host. To restrict access we need to add our rules in the `DOCKER-USER` chain [reference](https://docs.docker.com/network/iptables/).\n\n- TCP port `2376` _only to_ `18.203.51.247` for secure Docker engine communication. This port is required for Docker Machine to work. Docker Machine is used to orchestrate Docker hosts. As this is a local service we use the `INPUT` chain.\n\nIn addition,  the following ports must be opened for factomd to function which we add to the `DOCKER-USER` chain:\n- `2222` to `18.203.51.247`, which is the SSH port used by the `ssh` container\n- `8088` to `18.203.51.247`, the factomd API port\n- `8090` to `18.203.51.247`, the factomd Control panel\n- `8108` to the world, the factomd mainnet p2p port\n\nAn example using `iptables`:\n```\nsudo iptables -A INPUT ! -s 18.203.51.247/32 -p tcp -m tcp --dport 2376 -m conntrack --ctstate NEW,ESTABLISHED -j REJECT --reject-with icmp-port-unreachable\nsudo iptables -A DOCKER-USER ! -s 18.203.51.247/32  -i \u003cexternal if\u003e -p tcp -m tcp --dport 8090 -j REJECT --reject-with icmp-port-unreachable\nsudo iptables -A DOCKER-USER ! -s 18.203.51.247/32  -i \u003cexternal if\u003e -p tcp -m tcp --dport 2222 -j REJECT --reject-with icmp-port-unreachable\nsudo iptables -A DOCKER-USER ! -s 18.203.51.247/32  -i \u003cexternal if\u003e -p tcp -m tcp --dport 8088 -j REJECT --reject-with icmp-port-unreachable\n```\n\n(Replace `\u003cexternal if\u003e` with the name of the interface you use to connect to the internet eg. eth0 or ens0. To see interfaces use `ip addr list`)\n\nDon't forget to [save](https://www.digitalocean.com/community/tutorials/iptables-essentials-common-firewall-rules-and-commands#saving-rules) the rules!\n\n# Store Docker Swarm certificate and key\nMake sure you store the Docker Swarm mainnet key and certificate on your system. The files can be found at [here](https://github.com/FactomProject/factomd-authority-toolkit/tree/master/tls)\nYou can store these files in the directory /etc/docker for instance:\n```\nsudo mkdir -p /etc/docker\nsudo wget https://raw.githubusercontent.com/FactomProject/factomd-authority-toolkit/master/tls/cert_exp_9-12-24.pem -O /etc/docker/factom-mainnet-cert_exp_9-12-24.pem\nsudo wget https://raw.githubusercontent.com/FactomProject/factomd-authority-toolkit/master/tls/key_exp_9-12-24.pem -O /etc/docker/factom-mainnet-key_exp_9-12-24.pem\nsudo wget https://raw.githubusercontent.com/FactomProject/factomd-authority-toolkit/master/tls/ca_exp_9-12-24.pem -O /etc/docker/factom-mainnet-ca_exp_9-12-24.pem\nsudo chmod 644 /etc/docker/factom-mainnet-cert_exp_9-12-24.pem\nsudo chmod 440 /etc/docker/factom-mainnet-key_exp_9-12-24.pem /etc/docker/factom-mainnet-ca_exp_9-12-24.pem\nsudo chgrp docker /etc/docker/*.pem\n```\nThe last command `sudo chgrp docker /etc/docker/*.pem` might fail if docker service is run as root. This is not a probem, as root should be able to run them anyway.\n\nPlease note that in the rest of this file we assume you stored the files using the /etc/docker location and with above names. If not please adjust the commands below involving the certificate and keys.\n\n# Configure and Run the Docker Engine\n\nThere are a number of ways to run `dockerd` and two effectively mutually\nexclusive ways to configure `dockerd`. The ways to run `dockerd` are discussed\nbelow, but it is also important to understand the two ways that it can be\nconfigured.\n\n## Choose one of the following options for configuring `dockerd`\nYou can either use the `/etc/docker/daemon.json` file to specify `dockerd`\noptions, or you can specify options on the command line. Note that while these\nmethods can be used together, *if the same option is specified in both\nlocations, `dockerd` will fail to start even if the options agree*. For this\nreason it is best to either specify all options on the command line or all\noptions in `/etc/docker/daemon.json`.\n\n### 1. Using `daemon.json` (recommended)\n\nYou can configure the docker daemon using a default config file, located at\n`/etc/docker/daemon.json`. Create this file if it does not exist.\n\nExample configuration:\n```\n{\n  \"tlsverify\": true,\n  \"tlscert\": \"/etc/docker/factom-mainnet-cert_exp_9-12-24.pem\",\n  \"tlskey\": \"/etc/docker/factom-mainnet-key_exp_9-12-24.pem\",\n  \"tlscacert\":\"/etc/docker/factom-mainnet-ca_exp_9-12-24.pem\",\n  \"hosts\": [\"tcp://0.0.0.0:2376\", \"unix:///var/run/docker.sock\"]\n}\n```\nAs noted above, please make sure that you do not also specify any of these\noptions on the command line for `dockerd`. Please make sure to specify the\ncorrect paths for `\"tlscert\"`, `\"tlskey\"`, and `\"tlscacert\"`. If you are using `systemd` to run\nthe `docker.service` you will need an additional host in your host list:\n`\"fd://\"`. See `systemd` below.\n\n### 2. Options on the command line\n\nFor the same options as described above, you would use the following command\nline options:\n\n```\ndockerd -H=unix:///var/run/docker.sock -H=0.0.0.0:2376 --tlsverify --tlscacert=/etc/docker/factom-mainnet-ca_exp_9-12-24.pem --tlscert=/etc/docker/factom-mainnet-cert_exp_9-12-24.pem --tlskey=/etc/docker/factom-mainnet-key_exp_9-12-24.pem\n```\n\n## Choose one of the following 3 options for starting dockerd\nRemeber that if you specify an option on the command line, you can't have the\nsame option in your `/etc/docker/daemon.json` file.\n### 1. On RedHat\n\nOpen (using `sudo`) `/etc/sysconfig/docker` in your favorite text editor.\n\nAppend `-H=unix:///var/run/docker.sock -H=0.0.0.0:2376 --tlsverify --tlscacert=/etc/docker/factom-mainnet-ca_exp_9-12-24.pem --tlscert=/etc/docker/factom-mainnet-cert_exp_9-12-24.pem --tlskey=/etc/docker/factom-mainnet-key_exp_9-12-24.pem` to the pre-existing OPTIONS\n\nThen, `sudo service docker restart`.\n\n### 2. Using `systemd`\n\nRun `sudo systemctl edit docker.service`. This creates an override directory at\n`/etc/systemd/system/docker.service.d/` and an override file called\n`override.conf`. Alternatively, you can create this directory and file manually\nand you can give the file a more descriptive name so long as it ends with\n`.conf`.\n\nEdit the override file to match this:\n```\n[Service]\nExecStart=\nExecStart=/usr/bin/dockerd\n```\nand make sure that you add `\"fd://\"` to the `\"hosts\"` array in\n`/etc/docker/daemon.json` if you are using it for your config.\n\nIf you are *not* using `/etc/docker/daemon.json` use the following for your\nservice file override.\n```\n[Service]\nExecStart=\nExecStart=/usr/bin/dockerd -H fd:// -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2376 --tlsverify --tlscacert=/etc/docker/factom-mainnet-ca_exp_9-12-24.pem --tlscert=/etc/docker/factom-mainnet-cert_exp_9-12-24.pem --tlskey=/etc/docker/factom-mainnet-key_exp_9-12-24.pem\n```\nThen reload the configuration and the `docker.service`\n```\nsudo systemctl daemon-reload\nsudo systemctl restart docker.service\n```\n\n### 3. I don't want to use a process manager\n\nYou can manually start the docker daemon via:\n\n```\nsudo dockerd -H=unix:///var/run/docker.sock -H=0.0.0.0:2376 --tlsverify --tlscacert=/etc/docker/factom-mainnet-ca_exp_9-12-24.pem --tlscert=/etc/docker/factom-mainnet-cert_exp_9-12-24.pem --tlskey=/etc/docker/factom-mainnet-key_exp_9-12-24.pem\n```\nor just\n```\nsudo dockerd\n```\nif you are using the `/etc/docker/daemon.json` file for configuration.\n\n## Troubleshooting\n\nIf `dockerd` fails to start review the error output carefully. It generally\ntells you exactly what the problem is.\n\nIf you are using systemd and the service fails to start, finding the relevant\nlogs can be a challenge since the service is configured to just keep restarting\nwhich can bury the logs.\n\nIn this case, stop the service: `sudo systemctl stop docker`.\n\nThen manually start `dockerd`: `sudo dockerd`\n\nYou will then be able to see the `dockerd` output which should point you at the\nproblem. Fix those and then try starting the service with systemd again.\n\n# Create the Factomd volumes\nFactomd relies on two volumes,`factom_database` and `factom_keys`. Please create these before joining the swarm.\n\n1. `docker volume create factom_database`\n2. `docker volume create factom_keys`\n\nThese volumes will be used to store information by the `factomd` container.\n\nFor running a mainnet authority node we strongly recommend syncing the database from scratch. If you do already have a recently synced mainnet node and would like to avoid resyncing, run:\n\n`sudo cp -r \u003cpath to your database\u003e /var/lib/docker/volumes/factom_database/_data`.\n\nThe directory in `_data` after the copy should be `main-database`, as the volume is mounted at `$HOME/.factom/m2`.\n\nIn addition, please place your `factomd.conf` file in `/var/lib/docker/volumes/factom_keys/_data`. An example factomd.conf can be found [here](https://raw.githubusercontent.com/FactomProject/factomd/master/factomd.conf)\n\n# Join the Docker Swarm\n\nFinally, to join the swarm:\n```\ndocker swarm join --token SWMTKN-1-5ct5plmbn1ombbjqp8ql8hq93jkof6246suzast5n1gfwa083b-1ui6w6fupe45tizz0tv6syzrs 18.203.51.247:2377\n\n```\n\nAs a reminder, joining as a worker means you have no ability to control containers on another node.\n\nOnce you have joined the network, you will be issued a control panel login by a Factom employee after messaging one of the Factom engineers on discord. You should private message the following for **each** node:\n- NodeID (`docker info`)\n- IP Address\n- Docker engine listening port (`2376`)\n\n**Only accept logins at federation.factomd.com. Any other login endpoints are fraudulent and not to be trusted.**\n\n# Starting Factomd Container from the Docker CLI\n\nPlease note: There is a version for the Factom software in the next command. Make sure you run the correct and latest announced version from the Discord #operators-announcement channel\n\nRun this command _exactly_: `docker run -d --name \"factomd\" -v \"factom_database:/root/.factom/m2\" -v \"factom_keys:/root/.factom/private\" -p \"8088:8088\" -p \"8090:8090\" -p \"8108:8108\" -l \"name=factomd\" factominc/factomd:v5.2.0-alpine -startdelay=600 -faulttimeout=120 -config=/root/.factom/private/factomd.conf\n`\nAfter this your node will be started. You can check for the existence of a factom container using the command `docker ps`\nPlease wait for your node to be fully synced by checking the control panel node sync statuses to be 100% before performing any next steps. Please also regard the initial wait period of 20 minutes before doing anything with your node.  Also note that the factomd:v5.X.X-alpine version may have changed since the time of writing.\n\n### NOTE: The Swarm cluster is still experimental, so please pardon our dust! If you have an issues, please contact ian at factom dot com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffactomproject%2Ffactomd-authority-toolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffactomproject%2Ffactomd-authority-toolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffactomproject%2Ffactomd-authority-toolkit/lists"}