Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated Installation Doc for Python - Linux, Windows #435

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
Open

Updated Installation Doc for Python - Linux, Windows #435

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cc231e5
Updated Installation docs with new requirements command for pyenv pyt…
jayam04 Jan 15, 2025
cdda110
Merge branch 'develop' into better-installing-oppia
jayam04 Jan 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 56 additions & 46 deletions Installing-Oppia-(Linux;-Python-3).md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,47 @@
## Table of Contents

* [Install prerequisites](#install-prerequisites)
* [Clone Oppia](#clone-oppia)
* [Setup a virtual environment](#setup-a-virtual-environment)
* [Running Oppia on a development server](#running-oppia-on-a-development-server)
* [Tips and tricks](#tips-and-tricks)
* [Notes on installation on Arch Linux systems](#notes-on-installation-on-arch-linux-systems)
* [Changes to installation prerequisites](#changes-to-installation-prerequisites)
* [Changes to the virtual environment setup](#changes-to-the-virtual-environment-setup)
1. [Install prerequisites](#1-install-prerequisites)
1. [Clone Oppia](#2-clone-oppia)
1. [Setup a virtual environment](#3-setup-a-virtual-environment)
1. [Running Oppia on a development server](#4-running-oppia-on-a-development-server)
1. [Tips and tricks](#5-tips-and-tricks)
1. [Notes on installation on Arch Linux systems](#6-notes-on-installation-on-arch-linux-systems)
* [Changes to installation prerequisites](#changes-to-installation-prerequisites)
* [Changes to the virtual environment setup](#changes-to-the-virtual-environment-setup)

**Note:** If you just want to create and share explorations, you may be able to use the hosted server at https://www.oppia.org (in which case you don't need to install anything).
> [!TIP]
> If you just want to create and share explorations, you may be able to use the hosted server at https://www.oppia.org (in which case you don't need to install anything).

*These installation instructions were last tested on 8 January 2024. For more information on issues that may occasionally arise with the installation process, see the [Troubleshooting](https://github.com/oppia/oppia/wiki/Troubleshooting) page or ask in the [GitHub Discussions](https://github.com/oppia/oppia/discussions).*
> [!NOTE]
> These installation instructions were last tested on 8 January 2024. For more information on issues that may occasionally arise with the installation process, see the [Troubleshooting](https://github.com/oppia/oppia/wiki/Troubleshooting) page or ask in the [GitHub Discussions](https://github.com/oppia/oppia/discussions).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: ask in GitHub Discussions (drop "the")


## Install prerequisites
## 1. Install prerequisites

Oppia relies on a number of programs and third-party libraries. Many of these libraries are downloaded automatically for you when you first run the `start.py` script provided with Oppia (see step 1 in the next section). However, there are some things that you will need to do beforehand:

1. Make sure you have curl (used to download third-party libraries), git (which allows you to store the source in version control), unzip (used for unpacking zip files) and openjdk-11-jre (needed for GCP to work):

```bash
sudo apt-get update
sudo apt-get install curl git unzip openjdk-11-jre
```

Alternatively, if you are on Debian/Ubuntu, you can use the `install_prerequisites.sh` script to install these. From the oppia directory, run:

```
sudo apt-get update
sudo apt-get install curl git unzip openjdk-11-jre
```

Alternatively, if you are on Debian/Ubuntu, you can use the `install_prerequisites.sh` script to install these. From the oppia directory, run:

```
bash scripts/install_prerequisites.sh
```
```bash
bash scripts/install_prerequisites.sh
```

2. Verify that Java version 11+ is installed. You can use the command `java -version` to do this. (If you need to change the default binary for the `java` command on your machine, use `sudo update-alternatives --config java`.)

3. Install Chrome from [Google's website](https://www.google.com/chrome). You'll need this to run tests.


## Clone Oppia
## 2. Clone Oppia

1. Create a new, empty folder that will hold your Oppia work. Here, we call the folder `opensource`.

2. Navigate to the folder (`cd opensource/`). Next, we'll [fork and clone](https://help.github.com/articles/fork-a-repo/) the Oppia repository.
2. Navigate to the folder (`cd opensource/`). Next, we'll [fork and clone](https://help.github.com/articles/fork-a-repo/) the Oppia repository, as described in below steps.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

...in the steps below.

(Or just drop the 2nd sentence here and, in step 3, you can say "click on the fork button to fork Oppia's repository", where "fork Oppia's repository" is linked to https://help.github.com/articles/fork-a-repo/ .)


3. Navigate to https://github.com/oppia/oppia and click on the `fork` button. It is placed on the right corner opposite the repository name `oppia/oppia`.

Expand Down Expand Up @@ -94,22 +95,27 @@ bash scripts/install_prerequisites.sh

For making any changes to original repository, we first sync our cloned repository with original repository. We merge develop with `upstream/develop` to do this. Now we make a new branch, do the changes on the branch, push the branch to forked repository, and make a PR from Github interface. We use a different branch to make changes so that we can work on multiple issues while still having a clean version in develop branch.

## Setup a virtual environment
## 3. Setup a virtual environment

For your virtual environment, we recommend you use [pyenv](https://github.com/pyenv/pyenv). Here are some instructions for doing so, but you can use another virtual environment tool if you wish:
> [NOTE!]
> The commands below can be executed in any directory, as they are not path-specific.
1. **Make sure you install the Python build dependencies for your operating system. These are specified [here](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). If you don't do this it might lead to problems further on.** The build dependencies for Ubuntu/Debian are

> [NOTE!]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is working correctly, see the rich diff preview.

> The commands below can be executed in any directory, as they are not path-specific.

1. **Make sure you install the Python build dependencies for your operating system. These are specified [here](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). If you don't do this it might lead to problems further on.** To install build dependencies in Ubuntu/Debian run


```
sudo apt-get install make build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget llvm libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
sudo apt update; sudo apt install build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev curl git \
libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
```

2. Install pyenv:
2. Install pyenv using [installation steps](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

... using these installation steps: [link]

Or just say "Install pyenv." and link the whole text to that link.

pyenv lets you easily switch between multiple versions of Python.
```bash
$ curl -fsSL https://pyenv.run | bash

```console
$ curl pyenv.run | bash
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 270 100 270 0 0 630 0 --:--:-- --:--:-- --:--:-- 632
Expand All @@ -119,7 +125,8 @@ For your virtual environment, we recommend you use [pyenv](https://github.com/py
...
```

If you see the warning at the end, add the following lines to your ``>> ~/.bashrc`` (if you are using bash) or ``>> ~/.zshrc`` (if you are using zsh).
> [!WARNING]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These don't seem to be showing up properly in the rich text diff. In future, please do a preview check before submitting for review.

> If you see the warning at the end, add the following lines to your ``>> ~/.bashrc`` (if you are using bash) or ``>> ~/.zshrc`` (if you are using zsh).

```bash
export PYENV_ROOT="$HOME/.pyenv"
Expand All @@ -134,9 +141,10 @@ For your virtual environment, we recommend you use [pyenv](https://github.com/py
> Be careful with using graphical editors like Notepad in Windows. These can add carriage returns (`\r`) that confuse our Linux-based development tools. Instead, we recommend using editors designed for programming or command-line text editors.

3. Reload your shell or open a new terminal window to load your updated `~/.bashrc` or `~/.zshrc`.
```bash
exec "$SHELL"
```
```bash
exec "$SHELL"
```

4. Now you can install Python 3.9.20 and the associated pip like this:

```console
Expand All @@ -145,13 +153,15 @@ exec "$SHELL"
installed python-3.9.20 to /home/user/.pyenv/versions/3.9.20
```

5. Install direnv
5. Install direnv.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Install direnv, which helps to set and unset the virtual environment based on the current directory:

direnv helps to set and unset virtual environment based on current dierctory

```sh
sudo apt install direnv
```

6. Setup direnv into your shell.
6. Setup direnv into your shell.

If you are using bash:

```bash
Expand Down Expand Up @@ -182,7 +192,7 @@ exec "$SHELL"
> [!WARNING]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In "7." above -- let's change to "Add a new file called ..." (I know this was already there, but thought I'd mention it since we're updating this page fully)

Also this WARNING doesn't seem to be displaying correctly, ditto below/elsewhere. It's possible that those indicators don't work correctly in indented lists.

> Be careful with using graphical editors like Notepad in Windows. These can add carriage returns (`\r`) that confuse our Linux-based development tools. Instead, we recommend using editors designed for programming or command-line text editors.

8. Create a virtual environment for oppia by adding file named `.envrc` into the parent folder of the oppia repository
8. Create a virtual environment for oppia by adding file named `.envrc` into the parent folder of the oppia repository, which is `opensource/` in this case.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Create a virtual environment for Oppia by adding an .envrc file into the parent folder of the oppia repository (opensource/ in this case). The file should have the following content:

with this content:

```console
Expand All @@ -191,15 +201,15 @@ exec "$SHELL"

Then run this command in the same folder:

```sh
```bash
direnv allow
```

Now whenever you are within the `oppia` folder, the virtual environment will be active.

9. Install the Python dependencies:

```console
```bash
$ pip install pyyaml setuptools
Requirement already satisfied: setuptools in /home/user/.pyenv/versions/2.7.18/envs/oppia-tmp/lib/python2.7/site-packages (44.1.1)
Collecting pyyaml
Expand All @@ -213,15 +223,15 @@ exec "$SHELL"

10. If you want to run backend tests and check coverage, please install these 2 pip libraries:

```console
```bash
pip install coverage configparser
```

## Running Oppia on a development server
## 4. Running Oppia on a development server

1. In a terminal, navigate to `oppia/` and run:

```console
```bash
python -m scripts.start
```

Expand All @@ -242,7 +252,7 @@ exec "$SHELL"
> [!NOTE]
> Oppia uses the npm tool to install some packages. This tool accesses both ~/tmp and ~/.npm, and has been known to occasionally encounter permissions issues with those directories. You may need to either delete these directories and all their contents (if they do not contain anything else that needs to be preserved), or change their permissions so that they are owned by you, which you can do by running

```console
```bash
sudo chown -R {{YOUR_USERNAME}} ~/tmp
sudo chown -R {{YOUR_USERNAME}} ~/.npm
```
Expand Down Expand Up @@ -322,7 +332,7 @@ exec "$SHELL"

</details>

## Tips and tricks
## 5. Tips and tricks

* To preserve the contents of the local datastore between consecutive runs, use the `--save_datastore` argument when starting up the dev server:

Expand All @@ -332,7 +342,7 @@ exec "$SHELL"

* The default Oppia installation comes with a set of [demo explorations](https://github.com/oppia/oppia/tree/master/data/explorations). On startup, none of these are loaded. To load them, log in to your server as an admin, then click your username in the top-right corner and choose 'Admin Page'. This will open the admin page, from which you can load the demo explorations.

## Notes on installation on Arch Linux systems
## 6. Notes on installation on Arch Linux systems

_The following notes are thanks to @ashish-patwal. They come with no guarantees, and may change some settings on your local machine, so please make sure you fully understand their ramifications before following them!_

Expand Down
6 changes: 6 additions & 0 deletions Installing-Oppia-(Windows;-Python-3).md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# Table of Contents

> [!NOTE]
> Most of scripts in Oppia are designed to support UNIX based systems, this includes Linix and MacOS but not Windows. So, for Windows we have 3 major methods to support this.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most of scripts --> Most scripts

UNIX based systems, this includes --> UNIX-based systems. These include

Linix --> Linux

Also, what does "this" at the end refer to? It's not quite clear, perhaps worth rephrasing. Maybe "to support running these scripts:"?

> 1. Using Windows Subsystem for Linux 2 (WSL2) (recommended): It's provided by Microsoft and uses lightweight virtual machine with an actual Linux kernel.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uses --> uses a

> 2. Using Virtual Machine solutions such as Virtualbox, VMWare: It's easier to setup and you will have true Linux environment. However, it adds some overhead and reduces performance.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's --> These are

have true --> have a true

> 3. Using Docker (caution: in BETA): It's a modern way which packages dependencies and utilizes OS-level virtualization rather than hardware-level. Currently, being in BETA, it still requires WSL, so it's no better than first method.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

first --> the first


* [Installing Oppia in Windows and WSL2](#installing-oppia-in-windows-and-wsl2)
* [Step 1: Check if your Windows is up to date](#step-1-check-if-your-windows-is-up-to-date)
* [Step 2: Install WSL2](#step-2-install-wsl2)
Expand Down
Loading