Skip to content

Development environment

Jump to bottom
marksvc edited this page Nov 15, 2024 · 48 revisions

This page describes three ways to set up a development environment.

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 12GB, 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
  • Reboot the VM to apply the updates
  • 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, in the web-xforge/deploy/vagrant/sfdev directory, 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.

Linux development setup

Go to where you want to clone the repo (eg ~/code). In the instructions that follow, replace ~/code/web-xforge with the path to your cloned repo. 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.

sudo apt install --assume-yes git
mkdir --parents ~/code && cd ~/code
git clone --recurse-submodules https://github.com/sillsdev/web-xforge

Optionally install useful tools by doing the following. Chromium is useful for testing and debugging. The mono-complete package provides mono devel for OmniSharp in VS Code.

sudo apt install --assume-yes \
  ack ripgrep git-gui git-cola meld kdiff3 chromium-browser mono-complete
sudo snap install code --classic
sudo snap install paratext --beta
sudo snap install paratextlite
sudo snap install chromium-ffmpeg

Let VS Code, dotnet, etc. watch lots of files.

sudo tee --append /etc/sysctl.conf >/dev/null <<END
fs.inotify.max_user_watches=10000000
fs.inotify.max_user_instances=10000000
END
sudo sysctl -p

Run the Ansible playbook to install additional development dependencies. Ansible will prompt for your password for sudo. Note that ansible 2.10.7 in Ubuntu 22.04 (jammy) is too old and will hang at "Gathering facts". Use a newer ansible from the PPA.

sudo add-apt-repository --yes --update ppa:ansible/ansible
sudo apt install --assume-yes ansible
cd ~/code/web-xforge/deploy && 
  ansible-playbook playbook_focal.yml --limit localhost --ask-become-pass

Instruct SF to use mercurial in /usr/bin:

tee --append ~/.pam_environment <<< 'HG_PATH=/usr/bin/hg'
export HG_PATH=/usr/bin/hg

Configure MongoDB to listen on ipv6, to prevent error "MongoServerSelectionError: connect ECONNREFUSED ::1:27017", either using the command below, or manually performing what it describes in comments.

sudo python3 <<END
# Edit file /etc/mongod.conf
import re; file="/etc/mongod.conf"; data=open(file).read(); 
# After line '  port: 27017', insert line '  ipv6: true'.
data=re.sub(r'(port: 27017\n)', r'\1  ipv6: true\n', data); 
# Append ',::1' to the bindIp line.
data=re.sub(r'(bindIp: [\d.]+)', r'\1,::1', data); 
open(file, 'w').write(data)
END
# Restart MongoDB using the changed configuration.
sudo systemctl restart mongod.service

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

Install build dependencies. Run SF.

cd ~/code/web-xforge && dotnet tool restore
cd ~/code/web-xforge/src/RealtimeServer && npm ci
cd ~/code/web-xforge/src/SIL.XForge.Scripture/ClientApp && npm ci
cd ~/code/web-xforge && dotnet build
cd ~/code/web-xforge/src/SIL.XForge.Scripture/ && dotnet run

Browse to http://localhost:5000

Windows development setup

  1. Install git, e.g. Git Kraken

  2. Clone the repo from the command line including recursing submodules:

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

  3. Install MongoDB v7 as a service.

    Modify the mongod.cfg file. The net section should use ipv6, as follows. Reboot before running dotnet run in a later step.

    # network interfaces
net:
  port: 27017
  ipv6: true
  bindIp: 127.0.0.1,::1

  4. Install .Net SDK 8.0

  5. Install Node v18

  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 the following folders, owned by you. You can check for an updated list of folders in deploy/dependencies.yml.

  • C:/var/lib/scriptureforge/sync/
  • C:/var/lib/scriptureforge/audio/
  • C:/var/lib/scriptureforge/training-data/
  • C:/var/lib/xforge/avatars/
  1. Add developer secrets. Ask another developer how to get these.
  2. Copy deploy/files/InternetSettings.xml to %localappdata%/Paratext95. If you have installed Paratext 9, and completed the initial setup on first run, then this step may be taken care of for you.
  3. In src/RealtimeServer, run npm ci
  4. In src/SIL.XForge.Scripture/ClientApp, run npm ci
  5. In src/SIL.XForge.Scripture/, run dotnet run. Browse to http://localhost:5000.
Clone this wiki locally