“SchoolTripTrack” Documentation

“Admin Web Panel ”

Table of Contents

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

A) What is SchoolTripTrack? - top

SchoolTripTrack is a comprehensive multi-vendor school bus tracker system for managing the daily school bus operation that links the school, the guardians and the buses into one powerful system..

SchoolTripTrack consists of two Flutter apps for guardians 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;
    Note: the mysql_native_password plugin was removed in MySQL 8.4. If your MySQL server is 8.4 or newer, the command above fails with "Plugin 'mysql_native_password' is not loaded". Use the default plugin instead:
    		ALTER USER 'root'@'localhost' IDENTIFIED WITH caching_sha2_password BY 'YOUR PASSWORD HERE';
  4. Php 8.4
    5. The admin panel runs on Laravel 13, which requires PHP 8.3 or newer. These instructions install PHP 8.4. PHP 8.1 and 8.2 are no longer supported.
    	sudo apt install software-properties-common
	sudo add-apt-repository ppa:ondrej/php
	sudo apt update
	sudo apt install php8.4
  5. Php 8.4 extensions
    6. sudo apt install php8.4-common php8.4-mysql php8.4-xml php8.4-xmlrpc php8.4-curl php8.4-gd php8.4-imagick php8.4-cli php8.4-dev php8.4-imap php8.4-mbstring php8.4-opcache php8.4-soap php8.4-zip php8.4-intl php8.4-bcmath php8.4-redis -y
    Note: php8.4-bcmath and php8.4-redis are new in this list. php8.4-gd and php8.4-imagick are both required – without them student avatars and the QR codes on student cards fail when someone uses the system, not when you install it.
    Verify that every required extension is loaded. All eleven lines must print:
    php8.4 -m | grep -E '^(pdo_mysql|curl|gd|zip|intl|bcmath|redis|imagick|soap|mbstring|xml)$'
  6. Enable mod_rewrite for Apache
    7. 	sudo a2enmod rewrite
	sudo systemctl restart apache2
  7. Configure apache for php8.4
    8. 	sudo apt-get install libapache2-mod-php8.4
	sudo a2enmod php8.4
	sudo systemctl restart apache2
    Upgrading from an older version? Disable the previous PHP module first, otherwise Apache keeps serving the old one:
    	sudo a2dismod php8.1
	sudo a2enmod php8.4
	sudo systemctl restart apache2
	sudo update-alternatives --set php /usr/bin/php8.4
  8. Composer (version 2 is required)
    9. 	sudo apt-get update
	sudo apt-get install curl php8.4-cli php8.4-mbstring git unzip
	php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
	sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
    Confirm it reports version 2.x:
    	composer --version
  9. Please make sure that you have accounts for
    • A map provider account: Google Maps or Mapbox. You need at least one of them. The super admin selects which one is used in the admin panel (see step (F)-7).
    • 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
      The Maps SDKs for Android and iOS are needed by the mobile apps even if you use Mapbox, because the apps fall back to Google Maps when Mapbox is not available.
    • Mapbox account (optional, only if you want to use Mapbox instead of Google Maps). Billing must be enabled on the account, because address search uses Mapbox permanent geocoding (stop and school addresses are stored in your database). You need two tokens from the Mapbox account page:
      • A public token (starts with "pk.") for the admin web panel. Add a URL restriction to it with your website domain.
      • A secret token (starts with "sk.") for the server, with these scopes: tokens:write, styles:read, styles:tiles, fonts:read, datasets:read, vision:read, navigation:download. Never put the secret token in the admin panel or in the apps.
    • 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 "SchoolTripTrack".
    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 "SchoolTripTrack-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. PayStack
  5. Stripe
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) PayStack

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

Please record them as we will use them later.

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

5) Stripe

You need to get both "Publishable Key" and "Secret Key" from Stripe dashboard.

