Get Started with PushMaze

PushMaze 1.0 Installation

Hi! Thanks for purchasing PushMaze. Follow this step-by-step PushMaze installation guide to get the software up and running on your servers. We recommend Digital Ocean VPS for hosting, and we’ll be using that for the example. You could very well use a provider like AWS or any other VPS provider that lets you install your software and an SSL certificate. SSL certificates are a requirement for running our software as SSL is required for the PushMaze software to be able to subscribe your end users to push notifications.

Prerequisites for installation:

• DigitalOcean or AWS account
• A Firebase account from google – sign up here: https://console.firebase.google.com/
• A local computer with a Terminal/Command prompt – (terminal on mac or linux). This tutorial is written assuming the person running these commands is using a terminal on linux or macOS. Windows users might need alternative tools to run commands on the local machine. Some options for the operations are listed below. You can download the software required for these here: https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html
  • creating a ssh key – puttygen
  • logging into a remote server using ssh – putty
  • copying files over to a remote server using scp – pscp

STEP 1 – Create Droplet:

After logging into your account, click on the “Create” button and then choose Droplets. This will take you to the Droplet creation page.

STEP 2 – Select Droplet Size:

Once in the Droplet creation page, choose Ubuntu 16.04 x64 as the distribution type and then choose the Standard droplet of size 2 GB with 1 vCPU that costs $10 a month.

STEP 3 – Droplet Configuration:

You can safely ignore the “Add a block storage” option as the VPS we chose comes with ample space to kick us off.

In the “Choose a datacenter region” option, you can pick a geo location that you think would be the closest to your users. If you’re not sure of a location, we recommend picking one of the NYC datacenter.

You can leave the “Select additional options” unticked unless you specifically know what you’re doing.

In the very important “Add your SSH Keys” section, we’ll be adding a SSH key to our VPS and make that the default way of logging into the machine. Let’s create a new SSH key if you don’t already have one. It’s a good practice to create a new SSH key for each new machine you want to login to.

STEP 3.1 – Creating a SSH Key:

Let’s create a SSH key that opening a new terminal window on your local machine (Terminal 1) and typing in the following command:

ssh-keygen

 

Once you type this command, It will prompt you to answer a few questions, and you can just hit “Enter” without typing anything to just go with the defaults offered for the path in which you’d like to create the public and private keys. You can hit “Enter” without typing anything for the passphrase as well. You key would now have been created at ~/.ssh/id_rsa.pub.

Now we’ll have to copy the public key and enter it in the Digital Ocean interface. To display the key, type in this command:

cat ~/.ssh/id_rsa.pub

 

The key will be a long sequence of characters that look like below. Once the key is displayed, select it and copy it using your mouse.

Once you’ve copied the public key, click on the “New SSH Key” and paste it in text box that says “SSH key content”. Enter a name, and then press “Add SSH Key”.

Your machine now has been associated with a private key pair.

Finally, press “Create”.

Once the droplet is created, you will get a confirmation on screen. A fully ready-to-go Droplet’s page looks like below:

STEP 4 – Login to the droplet:

Once the droplet has been created, you can login to it by opening your Terminal/Command prompt and typing in the following command. You can find your droplet’s IP address at the top of the Droplet screen.

ssh -i ~/.ssh/id_rsa root@<username>

 

STEP 5 – Create an alternate user:

Once you have logged into your server, we’ll have to create an alternate user account that you can use to access the server as using the root account is insecure. From the logged in terminal, type in the following command. Follow the prompts and add a secure password for the user and then store the password somewhere safe. You can choose the just press “ENTER” for all other questions as these details are optional.

adduser <username>

STEP 6 – Give the user some powers:

Now let’s add admin privileges to the newly created account by typing the following command:

gpasswd -a <username> sudo

Please use the username you selected in STEP 5 for this.

STEP 7 – Copy SSH keys over:

The newly created user will need share the keys we created in STEP 3 in order to login to the server. Let’s copy over the keys from the root user to the newly created user. Type the following commands while being logged into the server.

mkdir /home/<username>/.ssh
cp ~/.ssh/authorized_keys /home/<username>/.ssh/
chown -R <username>:<username> /home/username/.ssh

Replace <username> with the name you chose in STEP 5.

STEP 8 – Hardening the machine:

Let’s now increase the security of the machine by disabling the root user from logging in to the machine remotely. Let’s open up the ssh daemon config file by typing the following command:

nano /etc/ssh/sshd_config

Search for the line “PermitRootLogin yes” and change it to “PermitRootLogin no”. Also verify that the option “PasswordAuthentication” is set to “no”.

Once this is done, let’s restart the ssh service by typing in this command:

service ssh restart

Let’s verify that our newly created user is allowed and the root user is not allowed to login. Open a new terminal window and type:

