• Stars
    star
    958
  • Rank 47,718 (Top 1.0 %)
  • Language
    Ruby
  • License
    GNU General Publi...
  • Created over 11 years ago
  • Updated 5 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

a collaborative knowledge-exchange platform in Rails; we welcome first-time contributors! 🎈

PublicLab.org

Code of Conduct Build Status first-timers-only-friendly Join the chat at https://publiclab.org/chat Code Climate codecov View performance data on Skylight Newcomers welcome GitHub license Gitpod Ready-to-Code

The content management system for the Public Lab research community, the plots2 web application is a combination of a group research blog -what we call "research notes"-and a wiki. Read more about the data model here.

Begin running (and contributing to) this codebase immediately with GitPod:

Open in Gitpod

It showcases a variety of features that help the Public Lab community collaborate on environmental technology, design, documentation, and community organizing. Originally a Drupal site, it was rewritten in 2012 with Ruby on Rails and has since extended but not yet entirely replaced the legacy Drupal data model and database design. We ❤️ Open Source and actively participate in various OSS programs such as Google Summer of Code(GSoC), Rails Girls Summer of Code (RGSoC), Outreachy, and Google Code-In (GCI). Some key features include:

Roadmap

We are developing a draft Roadmap for plots2 and our broader Public Lab code projects; read more and comment here.

A full description of the features, audiences, inter-relationships, and goals of Public Lab software projects can be found here: https://publiclab.org/software-overview

Table of Contents

  1. What Makes This Project Different
  2. Data model
  3. Contributing
  4. Prerequisites
  5. Installation
  6. SSL in Development
  7. Login
  8. Testing
  9. Maintainers
  10. How to start and modify cron jobs
  11. Bundle Exec
  12. Reply-by-email
  13. Bugs and Support
  14. Recaptcha
  15. Internationalization
  16. Security
  17. Developers
  18. First Time?
  19. Hacktoberfest

What makes this project different

The people who create our platform make very different design and technology decisions from other projects. This stems from our deep belief that, to see a change in the world, we must build and maintain systems that reflect our values and principles.

From design to system architecture to basic vocabulary and communication patterns, our systems have grown organically since 2010 to support a powerful, diverse, and cooperative network of people capable of taking on environmental problems that affect communities globally. The platform we have built together speaks to this shared history in many ways, big and small. It reflects input from people facing serious health issues, on-the-ground organizers, policy specialists, hardware hackers, educators, and civil servants.

This broad community and the Public Lab team have facilitated a space where we can discuss, break down, construct, prototype, and critique real-world projects. Together we have shaped a platform that incorporates familiar pieces but ultimately looks and feels quite different from anything else on the internet. Despite the growth of our platform, it remains committed to hearing the voices of others, mutual respect and support, an awareness of the barriers and challenges presented by gaps in expertise and knowledge, and a sensitivity to the inequalities and power imbalances perpetuated by many mainstream modes of knowledge production and technological and scientific development.

Our mutual aim to democratize inexpensive and accessible do-it-yourself techniques has allowed us to create a collaborative network of practitioners who actively re-imagine the human relationship with the environment. Our goals are supported and facilitated by a system which questions and even challenges how collaborative work can happen.

Data Model

Diagram

(Above: draft of our Data model)

Contributing

We welcome contributions, and are especially interested in welcoming first time contributors. Read more about how to contribute below! We especially welcome contributions from people belonging to groups under-represented in free and open source software!

Code of Conduct

Please read and abide by our Code of Conduct; our community aspires to be a respectful place both during online and in-­person interactions.

Prerequisites

For installation, prerequisites include sqlite3 and rvm. Click here for a complete list and instructions.

Installation

