Platform Contributor Guide
[Legacy v3] Platform
[Legacy v3] Platform
  • 👋[Legacy v3] Welcome | README
  • Contributing | Getting Involved
    • Specific tasks needed for COVID19-support
    • Add code to Ushahidi
    • Encouraging contribution from non-developers
  • Frequently Asked Questions
  • Join the Ushahidi community
  • Contributors ✨
  • 🛣️ The Ushahidi Platform Roadmap
    • V2-V3+ Migration tool
  • Privacy and security best practices
    • Security as a user
    • Security for deployment admins
    • Security for deployment hosts
  • Development & Code
    • Development: Overview
    • How to get the source code
    • Setup Guides
      • Installing for production environments
      • Development environment with XAMPP
      • Development environment setup with Vagrant
      • [Client] Setting up the Platform Client for development
        • Migration from AngularJS
      • Setting up the Pattern Library for development
      • [API & Client] Bundled release install
    • Add code to Ushahidi
    • Development process
    • Coding Standards
    • Track and submit issues in Github
    • Upgrading Ushahidi
      • Upgrading to latest release
      • Upgrading from V3.x.x to V4.x.x
    • ⚙️ Installation Helper‌
  • Tech Stack
    • API Documentation
    • Third party app development
      • Web hooks
    • Database | Tables overview
    • Database | Database Schema Diagram
    • Database | Table details
    • 📐Architecture
    • Use case internals
  • QA & Testing
    • The QA process
    • How to run QA tests
    • Defect Management
    • How to write QA test scripts
    • Hotfixes
  • Front-end development
    • Changing UI styles: introduction to the pattern library
      • File-structure
      • Installing new packages
      • How to Apply to the Platform
      • Using the changed styles in platform-client
      • Syntax and Formatting
      • Grid, Breakpoints, & Media Queries
      • Variables
      • Mixins
      • Helpers
      • Icons
      • Create a New Component from Scratch
      • Read Direction
  • Design
    • 🎨Design: overview
    • 'Best practice' design
    • Ushahidi Platform 'Sticker Sheet'
    • User testing process
    • User testing script examples
    • Synthesising user testing results examples
      • Synthesis example 1
      • Synthesis example 2
      • Synthesis example 3
      • Synthesis recommendations example 1
      • Synthesis recommendations example 2
    • Open Source Design
  • Documentation
    • Documentation
    • Contributing docs via GitHub
  • Translation
    • Localization and Translation
  • The Ushahidi Platform Facebook bot
    • The Facebook bot
      • Installing the bot
      • The bot script
  • Hackathon and events
    • Installathon, May 2019
      • Welcome to the hackathon!
    • Write/Speak/Code 2019
    • Open Design: Bangalore
    • Open Design: Taipei
    • 📑Google season of docs
    • 💻Google Summer of Code
      • GSoC 2024
  • Enhancement Proposals
    • Exchange Format
    • Importing data from previous versions
Powered by GitBook
On this page
  • Video-tutorials
  • Installing the API
  • Prerequisites
  • Getting the API Code
  • Getting the web server running
  • Setting up the deployment's database
  • Installing the client
  • Issues and solutions
  1. Development & Code
  2. Setup Guides

Development environment setup with Vagrant

PreviousDevelopment environment with XAMPPNext[Client] Setting up the Platform Client for development

Video-tutorials

The setup in this guide is demonstrated in below video as well if you want to watch and follow the guide at the same time!

Installing the API

This guide relies heavily on Vagrant and assumes some previous knowledge of how to use and/or troubleshoot vagrant.

Problems with the setup? Make sure to check our section Issues and solutionsbelow!

Prerequisites

Please make sure you install everything in this list before you proceed with the platform setup.

  • PHP >=7.0 <7.2 - if you are using Platform V4.0.0

  • PHP >=7.1 <7.4 - if you are using Platform V4.1.0 or later

  • PHP >=7.2 <7.4 - if you are using Platform V4.4.0 or later

Additional requisites setup

Getting the API Code

Clone the repository (this will create a directory named platform)

git clone https://github.com/ushahidi/platform.git

Go into the platform directory

cd platform

Switch to the develop branch

git checkout develop

Getting the web server running

Once you have the code, the next step is to prepare a web server. For this part, we will use vagrant, with the Vagrant and Homestead.yml files that ship with Ushahidi.

First up we need to install the PHP dependencies. In the platform directory, run:

composer install --ignore-platform-reqs

Without using --ignore-platform-reqs you might run into an error like "The requested PHP extension ... is missing from your system". That's ok. You don't need all the PHP extensions on your host machine, since the vagrant setup already has them.

