“EZBus” Documentation

“Admin Web Panel ”

Table of Contents

  1. What is EZBus?
  2. Prerequisites
  3. Firebase
  4. Payment Configuration
  5. Installation
  6. Activation & Configuration
  7. FAQ

A) What is EZBus? - top

EZBus is a transportation management system that is committed to enabling cities, individuals, and businesses to move anywhere. EzBus is tech-driven, fancy, and convenient.

EzBus consists of two Flutter apps for customers and drivers along with an Admin panel with a Laravel API system as a back-end and a Vue.js front-end system as a web interface.

Here we present the Admin web panel sub system

B) Prerequisites - top

To ensure that the admin panel fully operational, some prerequisites need to be installed. In the following, I will list the required prerequisites and show how you can install them on a Ubuntu machine

  1. Apache web server
    2. 	sudo apt update	
	sudo apt install apache2
  2. Mysql server database engine
    3. 	sudo apt install mysql-server
  3. Set the password of the root for the mysql server database engine
    4. 		#open a mysql terminal
		sudo mysql -u root #press enter when prompted for a password
		#write the following in mysql terminal
		ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'YOUR PASSWORD HERE';
		#exit the mysql terminal
		exit;
  4. Php 8.1
    5. 	sudo apt install software-properties-common
	sudo add-apt-repository ppa:ondrej/php
	sudo apt update
	sudo apt install php8.1
  5. Php 8.1 extensions
    6. sudo apt install php8.1-common php8.1-mysql php8.1-xml php8.1-xmlrpc php8.1-curl php8.1-gd php8.1-imagick php8.1-cli php8.1-dev php8.1-imap php8.1-mbstring php8.1-opcache php8.1-soap php8.1-zip php8.1-intl -y

    sudo apt-get install php-curl php-xml php-mbstring -y
  6. Enable mod_rewrite for Apache
    7. 	sudo a2enmod rewrite
	sudo systemctl restart apache2
  7. Configure apache for php8.1
    8. 	sudo apt-get install libapache2-mod-php8.1
	sudo a2enmod php8.1
	sudo systemctl restart apache2
  8. Composer
    9. 	sudo apt-get update
	php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
	sudo apt-get install curl php-cli php-mbstring git unzip
	sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
  9. Please make sure that you have accounts for
    • Google maps API
      Please make sure that you enable the following APIs
      • Geocoding API
      • Maps JavaScript API
      • Places API
      • Directions API
      • Routes API
      • Maps SDK for Android
      • Maps SDK for iOS
    • Firebase account
    • Braintree SDK. You can test with a sandbox account OR integrate a live account.

C) Firebase - top

  1. Go to your account in https://console.firebase.google.com and create a new project. Name it "EZBus".
    2. Firebase create project
  2. Create a new web app
    3. Firebase add web app
  3. Enter the new web app nickname, then click "Register app"
    4. Firebase add web app
  4. Copy the firebase config object.

    Please record them as we will use them later.

    5. Firebase add web app
  5. Go to settings of the web app, then open "Service accounts" tab. Click on "Generate new private key". Keep the downloaded file with the same name. The downloaded file name is in the form "ezbus-demo-firebase-adminsdk-jm2jc-c057abcdef.json".

    Please record the file name as we will use it later.

    6. Firebase cloud messaging Firebase cloud messaging
  6. Go to "Authentication" section in the left pane, then click on "Get started"
    7. Firebase cloud messaging
  7. Select Email provider
    8. Firebase cloud messaging
  8. Enable Email/Password
    9. Firebase cloud messaging
  9. Add the super admin account. Go to "Users" section tab, then click on "Add user"
    10. Firebase cloud messaging
  10. Enter the email of the super admin and a password, then click on "Add user"
    11. Firebase cloud messaging
  11. Get the UID of the super admin. Go to "Users" section tab, then copy the UID.

    Please record email, password, and UID as we will use them later.

    12. Firebase cloud messaging

D) Payment Configuration - top

The system has four types of payments. They are as follows:
  1. Braintree
  2. RazorPay
  3. FlutterWave
  4. PayTabs
  5. No payment (to allow free rides). If you need this option, skip configuring any payment gateway in the following.
In the following, we show how to configure each of them

1) Braintree

You need to get "Public Key", "Private Key", and "Merchant ID" from Braintree dashboard.