Standard Installation

  1. Fork our repo from https://github.com/publiclab/plots2.
  2. In the console, download a copy of your forked repo with git clone https://github.com/your_username/plots2.git where your_username is your GitHub username.
  3. Enter the new plots2 directory with cd plots2.
  4. Set the upstream remote to the original repository url so that git knows where to fetch updates from in future: git remote add upstream https://github.com/publiclab/plots2.git
  5. Steps to install gems:
    • You may need to first run bundle install if you have older gems in your environment from previous Rails work. If you get an error message like Your Ruby version is 2.x.x, but your Gemfile specified 2.7.3 then you need to install the ruby version 2.7.3 using rvm or rbenv.
      • Using rvm: rvm install 2.7.3 followed by rvm use 2.7.3
      • Using rbenv: rbenv install 2.7.3 followed by rbenv local 2.7.3
    • Run this bundle config set without 'production mysql' from the rails root folder to set your project to exclude libraries only needed in production.
    • Install gems with bundle install from the rails root folder.
  6. Run cp db/schema.rb.example db/schema.rb to make a copy of db/schema.rb.example in db/schema.rb.
  7. You could choose to use mysql2 or sqlite3 as your database. We recommend using sqlite3 as your plots2 database as some of our contributors have reported issues while using mysql2.
    • If mysql2, run cp config/database.yml.mysql.example config/database.yml to make a copy of config/database.yml.mysql.example in config/database.yml
    • If sqlite3, run cp config/database.yml.sqlite.example config/database.yml to make a copy of config/database.yml.sqlite.example in config/database.yml. kindly note if you choose to use sqlite some tests may fail. The project was setup initially to use mysql and some tests are tailored for mysql db. No need for alarm, we are working to fix these and this will not interfere with your development process
  8. Run rake db:setup to set up the database
  9. Install static assets (like external javascript libraries, fonts) with yarn install
  10. Setup React & webpacker by running rails webpacker:install && rails webpacker:install:react && rails generate react:install(for local SSL work, see SSL below)
  • If you get any prompt to overwrite files in this step please choose no. The prompt will be something like "Overwrite /home/plots2/config/webpacker.yml? (enter "h" for help) [Ynaqdhm]" :- type "n" and enter.
  1. Start the server with passenger start and navigate to http://localhost:3000/ on your browser.
  2. Wheeeee! You're up and running! Log in with test usernames "user", "moderator", or "admin", and password "password".
  3. Run rails test to confirm that your install is working properly. You can also run rails test:system for system tests. (Note: if you chose sqlite as your database, some tests may fail; Please ignore these, we are working to fix this. If your server starts correctly, you are all set)

Windows Installation

We recommend you either work in a virtual environment, or on a dual booted system to avoid dependencies issues as Unix systems tend to work smoother with Ruby and Rails. This will not only benefit you now for plots2, but also in the future while working on other Ruby projects, a Linux or Mac based OS will make your development much easier.

  1. Windows Subsystem for Linux (recommended)
  2. Dual Booting, option2, video guide
  3. Setting up a Linux virtual env

Windows Subsystem for Linux 2 Installation

