Skip to content

Development environment

Jump to bottom
marksvc edited this page Jul 7, 2023 · 34 revisions
  • Vagrant GUI Setup. A Vagrant box with xForge already installed is downloaded and set up on your machine. This is the easiest and cleanest to setup.
  • Local Linux Development Setup. Everything is installed directly on your machine, which needs to be running Ubuntu 16.04. This is the fastest method because development is not done in a virtual machine.
  • Manual Setup This setup is specifically written for Windows but the steps could be used for any OS.

Vagrant Development Machine

Setup

Install VirtualBox, Vagrant, and git. To do this in Linux, run

sudo apt install vagrant virtualbox virtualbox-guest-additions-iso git

Setup git. At least name and email is needed in .gitconfig. You can do this from a terminal in your host machine by running

git config --global user.name "My Name"
git config --global user.email "[email protected]"

Hardware-assisted virtualization (VT-x or AMD-V) needs to be enabled in your BIOS.

Clone the xforge git repository to access (and later receive updates to) the vagrant development machine configuration file:

git clone https://github.com/sillsdev/web-xforge
cd web-xforge/deploy/vagrant/sfdev

Create guest

  • Run vagrant up. This will download, initialize, and run the development machine. The machine is about 7GB, so expect the download to take a while.
  • Wait for the provisioning output from vagrant up to finish completely before doing anything in the guest.
  • In the guest development machine, check if there is a file on your Desktop called warning-not-provisioned.txt, indicating a problem. If there is, follow the instructions in that file.
  • Have a look at the machine-instructions.txt file on the desktop. Set local server secrets.
  • In a terminal, run the following to upgrade VS Code and other packages.
sudo apt update
sudo apt upgrade
  • Start Scripture Forge by running the following.
cd ~/src/web-xforge/src/SIL.XForge.Scripture
dotnet run
  • In the guest development machine, browse to http://localhost:5000/projects and log in. Launching Chromium may ask for the computer login password, which is "vagrant".

Re-create guest

If you want to start over with a fresh vagrant guest, you can do the following.

  • Run vagrant box update on the host computer to make sure you have the latest update to the vagrant basebox.
  • Run vagrant destroy on the host computer to delete your vagrant guest computer and all its data.
  • Follow the instructions above to create a vagrant guest.

Local Linux Development Setup

Start by installing Git and Ansible:

sudo add-apt-repository ppa:ansible/ansible
sudo apt update
sudo apt install -y git ansible

Now create a directory for installation and clone the repo:

git clone --recurse-submodules https://github.com/sillsdev/web-xforge

The --recurse-submodules is used to fetch many of the Ansible roles used by the Ansible playbooks in the deploy folder. If you've already cloned the repo without --recurse-submodules, run git submodule update --init --recursive to pull and initialize them.

Change the variable mongo_path: /var/lib/mongodb in deploy/vars/config_palaso.yml. Set it to a location where MongoDB should store its databases.

  • Vagrant VM Setup: uncomment line 5 and comment line 4
  • Local Linux Development Setup: uncomment line 4 and comment line 5 (or whatever is appropriate on your system, its best to have Mongo store databases on your HDD rather than SSD). Make sure the mongodb user has permission to read and write to the path you specify.

Run the following Ansible playbook (works on Ubuntu 16.04 thru 20.04 (focal)).

cd web-xforge/deploy
ansible-playbook playbook_focal.yml --limit localhost -K

Add developer secrets. Ask another developer how to get these.

In src/SIL.XForge.Scripture/, run dotnet run. Browse to http://localhost:5000.

Manual Setup

Although this setup is specifically written for Windows, the steps could be used for any OS and only step 3 is a Windows specific link. The order below is not particulalry important.

  1. Install git, e.g. Git Kraken

  2. Clone the repo from the command line including recursing submodules (feel free to clone with SSH instead of HTTPS):

    git clone --recurse-submodules https://github.com/sillsdev/web-xforge.

  3. Install MongoDB v4 as a service

  4. Install .Net SDK 6.0

  5. Install Node v16

  6. Install FFmpeg v4 executable into the C:\usr\bin\ directory.

  7. Install a developer editor, VS Code is recommended (the repo includes VS Code settings)

  8. Install Mercurial v4.8 (python 2) and copy contents into the C:\usr\local\bin\ directory.

  9. Create folders owned by you. Check in the Ansible deploy/dependencies.yml for the valid list of folders. As of writing they were:

  • /var/lib/scriptureforge/sync/
  • /var/lib/scriptureforge/audio/
  • /var/lib/xforge/avatars/

On Windows, just put these off your root drive, e.g. C:\var\lib\...

  1. Add developer secrets. Ask another developer how to get these.
  2. Copy /deploy/files/InternetSettings.xml to %localappdata%/Paratext93 or ~/.local/share/Paratext93/ on other systems. If you have installed Paratext 9.3, and completed the initial setup on first run, then this step will be taken care of for you.
  3. In src/SIL.XForge.Scripture/, run dotnet run. Browse to http://localhost:5000.
Clone this wiki locally