Please record them as we will use them later.

  1. Go to your account in https://www.braintreegateway.com or https://sandbox.braintreegateway.com
  2. Go to "Settings" from the upper right menu, then click on "API"
    3. Braintree
  3. Click on "Generate New API Key"
    4. Braintree
  4. Click on view for the generated key to get the "Public Key", "Private Key", and "Merchant ID".

    Please record them as we will use them later.

    5. Braintree

2) RazorPay

You need to get both "Key Id" and "Key Secret" from RazorPay dashboard.

Please record them as we will use them later.

  1. Open your "RazorPay" account dashboard
  2. Choose "Settings" section in the left pane, then click on "API Keys" RazorPay Get Keys
  3. Get both "Key Id" and "Key Secret" and save them.

3) FlutterWave

You need to get both "Public Key" and "Secret Key" from FlutterWave dashboard.

Please record them as we will use them later.

  1. Open your "Flutterwave" account dashboard
  2. Choose "Settings" section in the left pane, then click on "API"
    3. Flutterwave Get Keys
  3. Get both "Public Key" and "Secret Key" and save them.

4) PayTabs

You need to get both "Profile ID", "Server Key", "Currency", and "Region" from PayTabs dashboard.

Please record them as we will use them later.

  1. Open your "Paytabs" account dashboard
  2. Choose "Developers" section in the left pane, then click on "Key management"
  3. Click on "+" to generate new "API Key". Select Standard SDK.
  4. Get the "Server Key" and save it
  5. Obtain your Profile Id and save it (the number before your name)
    6. Paytabs Get Keys
  6. Choose one of the following regions: 'ARE','EGY','SAU','OMN','JOR','GLOBAL'
  7. Record the currency you registered in with PayTabs account. It is one from the list ['AED','EGP','SAR','OMR','JOD','US'].

E) Installation - top

As we indicated, the admin panel composed of a Laravel API system as a back-end and a Vue.js front-end system as a web interface. We indicate the installation steps for each of them separately.

1) Laravel API system installation

I assume that the purchased admin web panel is located in the folder "ezbus" at "/home/ezbus". You can modify this path if you download the folder in a different path. Please follow the following steps for installation

  1. Go inside the folder
    2. 	cd /home/ezbus
  2. Ensure that php 8.1 is the current verison of your php by typing the command 
    3. 	sudo update-alternatives --config php
  3. Install dependencies
    4. 	composer install
  4. Make a link to storage folder in the public folder
    5. 	ln -s ../../storage/app/public public/backend/storage
  5. Put the downloaded file in step (C)-5 above in the "ezbus" folder
  6. Create the .env file from the provided example .env
    7. 	cp .env.example .env
  7. Edit the .env file and set the following
    8. 	APP_URL = your web site url, for example www.mydomain.com
	DB_USERNAME = root
	DB_PASSWORD = password of root user of mysql database 
	FIREBASE_CREDENTIALS=Write the downloaded name in step (C)-5 and pre-append it with ./ (for example, ./ezbus-demo-firebase-adminsdk-jm2jc-c057abcdef.json)

If you want to use Braintree, then set the following
	BRAINTREE_ENV=sandbox or live
	BRAINTREE_MERCHANT_ID= your Braintree merchant ID from step (D)-1
	BRAINTREE_PUBLIC_KEY= your Braintree public key from step (D)-1
	BRAINTREE_PRIVATE_KEY= your Braintree private key from step (D)-1

If you want to use RazorPay, then set the following
	RAZORPAY_KEY= your RazorPay key id from step (D)-2
	RAZORPAY_SECRET= your RazorPay key secret from step (D)-2

If you want to use FlutterWave, then set the following
	FLW_PUBLIC_KEY= your FlutterWave public key from step (D)-3
	FLW_SECRET_KEY= your FlutterWave secret key from step (D)-3

If you want to use PayTabs, then set the following
    paytabs_profile_id= your PayTabs profile id from step (D)-4
	paytabs_server_key= your PayTabs server key from step (D)-4
	paytabs_currency= your PayTabs currency from step (D)-4
	paytabs_region= your PayTabs region from step (D)-4

