Hey Blockstackers!
If you’re using Linux to run Blockstack, this is a brief walk-through on how to get started. In this tutorial, I’m using Ubuntu 17.10. These instructions should work for most Debian-derived distros. Please let me know if there’s anything I can add to this to make it better!
1. Install Docker
If you alread have docker installed, then you can skip this step. Otherwise, you will need Docker installed for Blockstack to work. In Ubuntu, you can get it with:
$ sudo apt-get install docker.io
If the above worked, then you’re done! If not, then please see my post further down.
If you are not using Ubuntu, you may need to explicitly start Docker, using something like this:
$ sudo systemctl start docker
2. If you have installed blockstack before…
Check to see whether or not the folder ~/.blockstack exists already. This can be the case if you have already installed the browser, or installed the Blockstack CLI tools.
If you have a ~/.blockstack folder, you should move it out of the way:
$ mv ~/.blockstack ~/.blockstack.bak.$(date +%s)
3. Run the Linux Launch Script
You can find the Linux install script here.
Once you download the script, you can fetch the Blockstack Docker images. Sample execution:
$ cd ~/Downloads/
$ bash ./Blockstack-for-Linux-v0.20.1.sh pull
v0.20.1-browser: Pulling from blockstack/blockstack-core
f6fa9a861b90: Already exists
da7318603015: Already exists
6a8bd10c9278: Already exists
d5a40291440f: Already exists
bbdd8a83c0f1: Already exists
a3ed95caeb02: Already exists
b03257f84b55: Already exists
677219fe117b: Already exists
d8f140b393f1: Already exists
e9572be141d4: Already exists
Digest: sha256:4ef81086bf62db0ed56b3dd2f4435ace61e88b2dbdc52ef58e843e48c0e6a397
Status: Image is up to date for quay.io/blockstack/blockstack-core:v0.20.1-browser
v0.20.1: Pulling from blockstack/blockstack-browser
f6fa9a861b90: Already exists
da7318603015: Already exists
6a8bd10c9278: Already exists
d5a40291440f: Already exists
bbdd8a83c0f1: Already exists
a3ed95caeb02: Already exists
f0eed8246d65: Already exists
ec6732fa14f2: Already exists
3ee97b8d28a0: Already exists
684cf17c3537: Already exists
6b57ab123f0b: Already exists
bba95de1cc22: Already exists
835bd541d7d2: Already exists
e61649b9671b: Already exists
5ea4d49d4308: Already exists
5260c951460d: Already exists
681abe8d3c96: Already exists
4784dd5ea250: Already exists
Digest: sha256:3ba13666e5b790974e63e94dd6a3b9c16c474bba37a947aec47bf77c40477c0b
Status: Image is up to date for quay.io/blockstack/blockstack-browser:v0.20.1
Finally, you can start the browser!
You will be prompted for a Blockstack Core password. This is different from the 12-word password that will be used to own your names. You will need to enter it each time you run start.
Sample execution:
$ bash ./Blockstack-for-Linux-v0.20.1.sh start
IMPORTANT: This will be used to encrypt information stored within the containers
which may include private keys for your Blockstack wallet.
It is important that you remember this password.
This will be the password you use to "pair" your Blockstack Browser
with your Blockstack core node.
Legal characters:
letters (upper and lowercase), numbers, '_', and '-'
Password:
Repeat:
Wallet does not exist yet. Setting up wallet
Saving configuration to /root/.blockstack/client.ini
Wallet is encrypted using your password and stored at "/root/.blockstack/wallet.json", please make sure you create a backup.
{
"status": true
}
304e73f97dbe77523e74fa30087dba39cd2f40991db0ac1dcf2b4912e6847e75
Set BLOCKSTACK_DEBUG to 1
Re-exec as `"/usr/bin/python", "/usr/local/bin/blockstack", "api", "start", "--secrets", "3"`
[2017-11-08 02:09:51,206] [DEBUG] [spv:103] (9.140481081538304) Using mainnet
[2017-11-08 02:09:51,307] [DEBUG] [cli:419] (9.140481081538304) Load secrets from 3
[2017-11-08 02:09:51,353] [DEBUG] [client:95] (9.140481081538304) Connect to https://node.blockstack.org:6263
[2017-11-08 02:09:51,357] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "get_immutable_handler" method
[2017-11-08 02:09:51,359] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "put_immutable_handler" method
[2017-11-08 02:09:51,361] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "delete_immutable_handler" method
[2017-11-08 02:09:51,363] [WARNING] [storage:632] (9.140481081538304) Storage implementation is missing a "delete_mutable_handler" method
[2017-11-08 02:09:51,505] [WARNING] [dropbox:188] (9) Config file '/root/.blockstack/client.ini': section 'dropbox' is missing 'token'. Write access will be disabled
[2017-11-08 02:09:51,506] [DEBUG] [client:110] (9.140481081538304) Loaded storage drivers ['disk', 'gaia_hub', 'dropbox', 's3', 'blockstack_resolver', 'http', 'dht']
{
"status": true
}
2ede9c4f3248b160d28d4caa36781067cc61917ff60f963a3c89c6ef0fd8f43a
38622c2737d857679686fd58d05ed57f3ddef2963e895578c7b42444c9d6b475
ATTENTION: default value of option force_s3tc_enable overridden by environment.
...
4. Frequently Asked Questions
Are there any other dependencies?
You should have curl installed. It’s used by the Linux script.
What is the Blockstack Core password? Is that the same as my 12-word password?
No. The password you enter at the command prompt is used to encrypt the ~/.blockstack/wallet.json file. You should NOT use your 12-word passphrase that you enter into the browser.
Why is there a separate Blockstack Core password?
The Blockstack API daemon uses it to process name registrations. The file ~/.blockstack/wallet.json is the wallet it uses to do so. This wallet is NOT the same as the one in the browser.
What if I forget the Blockstack Core password?
It’s usually not the end of the world, and you can usually recover. However, if you were in the process of registering a Blockstack ID, then that Blockstack ID will be lost.
If you forget your Blockstack Core password, you can recover by moving the ~/.blockstack directory out of the way. A new ~/.blockstack directory will be generated for you, and you can enter a new Blockstack Core password.
Why doesn’t the start work the second time?
If you close the web browser, the background daemon will keep running. It’s possible the daemon is still running. To stop it, you should run:
$ bash ./Blockstack-for-Linux-v0.20.1.sh stop
If it still does not start, then it’s possible the API daemon left some old state around. In that case, try this as well:
$ rm -rf /tmp/.blockstack_tmp
Why do I have to be root to run the browser?
You do not need to be root per se, but you do need to be in the docker group. Specifically, the UNIX socket at /var/run/docker.sock must be readable and writable to you. We do not recommend running as root. Instead, add yourself to the docker group with this command:
$ sudo usermod -a -G docker $(whoami)
You may need to logout and log back in for the change to take effect. Alternatively, you can run su $(whoami), and the resulting shell will have the latest groups.
What if I have the blockstack CLI installed already?
If you have installed the CLI already, then you MUST back up your existing ~/.blockstack directory before running the browser. Once you stop the browser containers (with bash ./Blockstack-for-Linux-v0.20.1.sh stop), you can restore your ~/.blockstack directory to use the CLI again.
Help! Nothing is working!
If you’re still having trouble, there’s also a Web-only version available at browser.blockstack.com. You should only use this option of you cannot get Blockstack installed. If you go this route, you should uninstall Blockstack first. @odinho has written an excellent walk-through here.
