diff options
Diffstat (limited to 'website/content/platform/installation.mdx')
| -rw-r--r-- | website/content/platform/installation.mdx | 289 |
1 files changed, 289 insertions, 0 deletions
diff --git a/website/content/platform/installation.mdx b/website/content/platform/installation.mdx new file mode 100644 index 00000000000..f0a5be3f4f0 --- /dev/null +++ b/website/content/platform/installation.mdx @@ -0,0 +1,289 @@ +--- +title: Installation +sidebar_position: 1 +description: This page presents the general system requirements, supported environments, + installation procedures, and setup for running the OpenBB Platform. It discusses + the prerequisites including Python version, operating system requirements, Docker + usage, and the process of building the platform from source. +keywords: +- OpenBB Platform +- Python +- System requirements +- Supported environments +- Installation +- Docker +- Python virtual environment +- Installation from source +- Windows 10 +- Mac OS Big Sur +- Linux +- Package installation +- VS Code +- PyCharm +- Jupyter +- GitHub +- Conda +- venv +- API +- Repository +- pip +- Poetry +- Toml +- PyPI +- Node.js +- npm +--- + +import HeadTitle from '@site/src/components/General/HeadTitle.tsx'; + +<HeadTitle title="Installation | OpenBB Platform Docs" /> + +## General System Requirements + +Most systems capable of running Python 3.9-3.11 will be compatible with the OpenBB Platform. A modern processor (five years or less), running an up-to-date operating system, with at least 4GB of RAM, is recommended. Maintaining the system with current patches ensures maximum compatibility. At a minimum, Windows and macOS should be: + +- Windows 10 +- Mac OS Big Sur + +Linux users should run the command line update for the package manager, prior to installation. + +## Supported Environments + +The OpenBB Platform is installed within a Python virtual environment. It is compatible with versions of Python between 3.9 and 3.11, inclusively. The method for creating the environment will be a matter of user preference, from the command line - [Conda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html), [venv](https://docs.python.org/3/library/venv.html), etc. - or in a code editor and IDE - [VS Code](https://code.visualstudio.com/docs/languages/python), [PyCharm](https://www.jetbrains.com/pycharm/), [Jupyter](https://jupyter.org/). + +If you're interested in using the [Docker](/platform/installation#docker) container, skip ahead to the specific section [below](/platform/installation#docker). + +For those new to Python, [this article](https://www.infoworld.com/article/3306656/python-virtualenv-and-venv-dos-and-donts.html) shares some tips on getting started and why environments are important. + +See [this guide](https://code.visualstudio.com/docs/python/environments) for creating a Python environment in VS Code. + +With the environment created, and activated, begin the installation process. + +## Installation + +Before installation, update the package manager so that `pip` is current, then create the environment with the desired version of Python. + +:::note +Installing packages directly to the system Python or `base` environment is not recommended. Create a new environment first (can be any name, using openbb here for example). + +```bash +conda create -n openbb python=3.11 +conda activate openbb +``` + +::: + +### PyPI + +<details> +Install from PyPI with: + +```console +pip install openbb +``` + +This will install the core OpenBB Platform, along with officially supported extensions and providers. + +To install all extensions and providers (both officially supported and community maintained ones): + +```console +pip install openbb[all] +``` + +:::tip +In a macOS `zsh` Terminal shell, add quotation marks around the library name. + +`"openbb[all]"` +::: + +To install a single extension: + +```console +pip install openbb[charting] +``` + +```console +pip install openbb[ta] +``` + +Or install a single provider: + +```console +pip install openbb[yfinance] +``` + +To install the Nightly distribution (this installs all extras by default): + +```console +pip install openbb-nightly +``` + +From your python interpreter, import the OpenBB Platform: + +```console +from openbb import obb +``` + +:::warning +This import statement is required due to the statefulness of the obb package. There is currently no support for imports such as: + +```console +from openbb.obb.equity import * +``` + +::: + +When the package is imported, any installed extensions will be discovered, imported and available for use. + +:::note +Currently if you wish to have the bare-bones openbb package with no extensions or providers, you can install with: + +```console +pip install openbb-core && pip install openbb --no-deps +``` + +::: + +To update the package: + +```console +pip install --upgrade openbb +``` + +To update all extensions and providers: + +```console +pip install --upgrade openbb[all] +``` + +If you want to uninstall the package and all its dependencies: + +```console +pip uninstall openbb[all] +``` + +</details> + +### Docker + +<details> +OpenBB provides a `.dockerfile` on [GitHub](https://github.com/OpenBB-finance/OpenBBTerminal). + +Run the following command from the repo root to build the image: + +```bash +docker build -f build/docker/api.dockerfile -t openbb-platform:latest . +``` + +To run it: + +```bash +docker run --rm -p 8000:8000 -v ~/.openbb_platform:/root/.openbb_platform openbb-platform:latest +``` + +This will mount the local `~/.openbb_platform` directory into the Docker container to use with the API keys and preferences from there, and it will expose the API on port `8000`. +</details> + +### Source + +<details> +To build the OpenBB Platform from the source code, first install `git`: + +```console +pip install git +``` + +Next, clone the repository from GitHub: + +```console +git clone git@github.com:OpenBB-finance/OpenBBTerminal.git +``` + +When it is done, checkout the branch where the code is living: + +```console +git checkout develop +``` + +Then, `cd` into the directory: + +```console +cd openbb_platform +``` + +Install required packages + +```console +pip install poetry toml +``` + +Finally, run the developer installation script: + +```console +python dev_install.py +``` + +:::note +To install all extensions and providers, run: `python dev_install.py -e` +::: +</details> + +### Devcontainer + +The OpenBB Platform can be run in a [Devcontainer](https://code.visualstudio.com/docs/devcontainers/containers) in VS Code. This is a container with a well-defined environment, and it can be used to develop, build, test, and run the OpenBB Platform and its CLI. + +1. Open the project in VS Code +2. Press F1 (Command Palette) and select Remote-Containers: Reopen in Container +3. Wait for the container to build and the postCreateCommand to run +4. Open a terminal in VS Code and run the following command: source obb/bin/activate + +> You can also click the Dev Containers badge at the top of the README to open the project in a Devcontainer. + +## Post-Installation + +With a fresh installation, and upon installing or uninstalling extensions, the Python interface needs to be built. This is done automatically, but can be manually triggered if required. Start a Python session and import openbb: + +```console +python +``` + +```python +from openbb import obb + +exit() +``` + +To manually trigger the build: + +```python +import openbb +openbb.build() +``` + +Restart the Python interpreter and then begin using the OpenBB Platform. + +```python +from openbb import obb +``` + +Start the REST API with: + +```console +uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload +``` + +See more information about using the REST API in the [usage section](/platform/user_guides/rest_api) + +## Hub Synchronization + +Once you have installed the OpenBB Platform with the desired providers and extensions, you can synchronize with the [OpenBB Hub](https://my.openbb.co/app/hub). The main benefit of this is that you can use your single login to access your saved credentials and preferences from any instance. To login, you can use the `login` method, either using your email and password: + +```python +obb.account.login(email='my_email_here', password='my_password_here') +``` + +Or using your personal access token: + +```python +obb.account.login(pat='my_pat_here') +``` |