If you do not want to use any payment gateway, then do not set any of the above payment gateway keys.
  8. Edit the .env file to set The Google Maps API key. Set the following
    9. 	GOOGLE_MAPS_API_KEY= Your Google Maps API key
  9. Generate a new key
    10. 	php artisan key:generate
  10. Give full permission to storage and bootstrap/cache folders
    11. 	chmod -R 777 storage bootstrap/cache
  11. Change owner of the public and avatar folders
    12. 	sudo chown -R $USER:$USER public
	sudo chown -R $USER:$USER storage/app/public/avatars/
  12. Configure an Apache virtual host for EZBus
    • Create a configuration file for the virtual host for EZBus
      • 	sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/EZBus.conf
    • Edit the configuration file "/etc/apache2/sites-available/EZBus.conf" and replace its contents with the following
      • 	<VirtualHost *:80>
		ServerName EZBus
		DocumentRoot /home/ezbus/public
		<Directory /home/ezbus/public>
			Options Indexes FollowSymLinks MultiViews
			AllowOverride All
			Require all granted
		</Directory>
		ErrorLog ${APACHE_LOG_DIR}/error.log
		CustomLog ${APACHE_LOG_DIR}/access.log combined
	</VirtualHost>
    • Enable the configuration file "EZBus.conf"
      • 	sudo a2dissite 000-default.conf
	sudo a2ensite EZBus.conf
	sudo systemctl restart apache2
  13. Open mysql terminal and create a database with name "ezbus_db"
    14. 	mysql -u root -p #enter the root password when prompted
	create database ezbus_db; #then exit the mysql terminal
  14. Make sure that you give full permission to storage and bootstrap/cache folders.

    Database migration will fail if you did not do this

    15. 	chmod -R 777 storage bootstrap/cache
  15. Make sure that you have changed the owner of the public and avatar folders.

    Database migration will fail if you did not do this

    16. 	sudo chown -R $USER:$USER public
	sudo chown -R $USER:$USER storage/app/public/avatars/
  16. Update the super admin credentials in the users seeder file in "database/seeders/UsersTableSeeder.php". Write the email, password, and UID of the super admin, that was obtained in step (C)-11, in this seeder file.

    Database migration will fail if you did not do this

    17. 	$user = User::create([
		'name' => 'SuperAdmin',
		'email' => 'admin@yourdomain.com',
		'password' => Hash::make('admin123456'),
		'role' => 0,
		'status_id' => 1,
		'uid' => "l8nIta8bjOVLifjV0uktyUu5iF53"
	]);
  17. Migrate the database
    18. 	php artisan migrate:fresh --seed
  18. Install redis server
    19. 	sudo apt-get install redis-server
	sudo systemctl enable redis-server.service
	sudo apt-get install php-redis
  19. Install npm
    20. 	sudo apt-get install nodejs
	sudo apt-get install npm
  20. Install Laravel echo server
    21. 	sudo npm install -g laravel-echo-server
	sudo laravel-echo-server init #I recommend to press enter to choose the default answer for every question (except if you have https instead of http)
	sudo nohup laravel-echo-server start & #start the laravel-echo-server in background and make it permanently alive
  21. Update permissions of privacy and terms pages.
    22. 	chmod 777 public/privacy.html 
	chmod 777 public/privacy_local.html 
	chmod 777 public/terms.html 
	chmod 777 public/terms_local.html
    Now, the Laravel API system is ready to be used. You can verify that by opening the url "your domain and append it with /backend (for example www.mydomain.com/backend) in a browser. You should see the following image Laravel API

2) Vue.Js Front End

