This document provides a guide to installing the FarmData2 project. There are separate sections for doing a developer install and a user install. If you are interested in working on and contributing to the FarmData2 project follow the Developer Install section. If you are interested in using the FarmData2 application follow the User Install section.
There is a dedicated Install stream on the FarmData2 Zulip chat. This is the place to ask and look for answers to your install related questions.
FarmData2 is currently in the early stages of development and thus is not ready for independent use. This section will be updated when FarmData2 has reached a state of development that is suitable for use. In the meantime, please contact braught@dickinon.edu or allen@npfi.org for credentials if you would like to explore the trial instance available at FarmData2 Trial.
Before beginning this install please review the CONTRIBUTING.md document and in particular be sure to follow the links to the CODE_OF_CONDUCT.md that sets the expectations for the FarmData2 community.
We recommend Ubuntu Linux as the development platform for FarmData2. It is the development platform used by the core team and thus is the most well understood and most fully tested. Users of Windows and MacOS should consider using Ubuntu Linux within Virtual Box as their development platform. That said, developers experienced with tools like git, docker and docker-compose should not face any substantial barriers to development directly on Windows, MacOS or other Linux flavors.
The following are some recommendations for setting up a development platform using Linux in VirtualBox:
- The FOSS guide to Install Linux Inside Windows Using VirtualBox is a good place to start if you are unfamiliar with this process. This is a guide for Windows, but works equally well for MacOS with a little adaptation.
- If your machine has 8GB or more of RAM Ubuntu Desktop is recommended with an allocation of at least 4GB of RAM to the virtual machine.
- If your machine has less than 8GB of RAM Ubuntu based Linux Lite is recommended with an allocation of half of the machine's RAM to the virtual machine.
- When creating your virtual machine:
- Allocate a virtual disk of at least 30GB.
- Set the Video Memory to 128 MB.
- MacOS: If you are running VirtualBox on MacOS using a machine with a retina display the performance can be quite sluggish. Launching VirtualBox in Low Resolution Mode will resolve this issue.
FarmData2 relies on a few prerequisite programs that will need to be installed on your development platform. You will need to install
- git
- docker
- docker-compose
Under Ubuntu Linux these tools can most easily be installed using the apt or synaptic package managers. You might read the It's FOSS Complete guide to Using apt Commands in Linux if you are unfamiliar with apt.
Full installation details for other platforms can be obtained from the projects themselves on the following sites:
If you are developing under Linux you will need to be able to Manage Docker as a non-root user. To do so you need to add your user to the docker group. Use the following commands:
sudo groupadd docker
sudo usermod -aG docker $USER
Then log out and back into the system. When you log back in your user will have the permissions needed in order to use docker commands. Note that if you are developing on a virtual machine you will need to restart the virtual machine for the changes to take effect.
FarmData2 is hosted in a GitHub repository that can be found here:
To get started:
- Create a GitHub Account (if you do not already have one).
- To access GitHub via the command line git tools you will need to Create a personal access token in GitHub.
- You will also probably want to Store your GitHub Credentials with the Git Credential Helper to avoid retyping the token for every operation.
- Fork the FarmData2 repository into your own GitHub account.
- Clone your fork of FarmData2 to your development machine.
- Set your upstream remote to point to the main FarmData2 repository at https://github.com/DickinsonCollege/FarmData2.
The FarmData2 repository contains a sample database with anonymized data from several years of operation of the Dickinson College Farm. This database is in the compressed file docker/db.sample.tar.bz2 and needs to be expanded before it can be used. Change into the docker directory in the repository and use the command below:
./setDB.bash sample
When this command completes there should be a db directory in the docker directory. The files in this db directory are a mySQL database that contain the sample data. Note that you will only need to do this step once. But the above command can be used at any time to reset the database to its initial state.
To start FarmData2 ensure that you are in the docker directory in the repository and use the command below:
./fd2-up.bash
This command will start up the docker containers that are used by FarmData2. There will be lots of output from this command and the first time you run it, it may take a while to complete as it pulls, downloads and extracts the docker images to your machine.
If you encounter an error similar to Cannot start service www, it can likely be fixed by entering the command
sudo service apache2 stop
That's it! You now have a running version of FarmData2 that is loaded with the sample data set and is suitable for development work.
Open a browser and go to:
http://localhost
If everything has worked you will see the FarmData2 login screen.
- Click on "Login to farmOS"
- Log in using one of the following credentials:
- Administrator:
- Username:
admin - Password:
farmdata2
- Username:
- Farm Managers:
- Username:
manager1(or2) - Password:
farmdata2
- Username:
- Farm Workers:
- Username:
worker1(or2,3,4) - Password:
farmdata2
- Username:
- Guest:
- Username:
guest - Password:
farmdata2
- Username:
- Administrator:
The code and documentation can be edited with any editor. For convenience, the FarmData2 installation includes a browser-based integrated development environment (IDE). To use this IDE open a browser tab and go to:
http://localhost:3000
When the IDE opens:
- Click "Open Workspace"
- Select the
FarmData2directory - Click "Open"
The explorer on the left will show the contents and structure of the FarmData2 repository. More information about getting started working on the FarmData2 code and documentation can be found in the CONTRIBUTING document.
The above process of installing FarmData2 only needs to be completed once. Now you will need only to start and stop the docker containers before and after each work session.
From the docker directory in the repository you can:
- Stop FarmData2:
./fd2-down.bash
- Start FarmData2:
./fd2-up.bash
The fd2-up.bash and fd2-down.bash scripts use docker-compose to start all of the FarmData2 containers. When ./fd2-down.bash is run docker-compose removes all of the containers, including their writeable layers. The containers are all recreated, including blank writeable layers, each time the fd2-up.bash is used. However, all of the FarmData2 data and code is mounted from the development machine and thus will persist between uses. You can find all of the details of the mounted volumes in the docker-compose.yml file.
The FarmData2 database, that we expanded earlier, is mounted into the container from the directory:
docker/db
The FarmData2 code is mounted into the container from the directories:
contrib_modulesfarmdata2_modules
Changes to the code in these directories on the development machine will be reflected by the instance of FarmData2 running in the container.
For developers working on back-end services and the FarmData2 data model the installation starts a phpMyAdmin service that is available at localhost:8181. You can connect to this service as an administrator using the credentials:
- Username:
root - Password:
farm