Development Setup

Currently we support only *NIX-compatible platforms (Linux or macOS).

Prepare containers for external daemons

First install an appropriate version of Docker (later than 2017.03 version) and docker-compose (later than 1.21). Check out the Install Docker guide.

💡	All shell command snippets in this guide assume that your are on a arbitrary workspace directory (e.g., ~/workspace). Or, you may think cd .. is omitted at the ends of all command snippets.

$ git clone https://github.com/lablup/backend.ai
$ cd backend.ai
$ docker-compose -f docker-compose.halfstack.yml up -d
$ docker ps  # you should see 3 containers running

This will create and start PostgreSQL, Redis, and a single-instance etcd containers. Note that PostgreSQL and Redis uses non-default ports by default (5442 and 6389 instead of 5432 and 6379) to prevent conflicts with other application development environments.

Prepare Python 3.6+

Check out Install Python via pyenv for instructions.
Create the following virtualenvs: venv-manager, venv-agent, venv-common, and venv-client.

Prepare dependent libraries

Install snappy (brew on macOS), libsnappy-dev (Debian-likes), or libsnappy-devel (RHEL-likes) system package depending on your environment.

Prepare server-side source clones

Clone the Backend.AI source codes.

$ git clone https://github.com/lablup/backend.ai-manager
$ git clone https://github.com/lablup/backend.ai-agent
$ git clone https://github.com/lablup/backend.ai-common

Inside each directory, install the sources as editable packages.

💡	Editable packages makes Python to apply any changes of the source code in git clones immediately when importing the installed packages.

$ cd backend.ai-manager
$ pyenv local venv-manager
$ pip install -U -r requirements-dev.txt

$ cd backend.ai-agent
$ pyenv local venv-agent
$ pip install -U -r requirements-dev.txt

$ cd backend.ai-common
$ pyenv local venv-common
$ pip install -U -r requirements-dev.txt

(Optional) Symlink backend.ai-common in the manager and agent directories to the cloned source

If you do this, your changes in the source code of the backend.ai-common directory will be reflected immediately to the manager and agent. You should install backend.ai-common dependencies into venv-manager and venv-agent as well, but this is already done in the previous step.

$ cd "$(pyenv prefix venv-manager)/src"
$ mv backend.ai-common backend.ai-common-backup
$ ln -s "~/backend.ai-common" backend.ai-common

$ cd "$(pyenv prefix venv-agent)/src"
$ mv backend.ai-common backend.ai-common-backup
$ ln -s "~/backend.ai-common" backend.ai-common

Prepare client-side source clones

$ git clone https://github.com/lablup/backend.ai-client-py

$ cd backend.ai-client-py
$ pyenv local venv-client
$ pip install -U -r requirements-dev.txt

Inside venv-client, now you can use the backend.ai command for testing and debugging.

💡

Write a shell script like below to easily switch the API endpoint and credentials for testing: #! /bin/sh export BACKEND_ENDPOINT=http://127.0.0.1:8081/ export BACKEND_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE export BACKEND_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY source this script before you test and debug the client.

Initialize databases and load fixtures

Check out the Prepare Databases for Manager guide.

Prepare Kernel Images

You need to pull the kernel container images first to actually spawn compute sessions.

$ docker pull lablup/kernel-python:latest
$ docker pull lablup/kernel-python:3.6

For the full list of publicly available kernels, check out the kernels repository.

Setting Linux capabilities to Python

To allow Backend.AI to collect sysfs/cgroup resource usage statistics, the Python executable must have the following Linux capabilities (to run without "root"): CAP_SYS_ADMIN, CAP_SYS_PTRACE, and CAP_DAC_OVERRIDE. You may use the following command to set them to the current virtualenv's Python executable.

$ sudo setcap cap_sys_ptrace,cap_sys_admin,cap_dac_override+eip $(readlink -f $(pyenv which python))

Running daemons from cloned sources

$ cd backend.ai-manager
$ ./scripts/run-with-halfstack.sh python -m ai.backend.gateway.server --debug

Note that through options, PostgreSQL and Redis ports set above for development environment are used. You may change other options to match your environment and personal configurations. (Check out -h/--help)

$ cd backend.ai-agent
$ ./scripts/run-with-halfstack.sh python -m ai.backend.agent.server --scratch-root=`pwd`/scratches --debug --idle-timeout 30

※ The role of run-with-halfstack.sh script is to set appropriate environment variables so that the manager/agent daemons use the halfstack docker containers.