In the following, we show how to install the Vue.js front end that will be used as a web interface for the admin panel

  1. Go inside the folder
    2. 	cd /home/ezbus
  2. Go inside the folder "frontend"
    3. 	cd front-end
  3. Create the .env.production file from the provided example .env.production.example
    4. 	cp .env.production.example .env.production

  4. Edit the file ".env.production" and set the following 

    	# API Config
	VUE_APP_API_URL=your web site url, for example www.mydomain.com and append it with /backend. For example, www.mydomain.com/backend
	
	
	# Firebase Config
	VUE_APP_API_KEY=AIzaSy..... (from step (C)-4)
	VUE_APP_AUTH_DOMAIN=ezbus.... (from step (C)-4)
	VUE_APP_PROJECT_ID=ezbus.... (from step (C)-4)
	VUE_APP_STORAGE_BUCKET=ezbus.... (from step (C)-4)
	VUE_APP_MESSAGING_SENDER_ID=544..... (from step (C)-4)
	VUE_APP_APP_ID=1:544.......:web:01b......... (from step (C)-4)
	
	# Google Maps Config
	VUE_APP_GOOGLE_MAPS_API_KEY=Your Google Maps API key.

	# System Name
	VUE_APP_SYSTEM_NAME= Your System Name (instead of EZ-Bus)

  5. Edit the file "front-end/public/index.html" and set the title to your system name (instead of EZ-Bus) 

    	<title>Your System Name</title>
  6. Install dependencies
    7. 	npm install
  7. Build the project
    8. 	npm run build
  8. Copy the generated files to the public folder of the Laravel API system
    9. 	cp -r dist/* ../public/
    Now, the Vue.js front end is ready to be used. You can verify that by opening the url "your domain (for example www.mydomain.com) in a browser. You should see the login page of the admin panel

F) Activation & Configuration - top

Once you installed EZBus as indicated above, login with the super admin account credentials to set the different keys used by EZBus

  1. Go to this link and enter your purchase key. Please enter your complete website URL, for example https://www.mydomain.com and append it with /backend. For example,https:// www.mydomain.com/backend You can get the purchase key from your CodeCanyon download section. More information is here. domain (or localhost). You will get two secure keys. One for your web site url and the other for localhost. Copy your secure keys and keep it in a safe place as you will not be able to generate them again.

  2. Open your web site and login with the super admin credentials.

  3. You will see "Activate your account" button. Click on it and you will be redirected to the activation page

  4. Enter your secure key and click "Activate"

  5. Add scheduling entry for cron. This step is very important to handle all automated tasks
    • First open your terminal and run
      • crontab -e
    • Then add the following line
      • * * * * * cd /home/ezbus && php artisan schedule:run >> /dev/null 2>&1
  6. Adjust the settings of the admin panel. Specifically, you need to set the following
    • Currency
    • Rate per km: this is the rate that will be used to calculate the trip price)
    • Commission percentage: this is the percentage that will be deducted from the trip price and will be added to the admin account
    • No. of days in future to publish trips: this is the number of days that will be used to publish trips in the apps. No trips will be shown in the apps if the trip date is more than this number
    • Max distance to stop: this is the maximum distance that will be used to calculate the distance between the driver and the stop. If the distance is more than this number, the driver will not be able to start the trip
    • Distance to stop to mark arrived by a driver: this is the distance that will be used to calculate the distance between the driver and the stop. If the distance is less than this number, the driver will be able to mark arrived
    • Ads settings: this is the settings that will be used to allow ads in the customer and driver apps. You can allow ads in the customer app, driver app, or both
      1. Allow ads in customer app
      2. Allow ads in driver app
    Settings

G) FAQ - top

  1. I want to change the time zone so the timing in the backend matches the apps

    2. Change the timezone in config/app.php. Select one from here

  2. I do not see any trips in the apps even I created some trips in the admin panel

    3. Make sure that you write the crontab command correctly. Please see step (F)-5 above

  3. When I change some details in a trip, it is not reflected in the apps

    4. Note that the apps are working on a copied version from the trips table. This means that any change in the trips table will not be reflected immediately in the apps, but will reflected in future trips.

  4. Laravel-echo-server not working

    5. Configure your firewall and make sure that you allow traffic through the port 6001

  5. How do I know that the laravel-echo-server is working correctly?

    6. Go to the url of the admin panel and append it with 6001, i.e., open http://YOUR_WEBSERVER_URL:6001 and check if it gives OK

  6. The home page of the admin panel gives a blank white page
    • Make sure that you give full permission to storage and bootstrap/cache folders by
      • 	chmod -R 777 storage bootstrap/cache
    • Make sure that you edit the .env file correctly
    • Make sure that you edit the .env.production file correctly
  7. Why I need to set the Google Maps API key in both the .env file and the .env.production file?

    8. The .env file is used by the Laravel API system, while the .env.production file is used by the Vue.js front end. Both systems require the Google Maps API key. The Laravel API system uses it for server-side calls with the Routes API, which cannot be accessed from the client side. Meanwhile, the Vue.js front end uses it for client-side calls with other Google Maps APIs. Therefore, the API key must be configured in both systems.

  8. How I can secure my Google Maps API key?

    9. It is recommended to use two different API keys, one for the server-side in the .env file and the other for the client-side in the .env.production file. This way, you can restrict the usage of the API key to the specific system. For the server-side API key, you can restrict the usage to the server's IP address, while for the client-side API key, you can restrict the usage to your website domain. This will help prevent unauthorized usage of your API key. You can find more information on securing your API key in the Google Maps Platform documentation here.

Once again, thank you so much for using EZBus. As I said at the beginning, I'd be glad to help you if you have any questions. I'll do my best to assist. If you have a more general question relating to the items on CodeCanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.

CreativeAppsDev Team

Go To Table of Contents