Deployment and Sync

As a very powerful part LUYA ecosystem a timesaving and pretty awesome processes for synchronization and deployment has been developed. This guide explains the best practice of how to bring your website online and sync it back to your local development environment.

The following is required to reproduce the steps in this guide:

• Git repository (we use GitHub, BitBucket or others are working too).
• Server with SSH access (Prod environment).
• SSH keys so you can fetch the data from the production server. There is a good tutorial on setting up the keys here
• A local development machine with LAMP, MAMP or WAMP stack.

This process never syncs data from the local environment to the production server, only the opposite way!

When starting to build a website, follow this proposed process:

1. create a GitHub repository for the project
2. check out the LUYA kickstarter project
3. add the included files into the new GitHub repository (don't commit the vendor directory - this is downloaded by Composer)
4. start developing your website.

We recommend that you deploy the website to the server in an early stadium of the development cycle. So use dummy text and data on your local system.

Deployment

The deployment (using LUYA deployer) will mainly publish the Git repository on the production server and runs certain LUYA related tasks, like migration and import commands. It will also ensure the right env.php is created on the server based on the deploy.php server name setting server('prod', ...).

1. Set up your production environment on the server (create the database, enable SSH, etc.)
2. Ensure the config contains the right informations in luya\Config::ENV_PROD context.
3. Install and configure the [LUYA deployer]https://github.com/luyadev/luya-deployer)
4. Deploy your website with the ./vendor/bin/dep luya prod command.
5. First deployment: Run the ./vendor/bin/luya admin/setup command on the production server. To do so loggin with SSH and run the admin/setup command.

After the first deployment make sure the public_html/assets, public_html/storage and runtime is writeable, if the deployer could not set the permissions accordingly.

If you encounter problems while deployment try to run ./vendor/bin/dep luya prod -vvv which will display more informations.

Connection strategies

You can connect to the server either using:

• Password ->password('your pwd')
• Identity file ->identityFile('~/.ssh/yourkey')
• PEM file (e.g. using AWS or Lightsail) ->pemFile('~/.ssh/yourfile.pem')

We recommend to use either the identity or pem strategy: this way you can commit your deploy.php file on your repo, without having to store a password on the repo, which you don't want to do of course.

Example configuration file

<?php
namespace Deployer;

require 'vendor/luyadev/luya-deployer/luya.php';

// define your configuration here
host('SSHHOST.COM')
    ->stage('prod')
    ->port(22)
    ->user('SSHUSER')
    ->set('deploy_path', '~/httpdocs');

set('repository', 'https://USER:PASSWORD@github.com/VENDOR/REPO.git');

You are now ready to deploy your website to the server and can start to add content on the production environment.

Synchronization

The developed ./vendor/bin/luya admin/proxy sync command synchronize the database and files from the production environment to a number of local clients. In order to set up this command login to your LUYA admin UI on the production server, navigate to System -> Machines and create a new one.

After creation of your local machine you have to copy the identifier and token that is generated in the next step.

Now run the ./vendor/bin/luya admin/proxy command in your terminal. You will be asked to enter the URL of your production environment (e.g. https://luya.io) and then enter the machine and identifier and token from the previous step.

Terminal commands:

./vendor/bin/luya admin/proxy --> run or setup proxy urls and secret token
./vendor/bin/luya admin/proxy/clear --> clear and reset local stored proxy configuration

In case an error occurs when executing the admin/proxy command, executing the admin/proxy/clear command first might help (you will have to enter the url, identifier and token after resetting the configuration with the clear command).

For details and more commands, see luya\admin\commands\ProxyController .

Deploy prep env

When running a pre-production env (prep) it's very common to copy the database and files after deployment but it's recommend to achieved that with deployer and admin/proxy via the smart way. Therefore just update your deploy.php following the example below:

task('deploy:syncProdEnv', function() {
    $proxy = run('cd `release_path` && ./vendor/bin/luya admin/proxy --url=https://www.prod-website.com --idf=IDENTIFIER --token=TOKEN');
    writeln($proxy);
    
})->onlyOn('prep');
after('deploy:shared', 'deploy:syncProdEnv');

Now on every deployment to the prep env by using ./vendor/bin/dep luya prep will sync the files from the prod env.