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
  • What is the platform client?
  • Installation steps
  • Getting the platform-client code
  • Installing dependencies
  • Configuring the client build
  • Required build configuration variables
  • Advanced: other configuration variables
  • Running a local development server
  • Making `gulp` command available
  • Appendix: Building for publication
  1. Development & Code
  2. Setup Guides

[Client] Setting up the Platform Client for development

PreviousDevelopment environment setup with VagrantNextMigration from AngularJS

What is the platform client?

The web client is the component that end-users interact with when opening the Platform website with a web browser. The client interacts with the API in order to perform operations on the system (i.e. submit posts, query posts).

The Platform Client is currently using Angular JS 1.5.6 but since March 2021, we have started an incremental migration to another framework (yet to be decided which). We are using a micro frontend architecture and the code will be split up into different micro frontends, based on functionality. More information about the migration project can be found on the page .

Installation steps

Pre-requisite: Install the platform API by following one of the API setup guides

Pre-requisite: Install Node V10.x or higher (you might want to use NVM for this) before continuing.

Getting the platform-client code

  • In a terminal window or command prompt, clone the repository.

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

Mind your directories. The command above will create a directory named platform-client in the current active directory of your terminal/command prompt. Make sure you know which directory you are setting before running the command.

  • Go into the platform directory

cd platform-client
  • Ensure you are in the develop branch, with the latest code.

git checkout develop

Alternatively, you may run the command

git checkout master

for working on the masterbranch, with more stable code.

Installing dependencies

  • Install the platform-client dependencies.

npm run install:all

Configuring the client build

There are a few quite important variables that are looked at at the point when the client code is built into a browser web app. These variables are picked up from a file named .env , located in the platform-client folder that you have recently cloned from github.

  • Create a file named .env in your platform-client folder. This .env file is required and it doesn't exist by default. Therefore, you must create it. In the following sections, we'll let you know about the contents that you should put in that file.

In Windows environments, you may find yourself struggling to create this file with the right name. This may be because your text editor insists on appending ".txt" or because it is confused by the leading dot.

In that case, an easy way to create the file is by running the following command in the command prompt, when inside your platform-client folder:

type nul > .env

This will create an empty file, but with the right name. File Explorer may present this file as a file with empty name and of type "ENV file".

Mac/Linux users may use the touch .env command to the same end.

Required build configuration variables

There is only one required variable that must be defined in your .env file, and its name is BACKEND_URL. Its purpose is to configure the client with the URL to use, in order to send HTTP network requests to the Platform API. If this variable is wrong, nothing works. This variable usually takes different values for different users.

As such, the minimal working .env file consists of just this variable.

  • In your .env file write the BACKEND_URL variable, corresponding to your Platform API URL address. This is an example, showing the format used, (don't just copy & paste it to your file!):

.env
BACKEND_URL=http://dont.copy.this.name.com

If you have used one of our guides for setting up the API locally, check back the relevant section in that guide. Here are some direct links that should take you back there.

  • Vagrant setup, click TODO

Take a minute here to make sure you have entered the proper URL and the API is working.

{"now":"2019-02-04T10:52:25+00:00","version":"3","user":{"id":null,"email":null,"realname":null}}

If you get an error, please make sure that your API server is up (i.e. Apache and MySQL), and go back to your Platform API installation notes to make sure you had the correct URL.

Advanced: other configuration variables

All the other variables are often not required to specify, as they have sensible defaults.

You can safely skip this section if it's your first time setting up the client, and you just want to get it done. Getting into these details may be too much work for a first run.

  • The PORT variable specifies at which port the local development server should listen. The default for this variable is 3000.

  • APP_LANGUAGES is a list of language codes (in ISO-639-1 format) to download from Transifex. For example APP_LANGUAGES=sw,en,es would enable the client to appear in Swahili, English and Spanish.

  • OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET are variables used during the process of authentication of a user against the API. You can ignore these 99% of the times. Also, these are not particularly secret nor provide much security. They just have to exist, and they do by default. (If you must know, their values default to ushahidiui and 35e7f0bca957836d05ca0492211b0ac707671261 respectively)

Running a local development server

The local development server is a web server that makes the platform client available to your browser locally. Additionally, it will watch the platform-client folder for changes, and rebuild the application as needed.

  • Just run npm run serve:

npm run serve
  • And then wait until you see this message on the screen:

 All clients have loaded.
 Ushahidi client is ready to be viewed at http://192.168.68.104:3000

You are all set for developing, happy hacking!

Making `gulp` command available

In the legacy part of Platform Client, we use "gulp" to run the tasks and help to build the application. The gulp command, although a bit funny-sounding, is key for all development tasks on that part of the application.

By default, this command is hidden within the /legacy/node_modules/.bin directory of your platform-client folder. This makes it a bit awkward to invoke, see these examples:

# Windows users would run:
/legacy/node_modules\.bin\gulp
# Mac/Linux users:
/legacy/node_modules/.bin/gulp

That's too much typing.

To make it easy to call gulp when building and developing in the app, there are a couple approaches:

  • On any operating system, you can choose to install gulp globally. You would do it with his command:

npm install -g gulp
  • Alternatively, on Linux and Mac, you may edit the .bashrc file in your home directory, and append the following line:

.bashrc
export PATH=$HOME/bin:/usr/local/bin:node_modules/.bin:$PATH

Appendix: Building for publication

Sometimes you want to host your Platform instance so that other devices on the network or the internet can access it.

For the Platform client, this means placing the application files in a disk location configured as a static site, where your web server can find them and send them to those other devices.

In order to build the files for publication, run:

npm run install:all
npm run build

This will start the process of generating the static site. Once the files are generated, you will find the files in the server/www directory. Depending on your work flow, you may copy these files to your server, or you may choose to point your web server directly to this directory.

In the server directory you will also find an example nginx and an example apache2 file to help you with some of the web server configurations.

Please note that you will also need to publish the Platform API, so those other devices can actually make any use of the Platform.

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

XAMPP setup, click

From your .env file, copy the variable value (the part starting with ") and paste it in your browser's address bar, then hit enter. As a result you should see something similar to this:

TX_USERNAME and TX_PASSWORD are variables for configuring the credentials to the service, which stores multi-lingual versions of the Platform client text displayed on the screen. These are only required if you are going to develop in languages other than English.

At that point, the client should be available to the browser on the address (unless you specified aPORT on your.envfile).

Migration from AngularJS
Setup Guides
https://git-scm.com/doc
http://"\
Transifex
http://localhost:3000
here