Skip to content

Development environment

Jump to bottom
marksvc edited this page Jun 12, 2025 · 45 revisions

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

Vagrant development machine

Setup

If you have trouble, make sure that virtualization is enabled (Enable virtualization) in your BIOS/UEFI. You may need to Disable Hyper‐V in Windows.

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.
  • In the guest, have a look at the machine-instructions.txt file on the desktop. Set local server secrets.
  • Install security and VS Code updates in the guest by doing the following. Either click "Install Now" on the "Software Updater" dialog and wait for it to start, or launch a terminal and run the following commands. The vagrant password is "vagrant".
sudo apt update
sudo apt upgrade

When installing updates, if asked "Add Microsoft apt repository for Visual Studio Code?", you can leave it selected. If asked "GRUB install devices", you can select "/dev/sda2 (.. MB; /boot/efi)..". When asked "Continue without installing GRUB?", you can select the checkbox.

  • Reboot the guest to finish applying security updates.
  • Start Scripture Forge by running the following.
cd ~/code/web-xforge/src/SIL.XForge.Scripture
dotnet run

Re-create guest

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

  • Update the git repository on your host, such as by doing the following in the web-xforge repository directory on your host:
git checkout master
git pull --ff-only
  • 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 box. Consider page Manually-update-vagrant-box if you have network trouble with this command.
  • 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.

Note that in early 2025 some changes to vagrant servers may require a settings change to a file on your host computer. If you have trouble updating your vagrant box, first use these commands on your host to re-write a configuration file's content with no newline at the end of the file, which is important. The first command, cat is just to check what the file's content is before we overwrite it. (TODO: What are the equivalent commands in Windows?)

cat ~/.vagrant.d/boxes/marksvc-VAGRANTSLASH-sfdev/metadata_url
echo -n "https://vagrantcloud.com/api/v2/vagrant/marksvc/sfdev" > ~/.vagrant.d/boxes/marksvc-VAGRANTSLASH-sfdev/metadata_url

Checking guest version

Running vagrant box update on the host reports on the vagrant box version. You can also check by running cat ~/machine-info.txt inside the vagrant guest machine, which might show some content like

Vagrant base box information
Name: sfdev
Version: 1.2.0

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.

sudo apt install --assume-yes git
mkdir --parents ~/code && cd ~/code
git clone 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 dev-server.playbook.yml --limit localhost --diff --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 the below 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:

    git clone 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 Paratext's 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