Before continuing with the installation steps in this README, users of Windows Subsystem for Linux 2 (WSL 2) should open the WSL 2 Terminal and type out the commands below.

  1. Install Dependencies required from Ruby Source with the following commands:
  • sudo apt update
  • sudo apt install curl g++ gcc autoconf automake bison libc6-dev
  • sudo apt install libffi-dev libgdbm-dev libncurses5-dev libsqlite3-dev libtool
  • sudo apt install libyaml-dev make pkg-config sqlite3 zlib1g-dev libgmp-dev
  • sudo apt install libreadline-dev libssl-dev
  1. Add GPG Key & Install RVM:
  • Install gnupg2 if you haven't already: sudo apt install gnupg2
  • gpg2 --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
  • curl -sSL https://get.rvm.io | bash -s stable
  1. Load the Script environment variables using source command:
  • source ~/.rvm/scripts/rvm
  1. Install and use specific Ruby version:
  • rvm install ruby-x.x.x (this projects Ruby version)
  • rvm --default use ruby-x.x.x (replace x.x.x with this project's Ruby version)
  1. For further reference, read here

Redis Installation

Public Lab uses Redis and may be required for some functionality when running the application locally.

  1. Install Redis if you haven't already:
  • Using MacOS: brew install redis
  • Using Linux: sudo yum -y install redis
  • Using Ubuntu WSL2:
    • update & upgrade Ubuntu: sudo apt update && apt upgrade
    • install redis: sudo apt install Redis-server
    • open Redis.config file: sudo nano /etc/redis/redis.conf
    • update the file by changing the supervised no line to supervised systemd(ubuntu uses systemd)
    • start Redis: sudo service redis-server start
    • open Redis CLI: redis-cli
    • test Redis: type ping & response should be pong
    • exit cli: type quit
    • Awesome 👍 All done ✅
  1. Run Redis server:
  • Using MacOS: brew services start redis
  • Using Linux: redis-server
  1. Run SideKiq: bundle exec sidekiq
  2. If SideKiq started correctly Redis is now configured and working!

SSL in Development

At Public Lab we use the openssl gem to provide SSL (Secure Sockets Layer) for a secure connection (https) in the development mode. You can run the https connection on localhost through the following steps:

  1. Use passenger start --ssl --ssl-certificate config/localhost.crt --ssl-certificate-key config/localhost.key --ssl-port 3001.
  2. Open up https://localhost:3001.
  3. Add security exceptions from the advance settings of the browser. You can also use http (unsecure connection) on the port number 3000 by going to 'http://localhost:3000'. We use port number 3001 for 'https' and port number 3000 for 'http' connection. Secure connection is needed for OAuth authentication etc.

Login

Once you complete the installation, use any of these credentials to login into the PL website in your local development/testing environment to gain additional permissions for logged in users only. Each one comes with its own set of permissions; nevertheless, the experience across them is pretty much the same.

username: admin, moderator, or user

password: password

For more on the login systems, see this page

Testing

Click here for a comprehensive description of testing and here to learn about system tests.

Maintainers

How to start and modify cron jobs

  1. We are using Whenever gem to schedule cron jobs.
  2. All the cron jobs are written in easy ruby syntax using this gem and can be found in config/schedule.rb.
  3. Go to the config/schedule.rb file to create and modify the cron jobs.
  4. Click here to learn more about how to write cron jobs.
  5. After updating config/schedule.rb file run the command whenever --update-crontab to update the cron jobs.
  6. To see the installed list of cron jobs use command crontab -l
  7. For more details about this gem, visit the official repository of the Whenever gem.

Bundle exec

For some, it will be necessary to prepend your gem-related commands with bundle exec. For example, bundle exec passenger start. Adding bundle exec ensures you're using the version of passenger you just installed with Bundler. bundle exec rake db:setup, bundle exec rake db:seed are other examples of where this might be necessary.

Reply-by-email

Public Lab now supports "reply by email to comment" feature. For more details, go to the email documentation

Bugs and support

To report bugs and request features, please use the GitHub issue tracker

For additional support, join the Public Lab website and mailing list at http://publiclab.org/lists. For urgent requests, email [email protected]

Recaptcha

This application uses RECAPTCHA via the recaptcha gem in production only. For more information, click here.

Internationalization

Publiclab.org now supports Internationalization and localization, though we are in the initial stages. This has been accomplished with rails-I8n.

To see it in action, click on the 'Language' drop-down located in the footer section of the page. All the guidelines and best practices for I18n can be found here.

Translations are arranged in the YAML files here, which are set in a similar way to views files. An example for adding translations can be found here.

Since the implementation of our new Translation system, we now use the translation() helper, found here. This provides some extra translation features such as inserting a prompt visible to site visitors if no translation exists yet. You can learn more about our translation system by reading our Translation system docs.

To add new languages or for additional support, please write to [email protected]

Security

To report security vulnerabilities or for questions about security, please contact [email protected]. Our Web Working Group will assess and respond promptly.

Developers

Help improve Public Lab software!

First Time?

New to open source/free software? Here is a selection of issues we've made especially for first-timers. We're here to help, so just ask if one looks interesting : https://code.publiclab.org

Here is a link to our Git workflow.

Hacktoberfest

Wishing to contribute to Publiclab as part of Hacktoberfest? Check out our Hacktoberfest contributing docs

Let the code be with you.

Happy opensourcing. 😄


Platforms that ❤️ OSS

Twitter Follow

More Repositories

1

Leaflet.DistortableImage

A Leaflet extension to distort or "rubber sheet" images
JavaScript
270
star
2

mapknitter

Upload your own aerial images, position (rubbersheet) them in a web interface over existing map data, and share via web or composite and export for print.
Ruby
267
star
3

community-toolbox

Tools to understand and welcome people into a contributor community
JavaScript
141
star
4

webjack

a JavaScript library that uses an audio software modem to communicate with an Arduino via a headphone jack
JavaScript
136
star
5

spectral-workbench

Web-based tools for collecting, analyzing, and sharing data from a DIY spectrometer
Ruby
126
star
6

leaflet-environmental-layers

Collection of different environmental map layers in an easy to use Leaflet library, similar to https://github.com/leaflet-extras/leaflet-providers#leaflet-providers
JavaScript
99
star
7

PublicLab.Editor

A general purpose, JS/Bootstrap UI framework for rich text posting. An author-friendly, minimal, mobile/desktop interface for creating blog-like content, designed for PublicLab.org
JavaScript
79
star
8

spectral-workbench.js

The JavaScript heart of Spectral Workbench; a Public Lab project to record, manipulate, and analyze spectrometric data.
JavaScript
46
star
9

infragram

A minimal core of the Infragram.org project in JavaScript
HTML
44
star
10

simple-data-grapher

Turns CSVs into graphs in a few simple steps; embeds onto other websites!
JavaScript
38
star
11

leaflet-blurred-location

A Leaflet-based interface for selecting a "blurred" or low-resolution location, to preserve privacy
JavaScript
35
star
12

inline-markdown-editor

An inline wysiwyg markdown document editor based on replacing string subsections. WYSIWYG possible via woofmark.
JavaScript
30
star
13

pi-builder

Developing a reproducible build script system for making Raspberry Pi .img files
Ruby
22
star
14

leaflet-multispectral

Multispectral color manipulation and processing (NDVI etc) for Leaflet image overlays with pure JavaScript in Image Sequencer
HTML
22
star
15

plotsbot

A bot for Public Lab
JavaScript
17
star
16

papercraft-spectrometer

An introductory papercraft spectrometry kit
13
star
17

sky-camera

Public Lab's Android Aerial Acquisition App
Java
12
star
18

spectrometer3

Public Lab's open source Desktop Spectrometry Kit
11
star
19

leaflet-blurred-location-display

A library to display points which have been "blurred" for privacy with leaflet-blurred-location
JavaScript
11
star
20

SmART-Form

A community science effort to measure formaldehyde in the home environment
Java
9
star
21

webjack-firmata

A wrapper for WebJack to use as transport layer for firmata.js, for firmata access to an Arduino from a web browser.
JavaScript
9
star
22

mapmill

A Hot-or-Not styled crowdsourcing engine for sorting raw map imagery
HTML
8
star
23

colorimetry

A web-based colorimetry toolkit, using Image Sequencer
JavaScript
8
star
24

infragram-ps

Contents of the SD card to be used on the Infragram Point and Shoot - an open hardware multispectral camera developed by Public Lab: http://infragram.org
7
star
25

image-sequencer-app

An Image Processing server based on image-sequencer
JavaScript
7
star
26

community-microscope

Community Microscope design files
G-code
6
star
27

leaflet-tile-filter

Multispectral color manipulation and processing (NDVI etc) for Leaflet tile layers with pure JavaScript in Image Sequencer
HTML
6
star
28

mapknitter-exporter

The GDAL/ImageMagick-based exporter system from MapKnitter
Ruby
5
star
29

blurred-location

A JavaScript library to help manage variable location privacy through a "blurred location" model
JavaScript
4
star
30

mapknitter-exporter-sinatra

A minimal Sinatra app to run MapKnitter exports in the cloud
Ruby
3
star
31

plots-leaflet-viewer

A leaflet-based TMS viewer which accepts a TMS URL as a GET parameter. Good for fullscreen map viewing and embedding.
HTML
2
star
32

wherewebreathe

JavaScript
2
star
33

spectralchallenge

a website for Public Lab's Spectral Challenge, at http://spectralchallenge.org
JavaScript
1
star
34

lego-spectrometer

Design files for the Public Lab Lego Spectrometer
1
star
35

thermal-flashlight

Files for the Thermal Flashlight project
C++
1
star
36

multibot

A general-purpose Node.js bot library for writing interactive bot behaviors on various platforms
JavaScript
1
star
37

unearthing-pvd

A platform for historical data-driven analyses of industrial land use, story-mapping, and community organizing. (dataset)
1
star
38

publiclab-kits

Tracker for manufacturing issues for Public Lab kits
1
star
39

spectral-workbench-mobile

PhoneGap-based mobile app version of SpectralWorkbench.org, focus on iOS
JavaScript
1
star
40

SWBSearchModule

The spectral search module for the Spectral WorkBench
Python
1
star
41

leaflet-archive

A Leaflet map that displays geocoded images from Archive.org
JavaScript
1
star