brunocfalcao / Larapush

Deploy your codebase to your web server using a new Laravel Artisan command

php artisan push

Features

• Client <-> Server communications using HTTP. No need to have SSH access!
• Choose what codebase you want to upload (files, folders).
• Run pre-scripts and post-scripts that you define (artisan commands, invokable classes, or custom methods).
• You can choose to upload only modified files, or all files inside your codebase.
• Blacklist files so they can never be uploaded to your web server (e.g. .env).
• Keeps all of your uploaded codebase versions backup on your storage path.
• Get prompted in case you are uploading to production environments.
• Works on both UNIX and Windows web servers.

Requirements

Database is only needed in your web server (Laravel Passport will be installed)
PHP 7.2+
Laravel 5.8+

Installation

❗️ In order to generate your OAuth client and token, you need to first install Larapush on your web server!

Log in into your web server and run the following commands:

composer require brunocfalcao/larapush

php artisan larapush:install-remote

At the end, it will generate your command line that you will need to use to install it on your local computer. As example:

❗️ Now copy+paste the one generated on your web server so you can use it later on your local installation.

On your local development computer, run the following commands:

composer require brunocfalcao/larapush

Now paste the line from your previous web server installation to your local computer prompt. Here is an example:

php artisan larapush:install-local --client=4 --secret=5DrehY2gjPWTPL4rxzQwseHiQHWq8FXaH0Y --token=WXD2W6ZVK5

The installer will prompt to insert your web server URL. Just add it in the FQDN format (e.g.: https://www.johnsmith.com).

The installation completes you should see:

All good! Now you can push your codebase to your web server!

Don't forget to update your larapush.php configuration file for the correct codebase files and directories
that you want to upload.

Usage

Henceforth all you have to do is to run the command:

php artisan push

It will upload your codebase that you define on your larapush.php configuration file (larapush.codebase) and the scripts that you also specified (larapush.scripts).

Configuration

A new larapush.php configuration file is created. Let's explore it.

larapush.type

No need to change this, it is automatically configured by the installers using .env keys that will be registered.

larapush.environment

If your web server environment name matches one of the ones specified here, then Larapush will ask you to confirm the upload each time you push your code. This will avoid you to upload your codebase to environments that you might not want to (like a production).

larapush.remote

No need to change these keys by default, unless you want to change the main root URL path, or force a web server URL.

larapush.scripts (pre_scripts and post_scripts)

You can specify actions to run before and after the code is deployed on your web server. For each, you can:

• Run an Artisan command. E.g.: ['cache:clear', ScriptType::ARTISAN]
• Execute an invokable method. E.g.: [MyClass::class, ScriptType::CLASSMETHOD]
• Execute a specific object method: E.g.: ['[email protected]', ScriptType::CLASSMETHOD]
• Execute a system shell commands: E.g.:"['composer dumpautoload', ScriptType::SHELLCMD]

You can add as much as you want. All outputs are stored inside your transaction folder (later to be explained).

larapush.codebase

Important part, where you can specify your codebase folders and files. Just add them as array values, E.g.:

    'codebase' => [
        'App', 'database', 'resources/views/file.blade.php', 'webpack.js'
    ],

larapush.storage

This is the path where all of your codebase push transactions are stored. See it like a versioning way of storing all of your codebase along time.

larapush.oauth

These are security tokens generated by Laravel Passport. Don't change them, they are recorded on your .env file.

larapush.token

This is an extra security layer, of a token that needs to be the same in both web server and your local dev computer. Registered via your installation process.

Codebase transaction repository

Each time you upload your codebase, Larapush stores that codebase plus your configured "pre" and "post" scripts both in your local computer and in your web server. This is called a transaction. By default these transaction folders are on your storage_path("app/larapush"). You can change this path on your larapush.php configuration file.

As example, you are pushing your codebase and you see this line on your artisan command info:

[...]

Creating local environment codebase repository (20190413-211644-GFKXN)...

[...]

That code between parenthesis is the transaction code. If you navigate to your storage-path/app/larapush you will see all the transaction folders listed there. Each of those correspond to a push you have made to your web server.

Here is an example of the folders location:

In your web server it works exactly the same way. Additionally on each of the folder you might see also 2 files:

output_pre_scripts.log
output_post_scripts.log

Those are the console exports of the scripts that ran on each of your codebase push. So, in case you are running scripts you will see your console output there. Nice, heim? :)

Security above all

Larapush was developed taking security very seriously. At the end, anyone that knows your endpoint would be able to upload a malicious codebase to your web server. That's why Larapush uses OAuth client grant access tokens for each of the HTTP transactions that are handshaken between your web server and your local computer. At the end of the HTTP transaction, the client access token is marked as used, so it cannot be used again.

When you install Larapush on your web server, it installs Laravel Passport and generates a specific client token that will be unique between your web server and your local computer. Henceforth any transaction between your local computer and your web server needs to first request a new client grant token and then use that token on the respective HTTP call. Additionally there is also a token that is passed on each request that needs to be the same between your local computer and the web server. If not, the transaction aborts in error.

All of this is done automatically each time you push your codebase. Nice and smooth!

Security

If you find any security related issue please send me a direct email.

License

The MIT License (MIT). Please see License File for more information.