Installation: Back-end App

Preamble


There are a lot of ways to deploy to production. What I describe here is a very plain way to go about it.

I am assuming that you use Laravel Forge to deploy to your production server.

Forge deploys from a repository, and I am assuming that, like me, you use GitHub.com.

The way I do it is to set up my repository locally, then push to GitHub.com, then have Forge deploy from the GitHub.com repository.

I use MAMP Pro (not an affiliate link) for my local installations. Whatever local environment you use, it comes down to the same things: composer install, creating your database, updating the .env, and then firing up your up locally.

You should save your APP_KEY somewhere because it is used for encryption. My suggestion where to save your key: AWS Key Management Service.

Laravel Nova


My administrative app needs Laravel Nova to run.

So you need to buy Nova.

No, I do not have an affiliate link nor any arrangement with Nova. I decided to use Nova because it is a creation of the Laravel Project.

Nova is installed via composer. The documentation for doing this is here.

Installing on your Local Environment


Set up your new Laravel site


You will need the usual server stuff for local development. Here's Laravel's server requirements.

Run this command from the command line, which will create a "ls-adminbackup-app" folder, and install LaSalle Software's admin app. Create a folder name that suits your individual needs:
composer create-project lasallesoftware/ls-adminbackend-app ls-adminbackend-app

"cd" into the local app's root folder:
cd ls-adminbackup-app


Set up your local database


You need a database, so if you have not set up your local database for this local deployment, the please do so now.


Run lslibrary:lasalleinstallenv


Run my custom installation artisan command for setting a few environment variables in your .env file:
php artisan lslibrary:lasalleinstallenv

Please be very precise with your typing, as my artisan command does not validate anything.


Review your local .env file


You should not see any values beginning with the characters "Dummy", which are placeholder values used in "lslibrary:lasalleinstallenv" for string substitution.

If you are using MAMP, your MySQL may not work so you should add the following "DB_SOCKET" variable to your .env:
// https://stackoverflow.com/questions/50718944/laravel-5-6-connect-refused-using-mamp-server
  DB_SOCKET=/Applications/MAMP/tmp/mysql/mysql.sock

To include my test data with the seeding, in your .env, set:
LASALLE_POPULATE_DATABASE_WITH_TEST_DATA=true

Please double check your .env for errors and typos.


Run lslibrary:lasalleinstalladminapp


This command prepares Laravel Nova, performs an optional database drop, and executes the database migration and seeding.

Run:
php artisan lslibrary:lasalleinstalladminapp


Edit the Nova Service Provider


In "App\Providers\NovaServiceProvider", in gate() when you are not including my test data in the seeding, delete all the email addresses except for "bob.bloom@lasallesoftware.ca".

Please note that the emails you specify here will be pushed to GitHub.com for use on your Forge deployment.

composer.json


There are three different composer.json files: composer.classic.json, composer.development.json, and composer.forge.json.

Copy "development" to composer.json for your local set-up.

Copy "forge" to composer.json for your production deployment in Forge.

"Classic" is there as a starting point to customize composer.json to specific needs.

I copy the forge version to composer.json, then push it to GitHub.com. Then, I copy the development version to composer.json excluding it from my pushes to GitHub.com. This is one way to solve the problem of having one composer.json in your repo but requiring different versions for different environments.

The composer.json in your remote GitHub.com repo is pulled into Forge as your production composer.json. But you will want to use a different composer.json for your local development. So you'll have to figure something out!

Sometimes I .gitignore composer.json, and then copy the appropriate composer version to composer.json immediately before running composer install/update.

Since we are setting up the local environment, and I include composer.json in the repo, and to save you the hassle of setting up individual package repos on your local, and the default composer.json I maintain in my FOSS repo is the Forge version, there's nothing to do. However, if you want to mess around with your composer.json, now is the time!

Then run:
composer install


Fire up your local LaSalle Software admin app in your browser!


You should see the familiar Laravel welcome view.

