CLI Interface¶
The alarm service ships with a command line interface that can be used to interact with the service in various ways.
Requirements¶
The ethereum-alarm-clock-client
python package requires some system
dependencies to install. Please see the pyethereum documentation for more
information on how to install these.
This package is only tested against Python 3.5. It may work on other versions but they are explicitely not supported.
This package is only tested on unix based platforms (OSX and Linux). It may work on other platforms but they are explicitely not supported.
Installation¶
The ethereum-alarm-clock-client
package can be installed using pip
like this.
$ pip install ethereum-alarm-clock-client
Or directly from source like this.
$ python setup.py install
If you are planning on modifying the code or developing a new feature you should instead install like this.
$ python setup.py develop
The eth_alarm
executable¶
Once you’ve installed the package you should have the eth_alarm
executable
available on your command line.
$ eth_alarm
Usage: eth_alarm [OPTIONS] COMMAND [ARGS]...
Options:
-t, --tracker-address TEXT The address of the RequestTracker contract
that should be used.
-f, --factory-address TEXT The address of the RequestFactory contract
that should be used.
--payment-lib-address TEXT The address of the PaymentLib contract that
should be used.
-r, --request-lib-address TEXT The address of the RequestLib contract that
should be used.
-l, --log-level INTEGER Integer logging level - 10:DEBUG 20:INFO
30:WARNING 40:ERROR
-p, --provider TEXT Web3.py provider type to use to connect to
the chain. Supported values are 'rpc',
'ipc', or any dot-separated python path to a
web3 provider class
--ipc-path TEXT Path to the IPC socket that the IPCProvider
will connect to.
--rpc-host TEXT Hostname or IP address of the RPC server
--rpc-port INTEGER The port to use when connecting to the RPC
server
-a, --compiled-assets-path PATH
Path to JSON file which contains the
compiled contract assets
--back-scan-seconds INTEGER Number of seconds to scan into the past for
timestamp based calls
--forward-scan-seconds INTEGER Number of seconds to scan into the future
for timestamp based calls
--back-scan-blocks INTEGER Number of blocks to scan into the past for
block based calls
--forward-scan-blocks INTEGER Number of blocks to scan into the future for
block based calls
--help Show this message and exit.
Commands:
client:monitor Scan the blockchain for events from the alarm...
client:run
repl Drop into a debugger shell with most of what...
request:create Schedule a transaction to be executed at a...
Rollbar Integration¶
Monitoring these sorts of things can be difficult. I am a big fan of the rollbar service which provides what I feel is a very solid monitoring and log management solution.
To enable rollbar logging with the eth_alarm
client you’ll need to do the
following.
- Install the python rollbar package.
*
$ pip install rollbar
- Run
eth_alarm
with the following environment variables set. *ROLLBAR_SECRET
set to the server side token that rollbar provides. *ROLLBAR_ENVIRONMENT
set to a string such as ‘production’ or ‘ec2-instance-abcdefg’`.
Running a server¶
The scheduler runs nicely on the small AWS EC2 instance size. The following steps should get an EC2 instance provisioned with the scheduler running.
1. Setup an EC2 Instance¶
- Setup an EC2 instance running Ubuntu. The smallest instance size works fine.
- Add an extra volume to store your blockchain data. 20GB should be sufficient for a short while (after April 2017) if storing the entire history, block-for-block, is not required. Otherwise, a much larger size should be used.
- Optionally mark this volume to persist past termination of the instance so that you can reuse your blockchain data.
- Make sure that the security policy leaves 30303 open to connections from the outside world.
2. Provision the Server¶
sudo apt-get update --fix-missing
sudo apt-get install -y supervisor
sudo apt-get install -y python3-dev python build-essential libreadline-gplv2-dev libncursesw5-dev libssl-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev python-virtualenv libffi-dev autoconf
3. Mount the extra volume¶
The following comes from the AWS Documentation and will only work verbatim
if your additional volume is /dev/xvdb
.
sudo mkfs -t ext4 /dev/xvdb
sudo mkdir -p /data
sudo mount /dev/xvdb /data
sudo mkdir -p /data/ethereum
sudo chown ubuntu /data/ethereum
Modify /etc/fstab to look like the following. This ensures the extra volume will persist through restarts.
#/etc/fstab
LABEL=cloudimg-rootfs / ext4 defaults,discard 0 0
/dev/xvdb /data ext4 defaults,nofail 0 2
Run sudo mount -a
If you don’t get any errors then you haven’t borked your
etc/fstab
4. Install Geth or Parity¶
Install the go-ethereum client.
sudo apt-get install -y software-properties-common
sudo add-apt-repository -y ppa:ethereum/ethereum
sudo apt-get update
sudo apt-get install -y ethereum
or install the parity client.
bash <(curl https://get.parity.io -Lk)
5. Install the Alarm Client¶
Install the Alarm client.
mkdir -p ~/alarm-0.8.0
cd ~/alarm-0.8.0
virtualenv -p /usr/bin/python3.5 env && source env/bin/activate
pip install setuptools --upgrade
pip install ethereum-alarm-clock-client==8.0.0b1
6. Configure Supervisord¶
Supervisord will be used to manage both geth
and eth_alarm
.
If you are using Go-Ethereum, put the following in /etc/supervisord/conf.d/geth.conf
[program:geth]
command=geth --datadir /data/ethereum --unlock 0 --password /home/ubuntu/scheduler_password --fast
user=ubuntu
stdout_logfile=/var/log/supervisor/geth-stdout.log
stderr_logfile=/var/log/supervisor/geth-stderr.log
autorestart=true
autostart=false
and the following in /etc/supervisord/conf.d/scheduler-v8.conf
[program:scheduler-v8]
user=ubuntu
command=/home/ubuntu/alarm-0.8.0/env/bin/eth_alarm --ipc-path /data/ethereum/geth.ipc client:run
directory=/home/ubuntu/alarm-0.8.0/
environment=PATH="/home/ubuntu/alarm-0.8.0/env/bin"
stdout_logfile=/var/log/supervisor/scheduler-v8-stdout.log
stderr_logfile=/var/log/supervisor/scheduler-v8-stderr.log
autorestart=true
autostart=false
If you are using Parity, put the following in /etc/supervisord/conf.d/parity.conf
[program:parity]
command=parity --db-path /data/ethereum --unlock <your-account-address> --password /home/ubuntu/scheduler_password
user=ubuntu
stdout_logfile=/var/log/supervisor/parity-stdout.log
stderr_logfile=/var/log/supervisor/parity-stderr.log
autorestart=true
autostart=false
and the following in /etc/supervisord/conf.d/scheduler-v8.conf
[program:scheduler-v8]
user=ubuntu
command=/home/ubuntu/alarm-0.8.0/env/bin/eth_alarm --ipc-path /home/ubuntu/.parity/jsonrpc.ipc client:run
directory=/home/ubuntu/alarm-0.8.0/
environment=PATH="/home/ubuntu/alarm-0.8.0/env/bin"
stdout_logfile=/var/log/supervisor/scheduler-v8-stdout.log
stderr_logfile=/var/log/supervisor/scheduler-v8-stderr.log
autorestart=true
autostart=false
7. Generate an account¶
For Go-Ethereum
$ geth --datadir /data/ethereum account new
For parity
$ parity account new
Place the password for that account in /home/ubuntu/scheduler_password
.
You will also need to send this account a few ether. A few times the maximum transaction cost should be sufficient as this account should always trend upwards as it executes requests and receives payment for them.
Don’t forget to back up the key file! Go-Ethereum should have put it in
/data/ethereum/keystore/
and Parity in
/home/ubuntu/.local/share/io.parity.ethereum/keys/
8. Turn it on¶
Reload supervisord so that it finds the two new config files.
sudo supervisord reload
You’ll want to wait for Go-Ethereum or Parity to fully sync with the network
before you start the scheduler-v8
process.
9. Monitoring¶
You can monitor these processes with tail
tail -f /var/log/supervisor/geth*.log
tail -f /var/log/supervisor/parity*.log
tail -f /var/log/supervisor/scheduler-v8*.log
10. System Clock¶
You might want to add the following line to your crontab. This keeps your system clock up to date. I’ve had issues with my servers drifting.
0 0 * * * /usr/sbin/ntpdate ntp.ubuntu.com