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 setup in this guide is demonstrated in below videos as well if you want to watch and follow the guide at the same time!
Pre-requisite: Install the platform API by following one of the API setup guides
In a terminal window or command prompt, clone the repository.
git clone https://github.com/ushahidi/platform-client.git
Go into the platform directory
Ensure you are in the develop branch, with the latest, bleeding edge, code.
git checkout develop
Install the platform-client dependencies.
There are a few quite important variables that are looked 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.
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.
.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!):
All the other variables are often not required to specify, as they have sensible defaults.
PORT variable specifies at which port the local development server should listen. The default for this variable is
TX_PASSWORD are variables for configuring the credentials to the Transifex 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 on languages other than English.
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_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
gulp command, although a bit funny-sounding, is key for all development tasks on the platform client.
By default, this command is hidden within the
node_modules/.bin directory of your platform-client folder. This makes it a bit awkward to invoke, see these examples:
# Windows users would run:node_modules\.bin\gulp# Mac/Linux users: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:
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.
And then wait until you see this message in the screen:
webpack: Compiled successfully.
At that point the client should be available to the browser on the address http://localhost:3000 (unless you specified a
PORT on your
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:
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.