ssh -i ~/.ssh/id_rsa.pub <username>@<droplet-ip-address>

If you’re able to login as the new user we just created, we can continue for the rest of the tutorial in the terminal where you’re logged in as the newly created user and close the terminal where you’re logged in as root.

CAUTION: Please make sure you don’t kill the command line in which you’re logged in using the root user before you’ve verified that the newly created user is able to login to the server without any issues. YOU MIGHT GET LOCKED OUT OF YOUR DROPLET IF YOU DON’T GET THIS RIGHT.

STEP 9 – Install LAMP Stack:

Now we’ll have to install the LAMP (Linux, Apache, MySQL and PHP) stack to run the PushMaze code on our servers. Let’s run the following commands in the terminal while being logged into the remote server. Since we are using a sudo command, these operations get executed with root privileges. It will ask you for your regular user’s password to verify your intentions. Once you’ve entered your password, apt will tell you which packages it plans to install and how much extra disk space they’ll take up. Press Y and hit Enter to continue, and the installation will proceed.

STEP 9.1 – Install Apache:

PushMaze uses apache2 as the web server to serve it’s serve side files. To install apache, run the following commands:

sudo apt-get update

sudo apt-get install apache2

Set Global ServerName to Suppress Syntax Warnings

Next, we will add a single line to the /etc/apache2/apache2.conf file to suppress a warning message. While harmless, if you do not set ServerName globally, you will receive the following warning when checking your Apache configuration for syntax errors:

sudo apache2ctl configtest

Output

AH00558: apache2: Could not reliably determine the server’s fully qualified domain name, using 127.0.1.1. Set the ‘ServerName’ directive globally to suppress this message
Syntax OK

Open up the main configuration file with your text edit:

sudo nano /etc/apache2/apache2.conf

Inside, at the bottom of the file, add a ServerName directive, pointing to your primary domain name. If you do not have a domain name associated with your server, you can use your server’s public IP address:

ServerName localhost

Save and close the file when you are finished.

Next, check for syntax errors by typing:

sudo apache2ctl configtest

Since we added the global ServerName directive, all you should see is:

Output

Syntax OK

Restart Apache to implement your changes:

sudo systemctl restart apache2

You can do a spot check right away to verify that everything went as planned by visiting your server’s public IP address in your web browser (see the note under the next heading to find out what your public IP address is if you do not have this information already):

http://your_server_IP_address

You will see the default Ubuntu 16.04 Apache web page, which is there for informational and testing purposes. It should look something like this:

STEP 9.2 – Install MySQL:

Now that we have apache server up and running, it is time to install MySQL. MySQL is the DBMS that PushMaze uses.

Run the command below:

sudo apt-get install mysql-server

Follow on screen prompts and press ‘Y’ where required. Once this is done, we’ll secure our MySQL installation. Run:

mysql_secure_installation

Follow the prompts here and set a MySQL root password and keep that safe. Always use a strong and random password. If you’re unable to come up with a random password, use passwordsgenerator.net to generate a random password and store it in a safe place.

For the rest of the questions, you should press Y and hit the Enter key at each prompt. This will remove some anonymous users and the test database, disable remote root logins, and load these new rules so that MySQL immediately respects the changes we have made.

STEP 9.3 – Install PHP:

Run the following command to setup PHP:

sudo apt-get install php libapache2-mod-php php-mcrypt php-mysql

Now that php is installed, we want our server to look for Index.php first rather than index.html. So let’s change that by opening up this server file. Type in the following command:

sudo nano /etc/apache2/mods-enabled/dir.conf

Look for the below lines and change the order in which the apache2 server looks for files to load by default.

<IfModule mod_dir.c>
DirectoryIndex index.html index.cgi index.pl index.php index.xhtml index.htm
</IfModule>

Change it to,

<IfModule mod_dir.c>
DirectoryIndex index.php index.html index.cgi index.pl index.xhtml index.htm
</IfModule>

After this, we need to restart the Apache web server in order for our changes to be recognized. You can do this by typing this:

sudo service apache2 restart

We can also check on the status of the apache2 service using systemctl:

sudo systemctl status apache2

Output:

apache2.service – LSB: Apache2 web server
Loaded: loaded (/etc/init.d/apache2; bad; vendor preset: enabled)
Drop-In: /lib/systemd/system/apache2.service.d
└─apache2-systemd.conf
Active: active (running) since Wed 2016-04-13 14:28:43 EDT; 45s ago
Docs: man:systemd-sysv-generator(8)
Process: 13581 ExecStop=/etc/init.d/apache2 stop (code=exited, status=0/SUCCESS)
Process: 13605 ExecStart=/etc/init.d/apache2 start (code=exited, status=0/SUCCESS)
Tasks: 6 (limit: 512)
CGroup: /system.slice/apache2.service
├─13623 /usr/sbin/apache2 -k start
├─13626 /usr/sbin/apache2 -k start
├─13627 /usr/sbin/apache2 -k start
├─13628 /usr/sbin/apache2 -k start
├─13629 /usr/sbin/apache2 -k start
└─13630 /usr/sbin/apache2 -k start

