Deploys and configures the Bitcoin Core daemon, bitcoind.
This role has been written in a way so that Bitcoin forks and altcoins can be supported, but does not currently support any others yet.
If you already have Ansible installed and are pretty familiar with it, then:
ansible-galaxy install idolactivities.coind --force
ansible-playbook -i your.server.fqdn, ~/.ansible/roles/idolactivities.coind/examples/playbook_bitcoin.yml
Refer to that playbook for more information. You'll likely want to create your own playbook (and store secrets using Ansible Vault or something).
If you don't have a server, you can also use Vagrant:
# after following the installation step from earlier...
cd ~/.ansible/roles/idolactivities.coind/
vagrant up
The bitcoind running in that VM will be accessible from your machine, so you
can use bitcoin-cli if you have it installed:
bitcoin-cli -testnet=1 -rpcuser=apiuser -rpcpassword=apipass getnetworkinfo
If you are interested in contributing to this role, you may want to use the following setup for testing changes with Vagrant locally.
# Your clone method may differ (e.g. if you forked this repository)
git clone [email protected]:idolactivities/ansible-role-coind.git
cd ansible-role-coind/
mkdir -p ~/.ansible/roles/
ln -s $PWD ~/.ansible/roles/idolactivities.coind
We're effectively installing the Ansible role here, but it'll stay up to date with any local modifications.
To bring up the development VM, use Vagrant with your favourite provider:
vagrant up # brings up the VM and runs the playbook specified in the Vagrantfile
vagrant provision # runs the playbook only, requires VM to be up
vagrant destroy # stops and deletes the VM
Depending on what you're changing, you may want to write another playbook under
examples/ and update the Vagrantfile to use that playbook.
If you're lost, you may want to review the content within the examples/
directory to get an idea of how to write your own playbook.
All of these role variables are completely optional (at least, at this point in time) for a working installation, but you'll likely want to set a few.
coind_name: bitcoin
Specifies which coin's software to deploy. Currently, only bitcoin is
supported, but support for other coins will be implemented in due time.
coind_install_cli: no
Specifies whether or not to install the CLI utility on the destination host. This should only be necessary if you plan to SSH into the host and interact directly with the coin's RPC API using it.
coind_user: "{{ coind_name }}"
coind_group: "{{ coind_user }}"
coind_home: "/var/lib/{{ coind_name }}"
Specifies the user to run the coin software as (by default, the name of the coin itself) and the location of its block database, etc.
coind_url: "{{ _coind_urls[coind_name] }}"
coind_version: "{{ _coind_latest_version[coind_name] }}"
coind_sha256sum: "{{ _coind_sha256sums[coind_name][coind_version] }}"
Specifies where to download the release tarball from, which version to use, and
the SHA256 sum of that tarball. These are by default defined in variables in
vars/main.yml so you can validate these yourself, but you can easily just
override these with your own.
coind_offline_install: no
coind_offline_artifact_path: "~/.cache/ansible/{{ coind_name }}"
coind_offline_artifact_tarball: "{{ coind_offline_artifact_path }}/{{ coind_name }}-{{ coind_version }}.tar.gz"
For hosts with limited Internet access, you may want to download release
tarballs locally first and then push those files to the host. Set
coind_offline_install to yes to enable this. The artifact_path here is
where Ansible will download the tarballs locally, so make sure you have
permission to create/read it, and artifact_tarball is the path to the tarball
itself. The role does verify hashes in either situation.
coind_binary: "{{ _coind_binary[coind_name] }}"
coind_binary_cli: "{{ _coind_binary_cli[coind_name] }}"
These are the binary names of the coin daemon and CLI utility and are by
default defined in vars/main.yml. They're typically in the form of
{{ coind_name }}d and {{ coind_name }}-cli.
coind_config_global: {}
coind_config_main: {}
coind_config_test: {}
coind_config_regtest: {}
These get templated into the coin's configuration file and are typically
key-stringvalue dictionaries. The global config is where most configuration
options will typically fall into, but there are a few options that by default
only apply to mainnet and must be defined in their own section to be applied to
testnet/regtest (e.g. port, rpcbind).
For a list of configuration options, refer to the official documentation of the
coin that you are deploying. Note that the configuration file also accepts most
command line flags as well, so place any of those here. There is also an
example in the defaults/main.yml file that may prove useful.