Docker

Running the Docker Container

Scripture Forge has a Docker container, which can be used for running in a development environment.

Before You Begin

• Ensure that Docker is installed. The easiest way is with Docker Desktop.
• Add developer secrets. Ask another developer how to get these.
• If the MongoDB service is running on your computer, stop it:
  • Linux: sudo systemctl stop mongod
  • Windows: sc stop mongodb

Linux: Running from the command line

1. Change to the src/Docker directory
2. Build the container: docker compose build
3. Start the container: docker compose up
4. Shutdown the container by pressing Ctrl+C

Windows/Linux: Run from Visual Studio Code

1. Run the task: docker-compose-up
2. To debug .NET, use the "Docker .NET Attach (Preview)" configuration

Windows: Run from Visual Studio

1. Change the project dropdown in the Visual Studio toolbar to: "Docker"
2. Run: "Docker Compose"

Notes

• By default your user secrets will be imported into the container.
  • If you encounter issues with this, you may need to copy them from ~/.microsoft/usersecrets/4d0606c3-0fc7-4d76-b43b-236485004e81/secrets.json to /root/.microsoft/usersecrets/4d0606c3-0fc7-4d76-b43b-236485004e81/secrets.json
• Currently only debugging .NET code is supported.
• The .override.yml file contains configuration that is loaded by default on developer machines to help the container run in a dev friendly way.
• This configuration has been tested on Windows 11 and Ubuntu 23.04 using the latest Docker Desktop, and Ubuntu 20.04 using Docker Engine.

Troubleshooting

• Your Scripture Forge directory should be in a functional state before building the image. Follow the Cleaning instructions if the image is not building.
• If that fails, reset your Docker state:
  1. Stop all docker containers.
  2. Run docker system prune -a to delete all images.

End-to-end running on the Vagrant machine

This Docker container will run on the Vagrant machine, but will require some initial setup and configuration to do so.

Note: This is not something you will need to do, unless you use the Vagrant machine for development.

Initial Setup

Start the vagrant guest machine by running the following on your host:

cd web-xforge/deploy/vagrant/sfdev
vagrant up

In the guest, ensure that the file "warning-not-provisioned.txt" file is no longer on the desktop.

Setup and Configuration

In the vagrant guest, do the following.

1. Click "Install Now" to the Software Updater dialog.
2. When the Updater has finished, click "Restart Now".
3. Open a terminal and run (substituting values where enclosed in {} brackets):

# Update packages
sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y
# Setup Git
git config --global user.name "{my_name}"
git config --global user.email "{my_email}"
# Add Docker GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
# Add Docker repo
echo \
    "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
    "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# Install Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Add vagrant user to docker group
sudo groupadd -f docker
sudo usermod -aG docker $USER
newgrp docker
# Test Docker
docker run hello-world
# Configure user secrets
cd ~/src/web-xforge/src/SIL.XForge.Scripture
dotnet user-secrets set "Auth:BackendClientSecret" "{backend_client_secret}"
dotnet user-secrets set "Paratext:ClientId" "{paratext_client_id}"
dotnet user-secrets set "Paratext:ClientSecret" "{paratext_client_secret}"
dotnet user-secrets set "Paratext:ResourcePasswordHash" "{paratext_resource_password_hash}"
dotnet user-secrets set "Paratext:ResourcePasswordBase64" "{paratext_resource_password_base64}"
# Create debugger directory (before it's created later with root ownership)
mkdir ~/.vsdbg

4. Reboot the vagrant machine (to apply the new docker group)
5. Open a terminal and run:

# Stop Mongo
sudo systemctl stop mongod
# Build the Docker image
cd ~/src/web-xforge/src/Docker
docker compose build
docker compose up

6. Open http://localhost:5000/ using a web browser, and log into Scripture Forge.
7. Run Visual Studio Code.
8. In Visual Studio Code, do the following.
   1. Open the folder "~/src/web-xforge"
   2. Click "Yes, I trust the authors"
   3. Click the Extensions button in the sidebar
   4. In the Recommended list, click "Install" next to Docker
   5. Wait. Next to the C# extension, click "Reload Required"
   6. Click the Run and Debug button in the sidebar
   7. Click the down arrow in the configuration selector and select "Docker .NET Attach (Preview)"
   8. Click the Play button
   9. Select the process "dotnet" from the dropdown that will appear at the top center of the window