-
Notifications
You must be signed in to change notification settings - Fork 2
Installation Notes
Basic installation instruction can be found in the README file. But if you are new to Python, or if you run Windows (and especially if both are true), getting the blockchain running may be a little tricky. This document includes some tips that may help.
The biggest issue with running Python apps in Windows usually involves how it was installed. Most reference books recommend, or assume, that Python is installed in a directory like C:\python. But your installation may be different, probably depending on the Python version. It could be in C:\Program Files, or if installed with a non-administrative account, under your user account folder. For instance, my version was installed in c:\users\joe_000\appdata\local\programs\python\python36-32.
Also, your installation may or may not have updated your systems's PATH environment variable. If it was not updated, then you can still run Python easily enough by using the Start menu, typing py in a command shell, or clicking on a python script in Explorer. But most installation instructions assume you will start a command shell, navigate to your project directory, then use pip, virtualenv, or pipenv to install packages. If your path doesn't include the location of these files (in the scripts folder, under the folder that has the python.exe file), they won't run.
Fix this by adding the scripts folder to your PATH variable.
It is recommended that you run applications in a virtual environment; that is, a sort of ad hoc copy of Python that only includes the packages you need to run the application. (For our blockchain, those packages include flask and requests.)
By using a virtual environment, you avoid making any changes to the global set-up of your machine. You also avoid conflicts that can occur if applications depend on different versions of the same packages.
On the other hand, if you don't run many applications on your machine, or you just installed it, you can get away with running the blockchain app in your native Python environment:
- Download or clone the repository
- Open a command shell and navigate to the repo folder.
- Install the packages needed by the application:
pip install flask
pip install requests
- Then you can run the app:
python blockchain.py
And/or, in Windows:
py blockchain.py
To run multiple nodes, just spawn a new command shell or two, and repeat the python command with different ports (e.g., ` -p 5001)
These days, virtualenv has been superseded by pipenv, which is in some ways easier to use. But you will often encounter references to virtualenv in books, tutorials, and so on.
To create a virtual environment using virtualenv, start a command shell, navigate to your local copy of the blockchain repo, and enter
virtualenv env
This creates a folder called env in your repo; it is where the files needed to support your VM are stored, including a separate of the python executable and the pip installer.
Then, you 'activate' your VM by running the activate batch file in the scripts folder under env. In Windows:
scripts\activate
You know your VM is activated when you see its name (env) in front of your command prompt. Now you can install the flask and requests packages just as described above, but they will exist only within your virtual environment.
pipenv is similar to virtualenv, with some key differences:
- the files needed to support the VM are stored in your user folder instead of the repo folder
- two files, Pipfile and Pipfile.lock, are used to indicate what packages are installed as part of the VM
The Pipfile is created if needed by pipenv, but if it already exists, as it does in our repo, it will be used to automatically install the packages needed by the application.
To use pipenv, follow the instructions in our README file.
Docker takes a different approach. Instead of running the application in a virtual environment using your own installation of Python, it creates a separate, self-contained image of the application and everything it needs to run. Your machine doesn't even have to have Python installed, and even if it is installed, the Docker image is built from a base copy of Python, stored in a public Docker repository. The application runs off of that copy.
In fact, the docker file included in our git clones the application repository from our repo on github, so it isn't even necessary to clone it first on your machine.
Even so, making this work on a Windows machine is not a trivial undertaking.
First, you must install Docker, but the native Windows client only runs on Windows 10 Enterprise or Pro editions. Many Windows 10 users run the Home edition, so if that is what you have, or if you have an earlier version of Windows, you must install the Docker Toolbox instead.
Second, the Dockerfile is configured to build the image by cloning the Github repository. Since our repo is a fork of an earlier blockchain app, the the Dockerfile we have referenced that earlier chain. It so happens that that application has an error, and will not run.
We have fixed our copy of the Dockerfile to reference our own repository, but if you have previously cloned the repo, be sure to refresh your copy to get the most up to date Dockerfile (which is actually the only file you need from our repo to create a Docker image).
Keep in mind that even with the updated Dockerfile, the Docker image will be based on the online repo. If you have made changes to your local copy the Dockerfile will ignore them, unless you modify the Dockerfile to clone your local version.
Third, using Docker is not very practical when you want to test or debug changes to the app. Each change will require you to destroy the Docker container that runs the image and build a new one.
Fourth, on Windows at least, Docker images run on a virtual Linux machine that is assigned its own IP address, just as if it is a separate machine attached to your router. What this means is that you can't get to its web server using localhost, or 127.0.0.1. It will probably be an address starting with 192.168. To figure out what this address is, you will need to run the Kitematic application that comes with the Docker Toolbox. (I'm not sure how this works if you have the native Docker Windows client.)
Docker is actually very interesting technology, and is likely to have a significant impact on the way software is packaged and distributed. Once our blockchain is advanced enough to deploy on a large number of nodes, Docker will probably be the best way to distribute it. If you have an interest in Docker, it is worth using our blockchain to experiment with it. But if your primary interest is in developing the code, or tweaking it to understand how it works, pipenv will be much easier to deal with.