LiteFarm is the world’s first community-led, not-for-profit, digital platform joining farmers and scientists together for participatory assessment of social, environmental and economic outputs of farming systems. LiteFarm is the first application of its kind specifically tailored to the needs of diversified farmers with built-in pathways to provide expert decision support and help them earn additional income through payment for ecological services (PES) schemes and in-app certifications (such as organic). These approaches serve the multiple purposes of incentivizing adoption of sustainable land use practices through the provision of evidence-based decision support, and significantly increasing the amount of data being collected by diversified farming operations around the globe. It was developed with farmers at the center of the design process and built from the ground up with accessibility and approachability in mind. We are proud of our mission:

To meet farmers where they are and equip them with the tools they need to make informed and responsible decisions about the health of their farm, their livelihood, their community, and the planet.

LiteFarm version 1.0.0 was released to the public in July 2020. The LiteFarm app is continually being developed, with farmers, researchers, designers and developers working together to create new localized modules and features into the future. LiteFarm is deployed in Canada, the USA, and Latin America.

If you’re a farmer and would like to join LiteFarm you can sign up today at app.litefarm.org. If you are a researcher or would like to find out more about this project you can contact the UBC Centre for Sustainable Food Systems. If you're a developer, welcome to the team! All the details on how you can contribute to this project are right here.

LiteFarm is comprised of three applications which all reside in this monorepo.

• packages/webapp is the client-facing application
• packages/api is the back-end API server with entry point src/server.js
• packages/api/src/jobs is the "jobs scheduler" for certification exports, with entry point index.js

1. Check to see if you have Node.js installed. We use the version specified in the .nvmrc file of each folder with package imports. On a Mac use the command node -v in terminal. If it is installed, the version in use will be reported in the terminal. If not, install it from node.js.
2. Check to see if you have NVM installed. On a Mac use the command nvm -v. If you do not have NVM (Node Version Manager) installed, install it using these instructions: NVM
3. Check to see if you have pnpm installed. On a Mac use the command pnpm -v. If it is installed, the version will be reported. If you do not have it installed, run npm install -g pnpm in a terminal.
4. Clone the repository from Github to your computer. On a Mac, in a Terminal window navigate to the directory you want to put the files in. Then use the command git clone https://github.com/LiteFarmOrg/LiteFarm.git.
5. Install all packages:

• Switch to current version of Node.js by running nvm use in the root folder
• Navigate to the root folder / of the repo and run npm install.
• Navigate to the packages/api folder, and run npm install.
• Navigate to the packages/webapp folder, and run pnpm install.
• Navigate to the packages/shared folder, and run npm install.

6. (Highly recommended) Go to Get Docker | Docker Documentation and install Docker. Docker is the recommended method for setting up development dependencies, but alternative instructions will be provided as well if you are unable to use Docker. There will be extra instructions for each operating system. For example: Windows requires Windows subsystem for linux (WSL). Mac users may need to enable experimental/beta settings for Mac users.

The applications are configured with environment variables stored in .env files. Configuration information includes secrets like API keys, so the .env files are not included in this git repository.

This repository contains a .env.default file for both api and webapp. These files contain directions to acquire the personal keys needed to get LiteFarm running locally. Please note you will want to copy .env.default and rename the file to .env. Only after adding the .env file should you proceed to add the new keys. If you add your api keys to .env.default you may accidentally expose your keys since this file is tracked on git.

If you have questions about the other api keys, or wish to join the LiteFarm team, please contact [email protected].

Run docker compose up in the root directory to configure and start all development dependencies, including the database.

For more information, see services (local development dependencies) below.

Once the database container is running and the .env files have been configured as described above, in a terminal navigate to the packages/api folder. Execute npm run migrate:dev:db to run the migrations that set up the PostgreSQL database used by the app.

   # Install homebrew if you don't already have it with the command:
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
   # Install PostgreSQL.
   brew install postgresql
   # Start the Database Management Systems (DBMS) service.
   brew services start postgresql

In a terminal, navigate to the packages/api folder. Run npm run nodemon to launch the backend application. Nodemon will automatically restart the application when changes are made to the backend code.

In a terminal, navigate to the packages/webapp folder and run pnpm dev. This builds the frontend code, and starts a web server that will automatically reflect any changes you make to the frontend.

Load the frontend app in your browser at http://localhost:3000.

Run docker compose up in the root directory of the project.

Make sure that your .env variables are configured as outlined in the .env.default files (see section above). When exporting certification documents, both the webapp and API need to be running.

Also see the section below on using Docker.

