Skip to content

Development environment

Jump to bottom
marksvc edited this page Nov 12, 2024 · 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 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

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 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. Ansible will prompt for your password for sudo.

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

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

  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/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