-
Notifications
You must be signed in to change notification settings - Fork 204
Development Setup Guide
This guide should get the iNaturalist web application and API running on a Mac with Docker and homebrew. As of 2022, Almost everything will run on an M1 Mac, except for parts of the API. For developers working on other operating systems, Docker should work, and installing dependencies individually should work too, but you'll have to figure that out yourself. Ubuntu users might also want to check out our Github Actions CI config, which demonstrates how we assemble a build environment for automated testing.
Fair warning: it's kind of a pain in the neck, even with Docker.
- Install homebrew for installing software on the host
- Install Docker for running containerized services for the PostgreSQL, elasticsearch, redis, etc.
- Install RVM for managing Ruby versions
- Install NVM for managing node versions
# Install git if you haven't already
brew install git
# We use imagemagick for processing observation photos and profile pics
brew install imagemagick
# We use exiftool for doing some photo metadata processing
brew install exiftool
# We use ffmpeg to manipulate sound files
brew install ffmpeg
# You will probably need postgres libraries on the host to compile the Ruby postgres gem
brew install libpq
# The RGeo gem will need this
brew install geos
# Check out the Rails and API apps
git clone git@github.com:inaturalist/inaturalist.git
git clone git@github.com:inaturalist/iNaturalistAPI.git
cd inaturalist
# Install the specified Ruby version and use it. Note that CFLAGS seems to be required if you have an M1
CFLAGS="-Wno-error=implicit-function-declaration" rvm install $(cat .ruby-version)
rvm use
# Install gems w/ CFLAGS
gem install bundler
CFLAGS="-Wno-error=implicit-function-declaration" bundle
# Customize the docker config
cp docker-compose.override.yml.example docker-compose.override.ymlCustomize the values in docker-compose.override.yml if you want a username and password for Postgres that aren't inaturalist / inaturalist. See the Docker docs for other available postgres ENV variables.
# Init and start the docker services
make servicesIf you don't think you'll ever work on the API you can also run make services-api to include the API and run in the foreground (you'll also need to add working versions of docker-compose.override.yml and config.js to that directory to get the API to run). If iNaturalistAPI is not in a sibling directory to this repository specify the path as such: make services-api API_PATH=path/to/api.
# Run the setup script to install gems, wipe any existing copy of the database and setup a new one, etc.
ruby bin/setup
# Start the server
bundle exec rails sIn theory http://localhost:3000 should now load without an exception. Not everything will work on the site, but this is a good time for a reality check.
Now you'll want to get the Javascript frontend stuff working.
# Install the specified version of node with NVM
nvm install
# Install node packages
npm install
# Build all the React JS files with webpack. You could also start an ongoing
# process that will rebuild whenever it detects changes to the react files using
# `npm run webpack-watch`
npm run webpack That should get you mostly set up in Rails. Here's some optional stuff you'll probably want want to do
# Create an admin user for yourself. You'll probably want to edit the credentials here
bundle exec rails r "admin = User.create!( login: 'admin', email: 'admin@youremaildomain.net', password: 'adminpassword', password_confirmation: 'adminpassword', confirmed_at: Time.now ); admin.roles << Role::ADMIN_ROLE"
# Install some GIS software and load some timezones and places
brew install gdal
curl -OL "https://github.com/evansiroky/timezone-boundary-builder/releases/download/2021c/timezones-with-oceans.shapefile.zip"
unzip timezones-with-oceans.shapefile.zip
bundle exec rails r tools/load_time_zone_geometries.rb combined-shapefile-with-oceans.shp
bundle exec rails r tools/import_natural_earth_countries.rb
bundle exec rails r tools/import_us_states.rb
bundle exec rails r tools/import_us_counties.rb # probably overkill for development
ruby script/delayed_job start # enables notification feed in DashboardThe Rails app will run on its own, but a lot of it depends on the node API running in parallel, particularly the core pages like observation detail and taxon detail.
cd ../iNaturalistAPI
nvm install
cp config_example.js config.js
nvm install
npm install
node app.jsUnfortunately if you have an M1 Mac you're going to hit problems compiling mapnik. Instead, do this:
git checkout no-maps
npm install
node app.jsThat's a hacky workaround that removes some core mapping functionality from the API, but it will get the app running.
At this point you should have the Rails and node apps running at http://localhost:3000 and http://localhost:4000, respectively. You should have some seed data so localhost:3000/taxa/Animalia should load.
You could also run our test suite:
# in Rails
bundle exec rspec # this will take FOREVER
# you could also just run something small
bundle exec rspec spec/models/saved_location_spec.rb
# in the node API
npm test