embark-status-plugin
v1.0.0
Published
Embark-status is a plugin for [Embark](https://github.com/embark-framework/embark) that connects a DApp running in Embark to the [Status.im](https://github.com/status-im/status-react) mobile app. This plugin adds the Embark network (ie the blockchain node
Downloads
3
Readme
Embark-Status Plugin Setup
Embark-status is a plugin for Embark that connects a DApp running in Embark to the Status.im mobile app. This plugin adds the Embark network (ie the blockchain node spun up by Embark) to the Status.im app, connects the Status app to the node, then opens the DApp in the Status app's DApp browser.
Installation
In your DApp directory, install the embark-status plugin:
npm install status-im/embark-status --save-dev
NOTE: Please do not install
embark-status
directly from npm as this is a very old package. We are working with the package owner to get this updated as soon as possible. If you have already installed via npm, please uninstallembark-status
(npm uninstall embark-status
) before installing using the above command.
DApp configuration
Add this config in the DApp's embark.json
:
"plugins": {
"embark-status": {
"deviceIp": "your-device-ip",
"name": "MyDapp"
}
}
If your DApp is hosted (ie on decentralised storage like IPFS or Swarm), the plugin option dappUrl
can be specified to override the DApp URL that is opened in the Status DApp browser after embark-status
is connected to the Status app.
"plugins": {
"embark-status": {
"deviceIp": "your-device-ip",
"name": "MyDapp",
"dappUrl": "https://ipfs.io/ipfs/QmSVa32dFs5SKRmd7EXzuztMbNsZd5LGpCoU1keSrxo9BK"
}
}
Development environment
To configure for a development environment, please ensure you are running the correct version of NodeJS. Additionally, the blockchain client, webserver, and storage need to be set up to accept outside connections.
NodeJS Version
The minimum version of NodeJS that can be used is 8.11.3
. If you need to change your Node version, please use NVM.
$> node --version
v8.11.3
Blockchain client config
In your DApp, set config/blockchain.js > development > rpcHost
to 0.0.0.0
(macOS/Linux) or 127.0.0.1
(Windows). This will open up your blockchain client (Geth or Parity) to outside connections.
Webserver config
In your DApp, set config/webserver.js > host
to 0.0.0.0
(macOS/Linux) or 127.0.0.1
(Windows). This will open up your webserver to outside connections.
NOTE: When the Status browser opens the DApp, it will open the IP of the machine running Embark along with the port specified in the webserver config, ie
http://192.168.0.15:8000
. This is so that the device can connect to the webserver started by Embark.
Storage
Our machine will be running our storage node, and we need to access the node from our DApp, so we have to configure IPFS to run on our machine's IP, then tell embark to access the node via the machine IP.
NOTE:
embark-status
has only been tested with IPFS. This guide assumes you have ipfs installed and you are using it for your DApp.
DApp storage config
In your DApp, set config/storage.js > dappConnection
to
dappConnection: [
{
provider: "ipfs",
host: "your-machine-ip",
port: 5001,
getUrl: "http://your-machine-ip:8080/ipfs/"
}
]
IPFS config
Next, we need to update our IPFS API and gateway configuration.
Backup
First, let's backup our working IPFS config:
cp ~/.ipfs/config ~/.ipfs/config.bak
Run IPFS first
In order to interact with IPFS's config
CLI, we need IPFS to be running first (alternatively, ~/.ipfs/config
(macOS/Linux) can be manually updated with the changes):
ipfs daemon
Run IPFS CLI config update commands
Then run the following commands in a new shell, (replacing your-machine-ip
with your machine's IP):
ipfs config --json Addresses.API "\"/ip4/your-machine-ip/tcp/5001\""
ipfs config --json Addresses.Gateway "\"/ip4/your-machine-ip/tcp/8080\""
NOTE: In this case, we want the IPFS API and gateway to the be accessible from our machine's IP.
Stop IPFS daemon
In the first terminal where IPFS daemon is running, stop the IPFS daemon using Ctrl+c
.
When you need to revert your IPFS config
If you'd like to revert to the default settings, run the following two commands:
ipfs daemon
In a separate shell, run:
ipfs config --json Addresses.API "\"/ip4/127.0.0.1/tcp/5001\""
ipfs config --json Addresses.Gateway "\"/ip4/127.0.0.1/tcp/8080\""
Alternatively, you could overwrite your IPFS config with your backup:
mv ~/.ipfs/config.bak ~/.ipfs/config # overwrite the config
rm ~/.ipfs/config.bak # delete the backup
Or, another option is to delete your modified config, and re-init IFPS:
rm ~/.ipfs/config
ipfs init
The last option will recreate a fresh IPFS config for you.
Status.im app
Please make sure the Status app has development mode enabled. To enable development mode:
- Install Status mobile if not already done
- Open the app.
- Go to Profile (bottom right tab).
- Scroll to the bottom and tap the "Advanced" button.
- Enable the "Development mode" toggle
CORS
NOTE: The device IP specified in the plugin configuration above will be automatically added to CORS for the blockchain client (Geth/Parity) and the storage provider (IPFS/Swarm) when running Embark.
Now run Embark
Once all the above has been configured, run your DApp using Embark:
embark run
Known issues
Status app crashes
There is currently a bug in the Status app that crashes the app once the embark-status
plugin attempts to open the DApp in the Status DApp browser. Simply re-open the Status app after this crash. You may have to manually open the DApp for now:
- Tap the "+" in the top right of the Status app
- Tap "Open DApp"
- Enter
your-machine-ip:8000
for the URL.
IPFS CORS not updated correctly
Embark up to 4.0.0
is not updating IPFS CORS correctly, due to the need for IPFS to be restarted after update. This has been fixed in a PR, but has not been released yet. In the meantime, it's probably easiest to simply modify your IPFS config manually. Open up ~/.ipfs/config
(or equivalent in your OS), and edit both the API/Access-Control-Allow-Origin
and Gateway/Access-Control-Allow-Origin
sections to look like:
"Access-Control-Allow-Origin": [
"http://your-device-ip",
"http://your-machine-ip:8000",
"http://your-machine-ip:8080",
"http://0.0.0.0:8000",
"http://0.0.0.0:8545",
"ws://localhost:8546",
"http://embark"
]
If this is still not working for you, as a last resort, try updating both the API/Access-Control-Allow-Origin
and Gateway/Access-Control-Allow-Origin
to:
"Access-Control-Allow-Origin": [
"*"
]