Skip to content

Commit

Permalink
Docker: update installation instruction (OpenBB-finance#3692)
Browse files Browse the repository at this point in the history 
* Moving Docker folder into Build

* Workflows : update Docker

* Docker : update compose image version

* Docker : fix volumes path

* Docker: update documentation

* Docker : build.sh add prompt for version number

* Fix spelling

* fix hostname

* adding permissions to folders

* changing version to latest

* reverting wrong change

Co-authored-by: hjoaquim <[email protected]>
  • Loading branch information
@Chavithra @hjoaquim
Chavithra and hjoaquim authored Dec 5, 2022
1 parent 1f54385 commit 9add3e6
Show file tree
Hide file tree
Showing 4 changed files with 79 additions and 102 deletions.
5 changes: 5 additions & 0 deletions build/docker/build.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

echo "Building docker release"

if [ -z "$OPENBBTERMINAL_DOCKER_RELEASE_VERSION" ]
then
read -p "Version number (X.Y.Z format): " OPENBBTERMINAL_DOCKER_RELEASE_VERSION
fi

# SET DEFAULT PARAMETERS IF EMPTY
OPENBBTERMINAL_DOCKER_REGISTRY="${OPENBBTERMINAL_DOCKER_REGISTRY:-ghcr.io}"
OPENBBTERMINAL_DOCKER_GITHUB_REPOSITORY="${OPENBBTERMINAL_DOCKER_GITHUB_REPOSITORY:-openbb-finance/openbbterminal}"
Expand Down
6 changes: 3 additions & 3 deletions build/docker/docker-compose.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@ version: '3.8'
services:
openbb:
environment:
DISPLAY: host.docker.internal:0.0
DISPLAY: host.docker.internal:0.0
volumes:
- ~/OpenBBUserData:/home/python/OpenBBUserData
- ~/.openbb_terminal:/home/python/.openbb_terminal
platform: linux/amd64
image: ghcr.io/openbb-finance/openbbterminal/openbb:2.0.0
image: ghcr.io/openbb-finance/openbbterminal/openbb:latest
stdin_open: true # docker run -i
tty: true # docker run -t
tty: true # docker run -t
6 changes: 6 additions & 0 deletions build/docker/openbb.dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,12 @@ COPY --chown=python:python openbb_terminal openbb_terminal
RUN mkdir -p website/content/sdk/quickstart
COPY --chown=python:python ./website/content/sdk/quickstart/installation.md ./website/content/sdk/quickstart

RUN mkdir OpenBBUserData
RUN chown python:python OpenBBUserData

RUN mkdir .openbb_terminal
RUN chown python:python .openbb_terminal

# SETUP OPENBB IMAGE
FROM repository as dependencies

Expand Down
164 changes: 65 additions & 99 deletions website/content/terminal/quickstart/installation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -84,35 +84,38 @@ Right-Click the app and select <code>Open</code>. You will see a message saying
</TabItem>
<TabItem value="docker" label="Docker">
<p>Install with Docker</p>
Here are the steps to get OpenBBTerminal using the Docker containers that we provide:

1. Installing `Docker` and `Docker Compose`
2. Pulling and running `OpenBBTerminal Docker Container`
3. Configuring your X-server to show plots
Here we will detail how to run OpenBB Terminal Docker image.

Each of this steps need to be followed to have a working version of OpenBBTerminal.
Please check the section matching to your OS.

We will detail these steps in the rest of this document.
## 1. Windows

## 1. Installing `Docker` and `Docker Compose`
### 1.1. Install Docker Desktop

**INSTALL DOCKER**
You can find `Docker Desktop` for Windows here: [Download Docker Desktop](https://www.docker.com/products/docker-desktop)

Installing Docker Desktop is an alternative way and has a `Graphical User Interface` built in with `Docker Compose`.
### 1.2. Start Docker

You can find `Docker Desktop` installation file for your `OS` here: [Download Docker Desktop](https://www.docker.com/products/docker-desktop)
Execute the following command:

**START DOCKER**
```bash
docker info
```

Once you have `Docker` installed and running, you can use the following command to check the state:
If you have something like this, it means you haven't started Docker:

```bash
docker info
Server:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?
```

It should output a text like this one:
Start Docker, this is how the right output looks like:

```text
```bash
docker info
Client:
Context: default
Debug Mode: false
Expand All @@ -124,142 +127,105 @@ Server:
Stopped: 10
```

If you see a message like the following, it most likely means you need to start `Docker`.
### 1.3. Install VcXsrv

Open the docker desktop app in this case.
To display charts with your container, you need : VcXsrv.

```text
Server:
ERROR: Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?
```
You can download VcXsrv here : [Download VcXsrv](https://sourceforge.net/projects/vcxsrv)

## 2. Pulling and running `OpenBBTerminal Docker Container`
When running VcXsrv program check the option: `Disable access control`

**DOCKER COMPOSE**
### 1.4. Pull and run the container

Here are the commands to use `Docker Compose` to pull and run the `OpenBBTerminal Docker Container`:
Execute this commands:

```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/build/docker/docker-compose.yaml

docker compose run openbb
docker compose run poetry
```

The command line with `curl` is downloading this file : [`docker-compose.yaml`](https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/build/docker/docker-compose.yaml).

The `docker-compose.yaml` file is a configuration file telling `Docker Compose`:

- where to find `OpenBBTerminal Docker Container`
- how to run this container.
This will download and run the file: `docker-compose.yaml`

The second command runs `Docker Compose` on the service `poetry` defined in this `docker-compose.yaml` file.
This file contents the settings to pull and run OpenBB Terminal Docker image.

This second command must be run in the same folder in which `docker-compose.yaml` file is.
## 2. macOS

**DOCKER**
### 2.1. Install and run Docker Desktop

If you don't have `Docker Compose` you can also use `Docker` directly to run the `OpenBBTerminal Docker Container`.
Install and run Docker Desktop as describe above in this document.

Here is the commands to run:
### 2.2. Install XQuartz

```bash
docker pull ghcr.io/openbb-finance/openbbterminal/openbb:latest
You can download XQuartz here: [Download XQuartz](https://www.xquartz.org)

docker run -v ~/.openbb_terminal/:/home/python/.openbb_terminal -v ~/OpenBBUserData:/home/python/OpenBBUserData -it --rm ghcr.io/openbb-finance/openbbterminal/openbb:latest
```
Open X Quartz.

You can replace `latest` with the version you want to pull and run.
Then on `Preferences > Security`.

Note for windows:
Make sure both of these options are enabled:

```text
Ignore this message if you are using Powershell or a more evolved interpreters.
If you are using the builtin Windows interpreter.
Replace `~` by `%USERPROFILE%` in the command above.
```
- `Authenticate connections`
- `Allow connections from network clients`

## 3. Configuring your X-server to show plots
It should look like this:
![Screen Shot 2021-09-08 at 12 21 48 PM](https://user-images.githubusercontent.com/18151143/132548605-235d774b-9aa6-4a45-afcf-58fb775d376a.png)

In order to display plots in the docker container, we need to configure the XServer on the host machine. Without this configuration the interactive charts will not be displayed.
### 2.3. Get Docker IP

### On Windows
To get Docker IP you can use this command:

Download and install : [VcXsrv](https://sourceforge.net/projects/vcxsrv/)
```bash
IP=$(ifconfig | grep inet | grep -v "127.0.0.1" | awk '$1=="inet" {print $2}')
```

When running the program is important to check "Disable access control"
### 2.4. Pull and run the container

Run `Docker Compose` like this:
Execute this commands:

```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/build/docker/docker-compose.yaml

docker compose run poetry
```

Or run `Docker` directly:

```bash
docker run -v ~/.openbb_terminal:/home/python/.openbb_terminal -v ~/OpenBBUserData:/home/python/OpenBBUserData -it --rm --env DISPLAY=host.docker.internal:0.0 ghcr.io/openbb-finance/openbbterminal/openbb:latest
xhost +$IP
docker compose run -e DISPLAY=$IP:0 openbb
```

### X-Server on macOS
This will download and run the file: `docker-compose.yaml`

Users familiar with Docker and X-Server can set the `DISPLAY` variable in the file [setenv](/docker/setenv) described above. If you use this approach remember to add `:0` at the end of your inet address. E.g. `DISPLAY=192.168.1.155:0`.
This file contents the settings to pull and run OpenBB Terminal Docker image.

For help setting up the X-Server continue reading:
The `xhost +$IP` and `DISPLAY=$IP:0` parts are there to allow charts display.

#### Setting up X Quartz/X11
## 3. Linux

On macOS the X11 client of choice is [XQuartz](https://www.xquartz.org/). On Windows it's [Xming](http://www.straightrunning.com/XmingNotes/). XQuartz will be used as an example further on.
### 3.1. Install and run Docker Desktop

0. Install X Quartz from <https://www.xquartz.org/>
1. With X Quartz open: go to Preferences -> Security and make sure both options are enabled.
![Screen Shot 2021-09-08 at 12 21 48 PM](https://user-images.githubusercontent.com/18151143/132548605-235d774b-9aa6-4a45-afcf-58fb775d376a.png)
Install and run Docker Desktop as describe above in this document.

#### Adding the display for Docker
### 3.2. Pull and run the container

From the command prompt or terminal, run the following to add your local configuration to the list of allowed access control:
Execute this commands:

```bash
IP=$(ifconfig | grep inet | grep -v -e "127.0.0.1" | awk '$1=="inet" {print $2}')
xhost + $IP
```

Now we can run the docker container, adding the display to the environment:
curl -o docker-compose.yaml https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/build/docker/docker-compose.yaml

```bash
docker run -v ~/.openbb_terminal/:/home/python/.openbb_terminal -v ~/OpenBBUserData:/home/python/OpenBBUserData -it --rm --env-file=path/to/setenv --env DISPLAY=$IP:0 ghcr.io/openbb-finance/openbbterminal/openbb:latest
xhost +local:
docker compose run openbb
```

This container will be able to display all the same plots as the terminal interface.
Note: if you're using remote docker host, you can connect with `ssh -X <FQDN/IP>`.

### X-Server on Linux Desktop
## 4. Advanced: without Docker Compose

X-Server is default in Linux distribution. There is no need to install any clients.

#### Local docker container

We can use IPC socket to connect Desktop.

Add this setting to your `.env` file.

```bash
OPENBB_BACKEND=Qt5Agg
```

And run the following commands.
To run directly the docker image you can use the following command:

```bash
xhost +local:
docker run -it --rm --name openbb --env-file=./.env -e DISPLAY=$DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix ghcr.io/openbb-finance/openbbterminal/openbb:latest
xhost -local:
docker run --rm -it \
-v ~/.openbb_terminal/:/home/python/.openbb_terminal \
-v ~/OpenBBUserData:/home/python/OpenBBUserData \
ghcr.io/openbb-finance/openbbterminal/openbb:latest
```

If you're using remote docker host, you can connect with "ssh -X <FQDN/IP>".

Then run the previous docker command.

</TabItem>
<TabItem value="python" label="Python">
This installation type supports both Windows and Unix systems (Linux + MacOS).
Expand Down

0 comments on commit 9add3e6

Please sign in to comment.