Note: the export server is not usually needed, and so is not started with the other development dependencies. To start it, make sure the the webapp and API are already running, and use the command docker compose up export.

DO_SPACES_ACCESS_KEY_ID=myminioadmin
DO_SPACES_SECRET_ACCESS_KEY=myminioadmin

IMAGINARY_TOKEN=localonlytoken
LOCAL_IMAGINARY=http://localhost:8088

To run ESLint checks execute npm run lint

The chai.js and jest libraries automate tests that run real database operations using a dedicated database named test_farm, distinct from the pg-litefarm database that the app normally uses.

You'll want to confirm that you have an empty test_farm database (otherwise use your preferred database client to create one) before continuing with the following:

1. In a terminal, navigate to the packages/api folder.
2. Execute npm run migrate:testing:db to set up the test database.
3. Execute npm test to launch the tests. Or, to generate test coverage information, run npm test -- --coverage . and then see the coverage/index.html file.

While the tests do attempt to clean up after themselves, it's a good idea to periodically use psql or your database client to DROP and CREATE the test_farm database, followed by the migrations from step 2 above.

To run ESLint checks execute pnpm lint

Since this is a mobile web application, webapp should be viewed in a mobile view in the browser.

You can also test LiteFarm on your actual mobile device using the network adddress returned by vite --host when you start the webapp in development mode. To do this, also update VITE_API_URL in your webapp/.env file from localhost to that address (or your computer's network name) and the appropriate API port. Most of LiteFarm can be tested like this, but please note that Google SSO and some other functionality will not work over the local network.

Please see https://ngrok.com/ for more general information about ngrok.

While not required for most developers, use cases in which we currently utilize ngrok at LiteFarm include:

• Testing local changes on phones or different devices
• Testing local changes when working with other APIs and integrations

• Go to https://ngrok.com/ and sign up for an account
• Install the ngrok CLI (on the Getting Started page after signing up)
• Create a copy of ngrok/ngrok.default.yml and call it ngrok.yml. Make sure this file is in the ngrok folder at the root of the repo
• Login to your ngrok account and go to https://dashboard.ngrok.com/get-started/your-authtoken
• Add the auth token from there in ngrok.yml by replacing the ?

These commands can be run from the root of the repo.

• npm run ngrok to forward both backend and frontend ports with ngrok
• npm run ngrok:setup to add the ngrok urls to the file .env files (always run after forwarding a port to ngrok)
• npm run ngrok:api to forward the backend port with ngrok
• npm run ngrok:webapp to forward the frontend port with ngrok

Note: Please make sure to run the commands in the following order:

• npm run ngrok or npm run ngrok:api or npm run ngrok:webapp
• npm run ngrok:setup (in a new terminal)
• pnpm dev (in a new terminal from the packages/webapp folder)
• npm run nodemon (in a new terminal from the packages/api folder)

Please see https://docs.docker.com/ for more general information about docker.

Use cases in which we currently utilize docker at LiteFarm include:

• Managing development dependencies in the local development environment, including the database and services for working with images, files, and exports
• Simulating the server environment.
• Building LiteFarm application using docker commands and supporting its components using containers.

• Go to https://docs.docker.com/get-docker/ and install docker in your local system.
• After installation, you can run Docker commands using the Docker CLI.
• To build the beta/prod Docker containers (generally used when troubleshooting the build process), you will also need to:
  • create a .env file at the root directory of the project i.e. LiteFarm
  • add key-value pairs in the .env by referring to the docker-compose.[ENV].yml that contains the docker env keys

These commands can be run from the root of the repo.

• docker compose up to start the main development services
• docker compose up export to start the process that handles certification document export
• docker compose up [service names] to run one or more particular services
• docker compose down to stop and remove all containers defined in docker-compose.yml
• docker compose down --volumes to stop and remove all containers and volumes defined in docker-compose.yml
• docker-compose -f docker-compose.[ENV].yml up --build to build the beta/prod docker containers
• docker ps to see the list of docker containers in the running state.
• docker logs --details [containers name] to view the logs inside the container.

Notes:

• [service names] are db, minio, redis, export, and imaginary
• [container_name] are litefarm-db, litefarm-api and litefarm-web.
• [ENV] are beta and prod

You can use Storybook to visualize and test out the UI components used throughout the app.

• To view Storybook on your local environment, run pnpm storybook on the packages/webapp directory and navigate to http://localhost:6006
• To view the deployed version of Storybook, which is updated automatically with the latest changes on the integration branch, go to https://65316fc4f177c73a9181a843-yobioprfjv.chromatic.com

Please email: [email protected] for more details.