STEP 9.4 – Install phpMyAdmin:

phpMyAdmin was created so that users can interact with MySQL through a web interface. Run the command below to install it:

sudo apt-get install phpmyadmin php-mbstring php-gettext php-curl

• For the server selection, choose apache2.
• Select yes when asked whether to use dbconfig-common to set up the database
• You will be prompted for your database administrator’s password
• You will then be asked to choose and confirm a password for the phpMyAdmin application itself

The installation process actually adds the phpMyAdmin Apache configuration file into the /etc/apache2/conf-enabled/ directory, where it is automatically read.

The only thing we need to do is explicitly enable the PHP mcrypt and mbstring extensions, which we can do by typing:

sudo phpenmod mcrypt

sudo phpenmod mbstring

Now lets add the phpMyAdmin config to apache by opening up apache configuration:

nano /etc/apache2/apache2.conf

Add the following lines:

#phpMyAdmin Configuration

Include /etc/phpmyadmin/apache.conf

Afterwards, you’ll need to restart Apache for your changes to be recognized:

sudo systemctl restart apache2

You can now access the web interface by visiting your server’s domain name or public IP address followed by /phpmyadmin:

http://<ip_address_of_the_droplet>/phpmyadmin

Optionally, if you would like to secure your installation of phpMyAdmin even further, you can follow the steps here:

https://www.digitalocean.com/community/tutorials/how-to-install-and-secure-phpmyadmin-on-ubuntu-16-04#step-two-%E2%80%94-secure-your-phpmyadmin-instance

And that’s it for installing the LAMP stack!

STEP 10 – Domain setup:

This is the step where you add a domain to your droplet so you can run the PushMaze software under that domain. To be able configure the domain and point it to the droplet, you’ll need to go to your domain registrar (this is the place where you bought the domain) and configure the domain’s nameservers to point to DigitalOcean. Check this article for more details: https://www.digitalocean.com/community/tutorials/how-to-point-to-digitalocean-nameservers-from-common-domain-registrars

Once the nameservers are setup, you can then go into the DigitalOcean dashboard to setup the domain to point to the droplet.

Enter a domain of your choice and press “Add Domain”

On the domain details page, create an A record to point to the IP address of the droplet you just created, set TTL to 1800 seconds and press “Create Record”

STEP 11 – Setup a VirtualHost for PushMaze:

The next step in setting up the PushMaze software would be to setup a VirtualHost in Apache. In order to do this, we will get the software uploaded onto the server.

Step 11.1 – Copy files over:

Download the PushMaze package (pushmaze_latest.zip). We can use secure copy (scp) method to upload the zip file. Open a new terminal, and enter this command on your local machine:

scp -i ~/.ssh/id_rsa.pub  <path_to_pushmaze_src>/pushmaze_latest.zip <user>@<ip_address>:/home/<user>/pushmaze.zip

Now, switch to the remote server terminal, and enter the following commands:

sudo apt-get install unzip

cd ~

unzip pushmaze.zip

Note: “Path to pushmaze src” means the path your downloaded package is in, eg: C:/Users/PC Name/Downloads/pushmaze

Once you’ve copied the files over, login to the server via ssh and then create a symlink to the /var/www/ folder

sudo ln -s /home/<user>/pushmaze  /var/www/pushmaze

Step 11.2 – Configure the filesystem:

We need to make some file system changes for the software to work. Type in the following commands in sequence in the remote server:

cd ~/pushmaze

sudo chmod -R 0777 storage

mkdir uploads && sudo chmod -R 0777 uploads

sudo chmod -R 0777 DB

sudo chmod -R 0777 bootstrap/cache

php artisan key:generate

sudo chown www-data:www-data ~/pushmaze/public/firebase-messaging-sw.js

sudo chown www-data:www-data ~/pushmaze/.env

Step 11.3 – Create & configure the apache VirtualHost config file:

Creating the VirtualHost file lets us tell apache where to serve the PushMaze files from. To start off, run this command:

sudo cp /etc/apache2/sites-available/000-default.conf /etc/apache2/sites-available/pushmaze.conf

Let’s open this file up and configure the VirtualHost:

sudo nano /etc/apache2/sites-available/pushmaze.conf

The file will look something like this (The comments have been removed to make it readable):

<VirtualHost *:80>
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Now we will customize the file like below. Make sure to replace the text in RED with the actual values that pertain to your installation.

<VirtualHost *:80>
ServerAdmin admin@example.com
ServerName example.com
DocumentRoot /var/www/pushmaze/public

