Branch: master
Find file Copy path
194 lines (148 sloc) 8.58 KB

Back to README

Script Setup

We have a script to automate the process of setting up your developmental environment. Right now, it supports Debian-based systems(Debian, Ubuntu etc.), Fedora and MacOS.

Warning: If you run this python script on Windows system, it will run a still in Development script, which is not tested fully and might not work properly.

Note: We have a batch file for Windows which is still a Work-in-progress. If you are windows user, We would love your contribution in testing and developing the script for Windows platform. You can find the batch file under setup directory.


There are some basic requirements for the script to work:

  • git(to clone the repository)
  • python 3
  • ruby-2.5.0
  • apt(debian)/homebrew(MacOS)
  • node v10 or lower.


  • Clone the repository
  • From the repository directory, run python3
    • The python file checks for your operating system and runs the corresponding system dependent script
  • The script will ask for your root password and MySQL passwords.
    • While installing MySQL, the MySQL installer might ask you to setup the root password
    • In case of MacOS systems, the MySQL root password will be blank if the installer doesn't ask you to setup one.
  • Wait for the installation to complete
  • If you face any errors, you can find the log for the script in setup directory by the name of log.txt

In case of any errors please post your error logs on: You can also contact us on slack for any further queries.


  • If you want to setup your own manual Database config(Advanced users)
    • First, create your manual config file, config/database.yml from the sample file provided, config/database.example.yml
    • Run the script
    • Run Migrations if needed.
  • If you face issues related to MySQL default password on your system
    • Please confirm your Password for MySQL
    • Delete config/Database.yml
    • Run the script again.
  • If you face the error that Sorry! Your operating is not supported by this script
    • You can try running the system dependent scripts from setup directory, according to your system
    • You can try manual installation

Manual Setup

TL;DR bare minimum version

If you know your way around Rails, here's the very short version. Some additional requirements are necessary to make all the tests pass and all the features work, but this should be enough to stand up the app quickly.

  • copy config/application.example.yml to config/application.yml
  • copy config/database.example.yml to config/database.yml
  • create a MySQL database, dashboard
  • install ruby 2.5.0 and nodejs
  • bundle install
  • rake db:migrate
  • install yarn
  • yarn for more javascript requirements
  • gulp to build assets
  • guard or rails s to start a server
  • localhost:3000 should load the home page

Project Setup

  • Pre-requisites for setup on OSX (Mac)

    • You will need to have xcode installed in order to have git on your machine. If you run git and it is not there, you will be prompted to install xcode.
    • To install rvm, you'll first need a gpg utility. You can install the GPG Suite from
    • Homebrew will install itself when you run the rvm install command, if you don't have it already.
  • Pre-requisites for setup on Windows:

  • Fork this repo, so that you can make changes and push them freely to GitHub.

  • Clone the new WikiEduDashboard repo and enter that directory.

  • On OSX/Debian, make sure you are in the "sudo" group.

  • Install Ruby 2.5.0 (RVM is documented here; rbenv also works fine.)

  • Install Node:

  • Install Gems:

    • $ gem install bundler
    • $ bundle install
    • If some gems fail to install, you may need to install some dependencies, such as: libmysqlclient-dev libpq-dev libqtwebkit-dev
  • Install Yarn

  • Install node modules via Yarn:

    • $ yarn
  • Install PhantomJS:

    • $ sudo yarn global add phantomjs-prebuilt
  • Install Pandoc

    • See the Pandoc installation guide for your environment's specifics.
    • Only Pandoc itself is needed; no additional related components (eg, LaTeX) are required.
  • Add config files:

    • Save application.example.yml and database.example.yml as application.yml and database.yml, respectively, in the config directory. The default settings in database.yml will suffice for a development environment.
  • Create mysql development and test database:

    • Install mariadb-server (or mysql-server)
      • Debian: sudo apt-get install -y mariadb-server
      • OSX: brew install mariadb
      • Windows: Install XAMPP
    • Start a mysql command line:
      • Debian: sudo mysql
      • OSX: brew services start mariadb then sudo mysql
      • Windows: C:\xampp\mysql\bin\mysql -u root
    • CREATE DATABASE dashboard_testing DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
    • exit
  • Install Redis:

    • Debian: sudo apt install redis-server
    • OSX: brew install redis
    • Windows: Download the Windows port by the Microsoft Open Tech Group
  • Install Gulp (if not already installed)

    • sudo yarn global add gulp


  1. Migrate the development and test databases
  • $ rake db:migrate
  • $ rake db:migrate RAILS_ENV=test

Set up OAuth integration (optional — skip unless you are working on WikiEdits features)

Populate example data

Running these tasks will take several minutes, and should populate your database with a few example events with editing activity.

  1. Create courses with users
  1. Import revision and upload data
  • $ rake batch:update_constantly
  • $ rake batch:update_daily


  1. Start Redis (if not already running as daemon)

    • Redis is used by Sidekiq. Some features — especially related to making edits on Wikipedia — will not work when Redis is down. On a Linux-based system, it will probably be running as a daemon automatically after installation. On OSX, you may need to start it manually.

      $ redis-server

      OR, if you used homebrew to install redis:

      $ redis-server /usr/local/etc/redis.conf

  2. Start the server

    • OSX/Debian: Use guard. This tool starts the rails development server (on localhost:3000). It also watches the files, and will automatically restart the server when rails files are changed, and it will automatically run corresponding test files when applicable.

      $ guard

    • Windows:

      $ rails s

  3. Start Gulp to compile assets

    • The default gulp command will build the project's javascripts and stylesheets (in lieu of the rails asset pipeline), and watch the assets directory, recompiling after changes to javascript, jsx and stylesheet files. Using gulp build instead will generate the minified production version of assets.

      $ gulp

  4. The frontend is now visible at http://localhost:3000/

  5. Sign in and visit http://localhost:3000/campaigns to create a campaign.

  6. To set up test users and data, see User Roles


The living style guide illustrates many of the design building blocks of the dashboard, which you can use for creating new features: http://localhost:3000/styleguide


The Dashboard includes several rake tasks intended to keep the database synced with Wikipedia:

  • Initialize: rake batch:initialize (Only to be run manually, initializes the database)
  • Constant update: rake batch:update_constantly (Runs every 15 minutes by default)
  • Daily update: rake batch:update_daily (Runs once a day by default)