|
||
---|---|---|
app | ||
bin | ||
config | ||
db | ||
lib | ||
mqtt | ||
public | ||
spec | ||
typings | ||
webpack | ||
.buildpacks | ||
.codebeatignore | ||
.codeclimate.yml | ||
.coveralls.yml | ||
.gitignore | ||
.ruby-gemset | ||
.ruby-version | ||
.travis.yml | ||
api_docs.md.erb | ||
codecov.yml | ||
config.ru | ||
CONTRIBUTING.md | ||
DEPLOYMENT.md | ||
dokku.sh | ||
fake_logs.rb | ||
Gemfile | ||
Gemfile.lock | ||
ISSUE_TEMPLATE | ||
latest_corpus.rb | ||
LICENSE | ||
package.json | ||
Procfile | ||
Procfile.dev | ||
Rakefile | ||
README.md | ||
tsconfig.json | ||
tslint.json | ||
ubuntu_example.sh | ||
yarn.lock |
FarmBot Web App
Q: Do I need this?
This repository is intended for software developers who wish to modify the Farmbot Web App. If you are not a developer, you are highly encouraged to use the publicly available web app. Running a server is a non-trivial task with security implications. It requires an intermediate background in Ruby, SQL and Linux system administration.
If you are a developer interested in contributing or would like to provision your own server, you are in the right place.
Q: Where do I report security issues?
We take security seriously and value the input of independent researchers. Please see our responsible disclosure guidelines.
Q: What is the Farmbot Web App?
This repo contains FarmBot's web based user interface, a RESTful JSON API and a Dockerized MQTT server. The API stores data such as user account information, plant data, authorization tokens and a variety of other resources. The MQTT server facilitates realtime messaging from the browser to the device.
Q: Can I see some example API requests?
For a list of example API requests and responses, see our reference documentation. If you wish to write an add-on application that uses the FarmBot API, please let us know in an issue. We are happy to answer any specific questions you may have.
Q: How do I Setup an instance locally?
Prerequisites
You will need the following:
- A Linux or Mac based machine. We do not support windows at this time.
- Docker 17.06.0-ce or greater
- Ruby 2..5.0
- ImageMagick (
brew install imagemagick
(Mac) orsudo apt-get install imagemagick
(Ubuntu)) - Node JS >= v8.9.0
libpq-dev
andpostgresql
andpostgresql-contrib
gem install bundler
Setup
NOTE: A step-by-step setup guide for Ubuntu 17 users can be found here
Setup for non-Ubuntu users after installing the dependencies listed above:
git clone https://github.com/FarmBot/Farmbot-Web-App --branch=master --depth=10
cd Farmbot-Web-App
bundle install
yarn install
- Database config: Copy
config/database.example.yml
toconfig/database.yml
viacp config/database.example.yml config/database.yml
- App config: MOST IMPORTANT STEP. Copy
config/application.example.yml
toconfig/application.yml
viamv config/application.example.yml config/application.yml
. Please read the instructions inside the file. Replace the example values provided with real world values. - Give permission to create a database*
rake db:create:all db:migrate db:seed
- (optional) Verify installation with
RAILS_ENV=test rake db:create db:migrate && rspec spec
(API) andnpm run test
(Frontend). - Start server with
rails api:start
. Make sure you set anMQTT_HOST
entry inapplication.yml
pointing to the IP address or domain of MQTT server. If you are not running the MQTT server on a separate machine,MQTT_HOST
andAPI_HOST
will point to the same server. - Start MQTT with
rails mqtt:start
. Important note: You may be required to enter asudo
password because docker requires root access. - Open localhost:3000.
- Raise an issue if you hit problems with any of these steps. We can't fix issues we don't know about.
*Give permission to user
to create database:
sudo -u postgres psql
CREATE USER "user" WITH SUPERUSER;
Q: Is Dokku / Docker supported?
Dokku (a Docker management system) is partially supported. Pull requests welcome. Please see deployment.md
for more information.
Config Settings (important)
We try our best to follow the 12 Factor Methodology. Part of that means using ENV variables as a means of storing configuration. Your server won't run without setting ENV variables first.
You can accomplish this by setting the ENV variables directly from your shell / server management tool or by writing an application.yml
file.
See config/application.example.yml
for a list of all the variables that must be set.
Encryption keys: Encryption keys will be auto-generated if not present. They can be reset using rake keys:generate
. If ENV['RSA_KEY']
is set, it will be used in place of the *.pem
files. Useful for environments like Heroku, where file system access is not allowed.
We can't fix issues we don't know about. Please submit an issue if you are having trouble installing on your local machine.
Q: How can I Generate an API token?
You must pass a token
string into most HTTP requests under the Authorization:
request header.
Here's what a response looks like when you request a token:
{
"token": {
"unencoded": {
"sub": "test123@test.com",
"iat": 1459109728,
"jti": "922a5a0d-0b3a-4767-9318-1e41ae600352",
"iss": "http://localhost:3000/",
"exp": 1459455328,
"mqtt": "localhost",
"bot": "aa7bb37f-5ba3-4654-b2e4-58ed5746508c"
},
"encoded":
// THE IMPORTANT PART IS HERE!!:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ0ZXN0MTIzQHRlc3QuY29tIiwiaWF0IjoxNDU5MTA5NzI4LCJqdGkiOiI5MjJhNWEwZC0wYjNhLTQ3NjctOTMxOC0xZTQxYWU2MDAzNTIiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvIiwiZXhwIjoxNDU5NDU1MzI4LCJtcXR0IjoibG9jYWxob3N0IiwiYm90IjoiYWE3YmIzN2YtNWJhMy00NjU0LWIyZTQtNThlZDU3NDY1MDhjIn0.KpkNGR9YH68AF3iHP48GormqXzspBJrDGm23aMFGyL_eRIN8iKzy4gw733SaJgFjmebJOqZkz3cly9P5ZpCKwlaxAyn9RvfjQgFcUK0mywWAAvKp5lHfOFLhBBGICTW1r4HcZBgY1zTzVBw4BqS4zM7Y0BAAsflYRdl4dDRG_236p9ETCj0MSYxFagfLLLq0W63943jSJtNwv_nzfqi3TTi0xASB14k5vYMzUDXrC-Z2iBdgmwAYUZUVTi2HsfzkIkRcTZGE7l-rF6lvYKIiKpYx23x_d7xGjnQb8hqbDmLDRXZJnSBY3zGY7oEURxncGBMUp4F_Yaf3ftg4Ry7CiA"
}
}
Important: The response is provided as JSON for human readability. For your Authorization
header, you will only be using data.token.encoded
. In this example, it's the string starting with eyJ0eXAiOiJ...
Via CURL
curl -H "Content-Type: application/json" \
-X POST \
-d '{"user":{"email":"test123@test.com","password":"password123"}}' \
https://my.farmbot.io/api/tokens
Via JQuery
Since the API supports CORS, you can generate your token right in the browser.
Here's an example:
$.ajax({
url: "https://my.farmbot.io/api/tokens",
type: "POST",
data: JSON.stringify({user: {email: 'admin@admin.com', password: 'password123'}}),
contentType: "application/json",
success: function (data) {
// You can now use your token:
var MY_SHINY_TOKEN = data.token.encoded;
}
});
Want to Help?
Low Hanging Fruit. Raise an issue if you have any questions.
Translating the web app into your language
Thanks for your interest in internationalizing the FarmBot web app! To add translations:
- Fork this repo
- Navigate to
/public/app-resources/languages
and run the commandnode _helper.js yy
whereyy
is your language's language code. Eg:ru
for Russian. - Edit the translations in the file created in the previous step:
"phrase": "translated phrase"
. - When you have updated or added new translations, commit/push your changes and submit a pull request.