Click "login". These credentials are set up so you can log in:
  • user = bob.bloom@lasallesoftware.ca
  • password = secret

  • Change these credentials!

    Deploying on Laravel Forge


    Preamble


    Since I use webhooks to trigger a Forge deployment, I need a repository somewhere that Forge can "git pull origin master" from. I pull from a Github repository.

    I install a local app first (see the steps above). Then I make this installation a git repository. Then, I create a new Github repository and push my local repository to it.

    Now, it's time to set up things on Forge.

    I assume that you have your server already set up. Make sure that when you set up your server that you set up your database server as well Forge: Creating a Server With a Database.

    Set up your new Laravel site in Forge


  • click Servers | the-name-of-your-server
  • you should see "New Site"
  • set up your new Laravel site, then click "Add Site"
  • you should see your new site listed in Active Sites


  • Set up Let's Encrypt SSL in Forge


  • click Sites | the-name-of-your-site
  • click SSL
  • click the "LetsEncrypt" box
  • make sure that "Domains" is correct, then click "Obtain Certificate".
  • that's it!


  • Set up your database, and optionally your database user, in Forge


    It's time to set up your database. Your database server should already be installed!
  • click Servers | the-name-of-your-server
  • click Database

  • In the "Add Database" box:
  • type in the "Name" of your database
  • type in new "User (Optional)" of your database, ONLY IF YOU WANT TO CREATE A NEW DATABASE USER
  • type the "Password (Optional)" for your new database user, ONLY IF YOU WANT TO CREATE A NEW DATABASE USER
  • click "Add Database"
  • done!


  • Run lslibrary:lasalleinstallenv


    SSH into your cloud server, and cd into your app's root folder.

    Run my custom installation artisan command for setting a few environment variables in your .env file:
    php artisan lslibrary:lasalleinstallenv


    Edit Your .env

  • click Sites | the-name-of-your-site
  • click Environment
  • click "Edit Environment"

  • Test data will not seed in the "production" environment. Here is the method. Even so, set:
    LASALLE_POPULATE_DATABASE_WITH_TEST_DATA=false

    If you want to enable IP address "whitelisting", then set this variable to "yes":
    LASALLE_WEB_MIDDLEWARE_DO_WHITELIST_CHECK=yes
    and enumerate your "whitelisted" IP addresses:
    LASALLE_WEB_MIDDLEWARE_WHITELIST_IP_ADDRESSES=ipaddress1,ipaddress2,ipaddress3

    If you have a lot of IP addresses to "whitelist", then please enumerate them in the "lasallesoftware-library" config file.

    The only reason I have an env var for the IP addresses is to get around having to update the config file. It is easier to update the .env in Forge. My LaSalle Software uses the IP address specified in BOTH the .env and the config.

    Please note that Forge has likely changed the values of your database environment variables. So my custom artisan command will not be able to change them if the values are incorrect. Please scroll down to the database environment variables to double check that they are correct!

    Run lslibrary:lasalleinstalladminapp


    Return to your app's root folder on your cloud server instance.

    Run my custom installation artisan command for my admin app only:
    php artisan lslibrary:lasalleinstalladminapp

    This command will prepare Laravel Nova, perform an optional database drop, and do the database migration and seeding.

    The database seed is necessary to run the admin app.

    You will be prompted to create the first user (with the "owner" role). Please follow the prompts to enter your first user's first name, surname, and email address.

    Fire up your local LaSalle Software admin app in your browser!


    You should see the familiar Laravel welcome view.

    Click "login".

    If you were prompted to create your first user, then login with the email address that you entered. Your initial password defaults to "secret". Please change this password upon your initial login.

    If you seeded your database with test data, then use these credentials to log in:
  • user = bob.bloom@lasallesoftware.ca
  • password = secret
  • Using Cloud Storage


    In production, you should use cloud storage for your images, especially when you are using multiple domains.

    See my doc on Setting Up Amazon Web Services S3.