<Directory “/var/www/pushmaze/public”>

Options FollowSymLinks

AllowOverride all

Require all granted

</Directory>

ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

NOTE: If you don’t have a domain to point to the droplet, you could use the IP address of the droplet as well, and in the place of example.com, you’d use the IP Address and not use the ServerAlias line.

Step 11.4 – Enable the VirtualHost:

Now that we have created our virtual host files, we must enable them. Apache includes some tools that allow us to do this. We can use the a2ensite tool to enable our VirtualHost like this:

sudo a2ensite pushmaze.conf

sudo systemctl restart apache2

After restarting apache2, wait for a bit for the DNS to propagate you should be able to visit http://<domain.com> and see the home page of PushMaze.

STEP 12 – Setup the SSL certificate:

The next step in this process would be to setup an SSL certificate for the VirtualHost we just setup. We will be installing a software called certbot-auto to setup the SSL certificate.

Enter the following commands in the remote server:

cd

wget https://dl.eff.org/certbot-auto

chmod a+x ./certbot-auto

./certbot-auto

Once you’ve entered the last command, follow the prompts on screen. Once certbot-auto installs all the required software, it’ll ask you the following questions:

Which names would you like to activate HTTPS for?

——————————————————————————-

1: domain.com

——————————————————————————-

Select the appropriate numbers separated by commas and/or spaces, or leave input

blank to select all options shown (Enter ‘c’ to cancel):

You can enter “1” to indicate you’d like to create an SSL cert for the domain.

Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.

Select the appropriate number [1-2] then [enter] (press ‘c’ to cancel):

You can enter “2” to indicate you’d like to redirect all non https traffic to https.

Once everything is done, you should be able to see:

——————————————————————————-

Congratulations! You have successfully enabled https://<domain>.info

——————————————————————————-

Once this is done, you can verify that your PushMaze install works only on https and not on http by visiting https://<your-domain.com>

STEP 13 – Run the Installer:

This completes the server setup for Pushmaze. Now open up a browser and type in the URL : https://<domain.com>/installer 

Installer Step 1 – Database configuration.

In this step, you’ll enter database details for the application. The user you’re entering here needs to have privileges to create databases and tables.

Eg:

Application URL: https://domain.com

Database host name : localhost

Database username : root

Database Name : pushmaze

Database Password : pushmaze123

Click next once done.

Installer Step 2 – PushMaze Admin Config:

In this step, enter details of the first user account and the email ID and the password you’d like to login with. You can change this later.

Installer Step 3 – PushMaze FCM configuration:

In this step, you’ll be configuring the PushMaze app. Enter the name of the PushMaze Installation, a logo and a favicon if you’d like that.

We’ll also be adding the “Push Server Auth Key”, which we’ll get from Firebase. In order to get the server auth key, follow the below steps:

1. Go to: https://console.firebase.google.com/ and click on “Add Project”. Enter a project name and copy the project ID. Press “Create Project”
   
2. Once the project is created, click on the gear icon next to “Project Overview” and choose “Project Settings”
   
3. Choose “Cloud Messaging” and copy the Server key from that page.
   

Enter the server key from the FCM dashboard and click next

Installer Step 4: Firebase API setup:

Go back the firebase dashboard by clicking on “Project Overview”. You’ll see the getting started page like below. Click on ‘Add Firebase to your Web App’

You’ll get a popup with the details required for the next step. Enter these details one by one into the installation form.

After you complete this page it will automatically redirect to admin login page where you can enter the details of the first user you created in step 2 of the installation process.

STEP 14 – Setup Crontab:

We also need to setup a couple of cron jobs that enable you to send scheduled notifications and notifications from an RSS feed.

You can do this by opening your crontab by using the command

crontab -e

And pasting the line below which run the scheduled tasks according to the timings defined.

* * * * * /usr/bin/php /home/$USER/pushmaze/artisan schedule:run >> /dev/null 2>&1

STEP 15 – Set Permissions:

Finally we want to make sure that the apache web server is able to make changes to the public folder inside the pushmaze directory.

We can do this by running the following command:

sudo chown -R www-data:www-data ~/pushmaze/public

STEP 16 – Setup logrotate:

In this step, we will setup logrotate that will automatically rotate our log files so our servers don’t get clogged up.

Run the following commands:

sudo nano /etc/logrotate.d/pushmaze.conf

Paste the following block of text into the file that will enable logrotate to keep our log files clean.

/var/www/pushmaze/storage/logs/*.log {

    daily

    missingok

    rotate 14

    compress

    notifempty

    create 0640 www-data www-data

    sharedscripts

}

ALL DONE!

Installation is now complete. Browse around in the admin and check out all the features.

Please let us know if you have any questions about any of the above steps. If you have trouble installing, please contact us at support@pushmaze.com. All the best! 🙂