# Development environment setup with Vagrant ### 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! {% embed url="" %} Setting up Platform backend, recorded in Mac OS {% endembed %} ## Installing the API This guide relies heavily on Vagrant and assumes some previous knowledge of how to use and/or troubleshoot vagrant. {% hint style="info" %} If you want to learn more about vagrant, please refer to their docs here {% endhint %} {% hint style="info" %} Problems with the setup? Make sure to check our section [#issues-and-solutions](#issues-and-solutions "mention")below! {% endhint %} ## Prerequisites {% hint style="danger" %} Please make sure you install everything in this list before you proceed with the platform setup. {% endhint %} * [Vagrant](https://www.vagrantup.com/downloads.html) * Recommended: [Vagrant host-updater plugin](https://github.com/cogitatio/vagrant-hostsupdater) - 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.) * [VirtualBox](https://www.virtualbox.org/wiki/Downloads) - 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.) * [Composer](https://getcomposer.org/doc/00-intro.md#system-requirements) * 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 * **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`\\ ### Getting the API Code Clone the repository (this will create a directory named *platform)* ```bash git clone https://github.com/ushahidi/platform.git ``` Go into the platform directory ```bash cd platform ``` Switch to the *develop* branch ```bash git checkout develop ``` {% hint style="info" %} If you haven't used git before or need help with git specific issues, make sure to check out their docs here {% endhint %} ### 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: ```bash composer install --ignore-platform-reqs ``` {% hint style="info" %} 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. {% endhint %} {% hint style="warning" %} 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. {% endhint %} Bring up the vagrant server. Since this is the first time you run it, it will also provision the machine from scratch: ```bash 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. {% hint style="info" %} If you see an error like "Vagrant was unable to mount VirtualBox shared folders..." {% endhint %} * [ ] Verify that Vagrant and VirtualBox are up to date. * [ ] Verify that the VirtualBox Guest Additions were installed (and fix it if they weren't) * [ ] `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: ) * [ ] `lsmod | grep vboxguest` * [ ] If this command doesn't return anything, VB Guest additions are likely not installed correctly. A fix for this is to install the vbguest vagrant plugin. * [ ] if you are in the vagrant box, type `exit` and hit the return key to exit it * [ ] run `vagrant plugin install vagrant-vbguest` * [ ] run `vagrant up --provision` to continue * [ ] If that doesn't work, and you are in a linux or MacOS environment (this is not compatible with Windows!): * [ ] open the Homestead.yml file * [ ] Add `type: "nfs"` to the two directory mappings as shown below * [ ] run `vagrant up` ``` - map: "./" to: /vagrant type: "nfs" - map: "./" to: /home/vagrant/Code/platform-api type: "nfs" ``` {% hint style="success" %} Now that you (hopefully) have a working vagrant machine, you will have to ssh into it to finish installing the dependencies. {% endhint %} ```bash 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: ```bash cd ~/Code/platform-api ``` Set required php version. For current version of Ushahidi this should be 7.3: ```bash 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 ``` ```bash composer install ``` {% hint style="warning" %} **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. {% endhint %} ``` 192.168.33.110 platform-api 192.168.33.110 api.ushahidi.test ``` {% hint style="info" %} Don't be surprised: This IP address is automatically set up by Vagrant, see `Homestead.yaml` and used in a couple of places. {% endhint %} 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. ```bash 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. ```bash composer migrate ``` * 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. Example JSON ```json {"now":"2018-11-06T19:18:23+00:00","version":"3","user":{"id":null,"email":null,"realname":null}} ``` ### Installing the client Congratulations! You have set up the API. You may want now to [build and install the web client](/platform-developer-documentation/dev-legacy-v3/development-and-code/setup_alternatives/setting-up-the-platform-client.md) for a full experience. ## 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." According to information found here , a change in VirtualBox's handling of networking can render Homestead installations invalid. The solution seems to involve creating a `/etc/vbox/networks.conf` file with the following content: ``` * 192.168.33.0/24 ```
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ushahidi.com/platform-developer-documentation/dev-legacy-v3/development-and-code/setup_alternatives/vagrant-setup.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.