Please record them as we will use them later.

  1. Open your "Stripe" account dashboard
  2. On the home page, you will find to the right "For developers" section.
    3. Stripe Get Keys
  3. Get both "Publishable Key" and "Secret Key" and save them.

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 "SchoolTripTrack" at "/home/SchoolTripTrack". 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/SchoolTripTrack
  2. Ensure that php 8.4 is the current version 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 "SchoolTripTrack" 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, ./SchoolTripTrack-demo-firebase-adminsdk-jm2jc-c057abcdef.json)


	Note: Use Score based (v3) Recaptcha keys in the following

	RECAPTCHA_SITE_KEY= your Recaptcha site key
	RECAPTCHA_SECRET_KEY= your Recaptcha secret key

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 PayStack, then set the following
	PAYSTACK_PUBLIC_KEY= your PayStack public key from step (D)-4
	PAYSTACK_SECRET_KEY= your PayStack secret key from step (D)-4

If you want to use Stripe, then set the following
	STRIPE_KEY= your Stripe publishable key from step (D)-5
	STRIPE_SECRET= your Stripe secret key from step (D)-5
  8. Edit the .env file to set the server-side map keys. These keys are used only by the server and are never sent to browsers or apps. The browser map key is not set here, it is entered later in the admin panel (see step (F)-7). Set the keys of the provider you will use
    9. If you want to use Google Maps, then set the following
	GOOGLE_MAPS_SERVER_KEY= Your Google Maps server key (Routes API), restricted to your server IP address

If you want to use Mapbox, then set the following
	MAPBOX_SECRET_TOKEN= Your Mapbox secret token (sk.) from step (B)
	MAPBOX_USERNAME= Your Mapbox account username