If you get a warning like "In MemcachedConnector.php line 69: Class 'Memcached' not found" at this point you can safely ignore it, we will come back to it later.

Bring up the vagrant server. Since this is the first time you run it, it will also provision the machine from scratch:

vagrant up

Our vagrant box is built on top of Laravel's Homestead, a pre-packaged Vagrant box that provides a pre-built development environment. Homestead includes the Nginx web server, PHP 7.1, MySQL, Postgres, Redis, Memcached, Node, and all of the other goodies you might need.

If you see an error like "Vagrant was unable to mount VirtualBox shared folders..."

 -
      map: "./"
      to: /vagrant
      type: "nfs"
  -
      map: "./"
      to: /home/vagrant/Code/platform-api
      type: "nfs"

Now that you (hopefully) have a working vagrant machine, you will have to ssh into it to finish installing the dependencies.

vagrant ssh

Change to the project directory. This is shared by Vagrant / VirtualBox between your virtual server and your machine for easy updating during development:

cd ~/Code/platform-api

Set required php version. For current version of Ushahidi this should be 7.3:

sudo update-alternatives --set php /usr/bin/php7.3
sudo systemctl stop php7.1-fpm.service
sudo systemctl disable php7.1-fpm.service
sudo systemctl enable php7.3-fpm.service
sudo systemctl start php7.3-fpm.service
sudo sed --in-place=.php7.1.bak "s/php7.1-fpm/php7.3-fpm/g" /etc/nginx/sites-available/*
sudo systemctl restart nginx.service
composer install

Important: If you didn't setup vagrant-hostupdater, or if it failed for any reason, you will need to add the following lines to /etc/hosts in your host machine.

192.168.33.110  platform-api
192.168.33.110  api.ushahidi.test

Don't be surprised: This IP address is automatically set up by Vagrant, see Homestead.yaml and used in a couple of places.

At this point you should have a running web server, but your deployment isn't set up yet. We still need to configure the database and run the migrations.

Setting up the deployment's database

  • Copy the configuration file .env.example to make sure the platform can connect to the database.

cp .env.example .env
  • Run the migrations. This is required to be able to use your deployment, since it includes basic data such as an initial "admin" user, roles, the database schema itself, etc.

composer migrate

Example JSON

{"now":"2018-11-06T19:18:23+00:00","version":"3","user":{"id":null,"email":null,"realname":null}}

Installing the client

Issues and solutions

Vagrant says "The IP address configured for the host-only network is not within the allowed ranges. Please update the address used to be within the allowed ranges and run the command again."

The solution seems to involve creating a /etc/vbox/networks.conf file with the following content:

* 192.168.33.0/24

If you want to learn more about vagrant, please refer to their docs here

Recommended: - this is useful to avoid having to update /etc/hosts by hand (Note: The plugin homepage says that this plugin is not maintained anymore. For now, it still seems to work fine, so you can ignore this warning.)

- Note: Windows users may be required to Enable VT-X (Intel Virtualization Technology) in the computer's bios settings, disable Hyper-V on program and features page in the control panel, and install the VirtualBox Extension Pack (installation instructions here.)

VirtualBox > 6.1.28 . As described here , you may need to add the virtual internal network to a configuration file in VirtualBox. Our Vagrant/Homestead setup is coded to use the 192.168.33.0/24 network. Please create the file /etc/vbox/networks.conf (or equivalent in Windows (?)) and make sure it has the following line in it: * 192.168.33.0/24\

If you haven't used git before or need help with git specific issues, make sure to check out their docs here

vagrant ssh (to ssh into the machine. If you get an error like 'the path to your private key does not exist' when doing vagrant ssh, you need to generate a key, or if you already have one, double-check the path in the file "Homestead.yaml" . One good guide on generating keys is found here: )

Go to in your browser to check the API is up and running. You should see some JSON with an API version, endpoints and user info.

Congratulations! You have set up the API. You may want now to for a full experience.

According to information found here , a change in VirtualBox's handling of networking can render Homestead installations invalid.

https://learn.hashicorp.com/vagrant
Vagrant
Vagrant host-updater plugin
VirtualBox
Composer
https://github.com/laravel/homestead/issues/1717
https://git-scm.com/doc
https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#generating-a-new-ssh-key
http://192.168.33.110
build and install the web client
https://lifesaver.codes/answer/virtualbox-6-1-28-no-longer-auto-assigns-hostonly-ips-1717
Setting up Platform backend, recorded in Mac OS