python_libstorj

Dependencies

• python 2.7
• swig
• virtualenv (optional)
• docker (optional)

Enviroment Setup

This section aims to explain how to get multiple environments setup and working with python_libstorj. These different environments aren't necessarily mutually exclusive; you can choose how you would like to interact with python_libstorj.

(Common Steps)

• Clone python_libstorj

  git clone https://github.com/Storj/python-libstorj
  

• Configuration

  The tests/ directory contains multiple example "options.yml" files. Depending on which environment you choose, you may want to use the respective example file. Copy tests/options.<some>_example.yml to tests/options.yml and edit:

  • bridge_options
    • user
    • pass
    • host (if applicable)
    • port (if applicable)
    • proto (if applicable)
  • encrypt_options
    • mnemonic

  See libstorj for an easy way to create/import/export users/mnemonics (libstorj --help).

Using Docker

Using docker is a convenient way to get into a completely ready to go environment. The image is based on storjlabs/storj-integration image which runs a complete mini storj backend:

Bridge (1x), Bridge-monitor(1x), Renters (6x), Farmers (16x)

You can use the python_libstorj.dockerfile as a starting point for building a custom docker environment with python_libstorj installed and built from source. This is ideal for use as a development environment for python_libstorj, for example.

The libstorj cli tool is already installed in the python_libstorj image; it's used to automatically register and activate a user, during docker build, with the credentials provided in the following build-args and/or environment variables:

# See https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg


STORJ_EMAIL    # email address of storj user
STORJ_PASS     # basicauth password of storj user
STORJ_KEYPASS  # cli credential encryption passphrase
STORJ_MNEMONIC # mnemonic of a storj user
STORJ_BRIDGE   # the bridge server to talk to (e.g.  https://api.storj.io)
               #   - defaults to http://127.0.0.1:6382

See the help for more info (libstorj --help).

1. Clone python_libstorj

2. Create a config file

   The options.docker_example.yml only requires changes to the user, pass and mnemonic properties; further changes are optional.

3. Build the python_libstorj image

   # See https://docs.docker.com/engine/reference/commandline/build/
   
   docker build --tag python_libstorj \
       --build-arg STORJ_EMAIL="<email>" \
       --build-arg STORJ_PASS="<password>" \
       --build-arg STORJ_MNEMONIC="<mnemonic>" \
       -f ./dockerfiles/python_libstorj.dockerfile .
   
   # optionally add the `--no-cache` arg to ensure a fresh build
   

   Note: STORJ_BRIDGE and STORJ_KEYPASS environment variables (and corresponding build-args; see libstorj for more info - (these currently only apply to the libstorj cli (i.e. options.yml is used by the unittest suite)).

4. Run/Create/Start a python_libstorj container

   # See https://docs.docker.com/engine/reference/commandline/run/
   #     https://docs.docker.com/engine/reference/commandline/create/
   #     https://docs.docker.com/engine/reference/commandline/start/
   
   # See volumes: https://docs.docker.com/storage/volumes/
   # use of volumes (i.e. `-v`) is optional
   
   # Get a quick shell in a `python_libstorj` container
   docker run -v $(pwd)/tests:/python_libstorj/tests \
              -v $(pwd)/lib:/python_libstorj/lib \
              -it --name python_libstorj_1 python_libstorj
   
   # Get an ephemeral container
   docker run --rm -it python_libstorj
   
   # Create (but don't start) a persistent container
   docker create -v $(pwd)/tests:/python_libstorj/tests \
                 -v $(pwd)/lib:/python_libstorj/lib \
                 -it --name python_libstorj_1 python_libstorj
   
   # Start a stopped container
   # (either from a previous `create` or `run`)
   docker start -ai python_libstorj_1
   
   # Deleting a container
   # If you used the `--name` arg you will need to delete
   # the container with that name before you can re-create it
   docker rm python_libstorj_1 # following the example above
   
   #   You can use `docker ps` to see what containers are running.
   

Using Docker

1. Clone python_libstorj

2. Create a config file

3. Build the docker image

   # See https://docs.docker.com/engine/reference/commandline/build/
   
   docker build --tag python_libstorj -f ./dockerfiles/python_libstorj.dockerfile .
   

4. Running the container

   # See https://docs.docker.com/engine/reference/run/
   #     https://docs.docker.com/engine/reference/run/#volume-shared-filesystems
   
   docker run -it \
       -v $(pwd)/lib:/python_libstorj/lib \
       -v $(pwd)/tests:/python_libstorj/tests \
       python_libstorj
   

5. Start a local storj backend (optional)

   From within the python_libstorj container:

   # See https://github.com/storj/libstorj
   /root/scripts/start_everything.sh
   

Using Virtualenv

1. Clone python_libstorj
2. Setup a virtualenv

   virtualenv env
   

3. Activate your virtualenv

   . env/bin/activate
   

4. Install pip dependencies

   pip install -r ./requirements.txt
   

5. Create a config file

Build

Run the build shell script:

./build.sh

Building needs to be done once initially (already done if you're using docker), and any time changes are made to C/C++ and/or swig interface source (e.g. ./lib/*.{cpp,h,i})

Running Tests

python -m unittest discover