Editing Troubleshooting Elastic Beanstalk Deployment (section)

== Deployment ==

=== eb deploy failure ===

* Run `eb logs` in the local distribution of the environment to view the latest commands run in the EBS environment.
** If `eb logs` generates a "permission denied" message, try `eb logs --instance [EBS-INSTANCE-ID] --verbose`
* View the tail of the file `/var/log/cfn-init-cmd.log`. This file will list all commands in `.ebextensions` and whether they executed successfully or not.
* Check the `.ebextensions` config files on the server in `/var/app/staging/`
* Confirm the domain settings in AWS Route 53.
* Confirm that the web files have been uploaded to `/var/www/html/`.
* Confirm the EBS raw URL to the site: '''AWS Console''' > '''Elastic Beanstalk''' > '''Environments''' > ''click on the URL for the environment in question''
* Scale back the application and incrementally deploy.
** Remove all web files except for a boilerplate "Hello, World" index file.
** Comment out all commands in `.ebextensions` configuration files. 
** Remove `composer.json`
** Run `eb deploy` to see if it can successfully upload this most basic environment. 
** Incrementally add back components of the application and redeploy to isolate problematic components.

==== Errors running `composer install` ====

This could be due to an expired GitHub personal access token. 

These tokens allow composer to pull from private GitHub repos. 

The token is stored in a file in an S3 bucket. The file is copied to the EBS server in one of the `.ebextensions` scripts and used to run composer. Look in that script for the expected location of the file.

If the token is expired, [https://github.com/settings/tokens generate a new one]. Save the token in a text file and upload it to the S3 bucket, overwriting the old token file.

=== Directives in .ebextensions config files aren't executed ===

AWS eb cli uses git HEAD to create zip file to upload to the server. 

Confirm that zip files have been added and committed to the repo.

Or to deploy changes before they are committed:

<pre>
$ eb deploy --staged
</pre>

<p class="alert alert-warning">Make sure to stage any edits with git (e.g. `git add`) before running `eb deploy` with the `--staged` option!</p>

=== Local edits are not being deployed ===

By default, `eb deploy` uses the git repo, not local files for the application deployment.

To upload the local edits instead, first stage any edits, then use the `--staged` flag with `eb deploy`.

<pre>
$ git add ./
$ eb deploy --staged
</pre>

=== Cannot create files in /etc/nginx/conf.d with .ebextensions ===

According to this Stackoverflow thread, [https://stackoverflow.com/questions/24812375/websockets-on-elastic-beanstalk-with-docker WebSockets on Elastic Beanstalk with Docker], it seems that when EBS creates an application it basically clears out the nginx configuration after the .ebextensions commands are run. So any custom ngnix configuration done through .ebextensions would be overwritten. 

I have confirmed this insofar as I put my nginx configuration in a file and uploaded it successfully to the ec2-user home directory. I put in another command to move that file to the nginx configuration directory, and after the application was successfully deployed, the custom nginx configuration file was gone. 

There were some solutions offered on the Stackoverflow thread above. They involved moving Python scripts to an EBS “hooks” directory which would be executed after the application is deployed. There is no “hooks” directory in that location on my EBS server. 
For the time being, I am manually creating the nginx config file on the command line on the server after the application is deployed. This will allow the server to use the Let’s Encrypt certificates to serve https requests, and should stay in place through LE certificate renewals until the next application deployment.

The AWS documentation assumes that you generate the certificates manually and insert the contents of the certificate in the `.ebextensions` config file. The alternative example above places the command to generate the certificates in the `.ebextensions` config file. There is a flag that is incompatible with production environments: `--staging`. This will cause the Let's Encrypt staging server to issue the certificates. The server address will also get stored in a local config file, so subsequent attempts to reissue the certificates without the `--staging` flag will still invoke that staging server. <ref>[https://community.letsencrypt.org/t/cn-fake-le-intermediate-x1/13437/4 CN=Fake LE Intermediate X1] - Let's Encrypt forums</ref>

=== systemctl command not found ===

The AWS documentation uses `systemctl` to restart the Apache server. If this command is not available use the `service` command instead.

=== Cannot find SSLCertificateFile directive ===

When running `letsencrypt-auto` or `certbot-auto`

<pre>
Cannot find an SSLCertificateFile directive in /files/etc/httpd/conf/httpd-le-ssl.conf/IfModule/VirtualHost. VirtualHost was not modified
Unable to find an SSLCertificateFile directive
</pre>

This was fixed by successfully installing `mod_ssl`

=== Re-installing certificates after upgrading an Elastic Beanstalk instance platform ===

See [https://github.com/HausCloud/AWS-EB-SSL Easy Secure Single-Instance Elastic Beanstalk Apps].

The idea behind this is:

# Run a script that checks if security certificates are installed.
## Certfiicates are not installed. 
### Download and install the `certbot` utility script if it is not installed.
### Use `certbot` to install Let's Encrypt certificates.
### After installing the LE certificates, `certbot` will update the nginx configuration files to allow SSL to reference the certificates.
## Certificates are installed.
### Do not attempt to install any certficates.
### Before deploying the app, save the nginx config files modified by `certbot`.
### After deploying the app, restore the nginx config files that were modified by `certbot`.

=== Platform hook scripts are not executing ===

***Symptom*** 

`/var/logs/eb-engine.log` reports "Permission denied" for execution of the script.

***Solution***

Update permissions locally, then re-run `eb deploy`.

<pre>
$ chmod 755 my-platform-hook.sh
$ git update-index --chmod=+x my-platform-hook.sh
$ eb deploy --staged
</pre>