Understanding the AppSpec File Structure

The AppSpec file is a YAML file that defines the deployment lifecycle for your application on AWS CodeDeploy. It specifies the files to be copied to your instances, the commands to be run during different deployment phases, and the target location for these files.

AppSpec File for Linux Deployments

This example demonstrates a typical AppSpec file for a Linux environment. It outlines the essential deployment lifecycle events and their associated scripts.

Deployment Lifecycle Events

• ApplicationStop: Executes before the new application revision is downloaded. Used for gracefully stopping the application or cleaning up previous installations.
• BeforeInstall: Runs before files are copied to the target instance. Useful for tasks like decrypting files or creating backups.
• AfterInstall: Executes after files have been copied. Ideal for configuring the application or setting file permissions.
• ApplicationStart: Typically used to restart services that were stopped during the ApplicationStop phase.
• ValidateService: The final deployment lifecycle event, used to verify that the deployment was successful.

version: 0.0
os: linux
files:
  - source: /
    destination: /home/snake/_target
hooks:
  # This deployment lifecycle event occurs even before the application revision 
  # is downloaded. You can specify scripts for this event to gracefully stop the 
  # application or remove currently installed packages in preparation for a deployment. 
  # The AppSpec file and scripts used for this deployment lifecycle event are from the 
  # previous successfully deployed application revision.
  ApplicationStop:
    - location: scripts/stop_server.sh
      timeout: 300
      runas: root
  
  # You can use this deployment lifecycle event for preinstall tasks, 
  # such as decrypting files and creating a backup of the current version.
  BeforeInstall:
    - location: scripts/before_install.sh
      timeout: 300
      runas: root

  # You can use this deployment lifecycle event for tasks such as configuring 
  # your application or changing file permissions.
  AfterInstall:
    - location: scripts/after_install.sh
      timeout: 300
      runas: root

  # You typically use this deployment lifecycle event to restart services that 
  # were stopped during ApplicationStop
  ApplicationStart:
    - location: scripts/start_server.sh
    #- location: scripts/notify_post_start.sh
      timeout: 300
      runas: root

  #  This is the last deployment lifecycle event. It is used to verify the 
  # deployment was completed successfully.
  ValidateService:
    - location: scripts/validate_service.sh
      timeout: 300
      runas: root

Key AppSpec Components

• version: Specifies the AppSpec file format version.
• os: Defines the operating system for which the AppSpec file is intended (e.g., linux, windows).
• files: Lists the files to be deployed, including their source and destination paths.
• hooks: Defines the scripts to be executed at various deployment lifecycle events. Each hook specifies the script location, timeout, and the user runas.

Best Practices for AppSpec Scripts

• Ensure scripts are executable and have appropriate permissions.
• Use the timeout parameter to prevent deployments from hanging indefinitely.
• Run scripts as the appropriate user (e.g., root for system-level operations).
• Include error handling and logging within your scripts for easier debugging.