Development environment

• 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 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.

Local Linux Development Setup

sudo apt update
sudo apt install --assume-yes git ansible
# Go to where you want to clone the repo. In the below instructions, 
# replace ~/code/web-xforge with the path to your cloned repo.
mkdir --parents ~/code && cd ~/code
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.

Optionally install useful tools:

sudo apt install --assume-yes ack ripgrep git-gui git-cola meld kdiff3
sudo snap install paratext --beta
sudo snap install paratextlite

Chromium is useful for testing and debugging.

sudo apt install --assume-yes chromium-browser
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

Install mono devel for OmniSharp in VS Code.

sudo apt install --assume-yes mono-complete

Run the following Ansible playbook to install additional development dependencies.

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

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

Install build dependencies.

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

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 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 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/scriptureforge/training-data/
• /var/lib/xforge/avatars/

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

10. Add developer secrets. Ask another developer how to get these.
11. 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.
12. In src/RealtimeServer, run npm ci
13. In src/SIL.XForge.Scripture/ClientApp, run npm ci
14. In src/SIL.XForge.Scripture/, run dotnet run. Browse to http://localhost:5000.