Optional Mapbox settings (the defaults are fine for most installations)
	MAPBOX_TEMP_TOKEN_TTL=15
	MAPBOX_TEMP_TOKEN_SCOPES=styles:read,styles:tiles,fonts:read,datasets:read,vision:read

    The server uses the Mapbox secret token to calculate routes and to create short-lived Mapbox tokens (15 minutes by default) for the driver and guardian apps. The apps renew these tokens automatically, so there is nothing to configure in the apps for Mapbox. If you change the .env file after running "php artisan config:cache", run "php artisan config:clear" so the new values are used.

  9. Edit the .env file to set the email configuration. This is mandatory so the guardians can receive the student card ready for print. Set the following
    10. 	MAIL_USERNAME
	MAIL_PASSWORD
	MAIL_FROM_ADDRESS
    Please note that, if you are using gmail, you need to get the app password from your gmail account. You can get it from the following link https://myaccount.google.com/apppasswords. Do not use your gmail password here. Use the app password instead. You can find more details here.
  10. Generate a new key
    11. 	php artisan key:generate
  11. Give full permission to storage and bootstrap/cache folders
    12. 	chmod -R 777 storage bootstrap/cache
  12. Change owner of the public and avatar folders
    13. 	sudo chown -R $USER:$USER public
	sudo chown -R $USER:$USER storage/app/public/avatars/
  13. Configure an Apache virtual host for SchoolTripTrack
    • Create a configuration file for the virtual host for SchoolTripTrack
      • 	sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/SchoolTripTrack.conf
    • Edit the configuration file "/etc/apache2/sites-available/SchoolTripTrack.conf" and replace its contents with the following
      • 	<VirtualHost *:80>
		ServerName SchoolTripTrack
		DocumentRoot /home/SchoolTripTrack/public
		<Directory /home/SchoolTripTrack/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 "SchoolTripTrack.conf"
      • 	sudo a2dissite 000-default.conf
	sudo a2ensite SchoolTripTrack.conf
	sudo systemctl restart apache2
  14. Open mysql terminal and create a database with name "SchoolTripTrack_db"
    15. 	mysql -u root -p #enter the root password when prompted
	create database SchoolTripTrack_db; #then exit the mysql terminal
  15. Make sure that you give full permission to storage and bootstrap/cache folders.

    Database migration will fail if you did not do this

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

    Database migration will fail if you did not do this

    17. 	sudo chown -R $USER:$USER public
	sudo chown -R $USER:$USER storage/app/public/avatars/
  17. 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

    18. 	$user = User::create([
		'name' => 'SuperAdmin',
		'email' => 'admin@yourdomain.com',
		'password' => Hash::make('admin123456'),
		'role' => 0,
		'status_id' => 1,
		'uid' => "l8nIta8bjOVLifjV0uktyUu5iF53"
	]);
  18. Migrate the database
    19. 	php artisan migrate:fresh --seed
  19. Install redis server
    20. 	sudo apt-get install redis-server
	sudo systemctl enable redis-server.service
	sudo apt-get install php-redis
  20. Install npm
    21. 	sudo apt-get install nodejs
	sudo apt-get install npm
  21. Install Laravel echo server
    22. 	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
  22. Update permissions of privacy and terms pages.
    23. 	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/SchoolTripTrack
  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=SchoolTripTrack.... (from step (C)-4)
	VUE_APP_PROJECT_ID=SchoolTripTrack.... (from step (C)-4)
	VUE_APP_STORAGE_BUCKET=SchoolTripTrack.... (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)

	# System Name
	VUE_APP_SYSTEM_NAME= Your System Name (instead of SchoolTripTrack)

	# RECAPTCHA Config
	VUE_APP_RECAPTCHA_SITE_KEY= Your Recaptcha site key

    Note that no map key is set in this file. The Google Maps key or the Mapbox public token is entered by the super admin in the admin panel (see step (F)-7), so changing or rotating it does not need a rebuild.

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

    	<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 SchoolTripTrack as indicated above, login with the super admin account credentials to set the different keys used by SchoolTripTrack

  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/SchoolTripTrack && php artisan schedule:run >> /dev/null 2>&1
  6. Adjust the settings of the admin panel. Specifically, you need to set the following
    • Currency
    • 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
    • Allow Ads in the driver app: this is a switch to allow or disallow ads in the driver app
    • Allow Ads in the parent app: this is a switch to allow or disallow ads in the guardian app
    Settings
  7. Set the map settings. In the admin panel, open Settings and go to the "Map settings" section. Until a key is saved here, maps show "Maps are not configured" and routes cannot be calculated.
    • Google Maps browser API key: your Google Maps key restricted to your website domain (HTTP referrers), with the APIs from step (B) enabled.
    • Mapbox public token: your Mapbox public token (pk.) restricted to your website domain. A secret token (sk.) is rejected here.
    • The provider is selected automatically from the keys you fill: Google Maps when a Google key is entered (even if a Mapbox token is also entered), and Mapbox when only a Mapbox token is entered. The web panel and both mobile apps use the selected provider.
    • To save Mapbox as the provider, MAPBOX_SECRET_TOKEN and MAPBOX_USERNAME must be set in the .env file (step (E)-1), because the mobile apps get their Mapbox tokens from the server. Otherwise, saving is refused with an error message.

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 are there map keys in both the .env file and the admin panel?

    8. The keys in the .env file (GOOGLE_MAPS_SERVER_KEY, MAPBOX_SECRET_TOKEN) are server-side keys. The server uses them to calculate routes, and the Mapbox secret token is also used to create the tokens of the mobile apps. They are never sent to browsers or apps. The key in the admin panel (Settings > Map settings) is the browser key used by the web panel to show maps and search addresses.

  8. How I can secure my map keys?

    9. Use a different key for each place it is used, and restrict each one:

  9. Do I need to add a Mapbox token to the mobile apps?

    10. No. Mapbox cannot restrict a token to a mobile app, so the apps never get a permanent token. After login, the server gives the apps a short-lived Mapbox token (15 minutes by default, set with MAPBOX_TEMP_TOKEN_TTL) and the apps renew it automatically. If an account misuses it, suspend the account; its Mapbox access ends when the current token expires.

  10. The apps show Google Maps even though I selected Mapbox

    11. The apps fall back to Google Maps when the server cannot give them a Mapbox token. Make sure MAPBOX_SECRET_TOKEN and MAPBOX_USERNAME are set in the .env file, that the secret token has the scopes listed in step (B), and run "php artisan config:clear" if you cached the configuration. The reason is written in storage/logs/laravel.log (search for "Mapbox temporary token").

Once again, thank you so much for using SchoolTripTrack. 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