iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
A first AWS CodeDeploy deployment to EC2 comes down to five pieces working together: an application, a revision with an appspec.yml file at its root, a deployment group that selects the target instances, a running CodeDeploy agent with the right instance profile on each target, and a deployment whose lifecycle events you check one by one. This walkthrough follows Chandra, a developer making that first deployment, through each piece in the order it is needed.
It describes the documented EC2/On-Premises workflow. It does not reproduce a specific operating system, repository, command log, or error from one test run, and it does not cover ECS or Lambda, which use different AppSpec and deployment rules.
The five pieces and how they relate
- Application: the CodeDeploy container that groups your deployment settings. It holds no servers itself.
- Deployment group: the set of target instances and the deployment type (in-place or blue/green) for that application.
- Revision: the bundle of application files, scripts, and an AppSpec file that CodeDeploy installs.
- Target instances: the EC2 instances (or on-premises servers) that receive the revision.
- CodeDeploy agent: software on each target that downloads the revision, copies files, and runs your scripts.
The official flow starts with an application and a deployment group, uploads the revision to Amazon S3 or GitHub, and has the agent on each target retrieve and unbundle it, copy files according to AppSpec, and execute configured scripts. (AWS: Deployments on an EC2/On-Premises Compute Platform)
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Step 1: Prepare the revision and its AppSpec file
Chandra started with a folder that contained the application and its deployment scripts. The layout that matters for CodeDeploy looks like this:
my-app/
├── appspec.yml
├── app/
│ └── index.html
└── scripts/
├── stop_server.sh
├── install_deps.sh
├── start_server.sh
└── validate.shThe AppSpec file must be YAML, must be named exactly appspec.yml, and must sit at the root of the revision directory. A revision can contain only one AppSpec file. Without it, CodeDeploy cannot map source files to destinations or run scripts. (AWS: Add an application specification file to a revision for CodeDeploy)
A minimal example for a Linux instance:
version: 0.0
os: linux
files:
- source: /app
destination: /var/www/my-app
hooks:
ApplicationStop:
- location: scripts/stop_server.sh
timeout: 60
runas: root
AfterInstall:
- location: scripts/install_deps.sh
timeout: 300
runas: root
ApplicationStart:
- location: scripts/start_server.sh
timeout: 120
runas: root
ValidateService:
- location: scripts/validate.sh
timeout: 60
runas: rootWhat each part does
- version: 0.0 is the AppSpec format version for EC2/On-Premises.
- os: linux tells the agent which operating system the file targets. Windows revisions use a different value.
- files maps
sourcepaths inside the revision to adestinationon the instance. Here, everything underapp/is copied to/var/www/my-app. - hooks names the lifecycle events where scripts run. Each
locationis a path relative to the revision root,timeoutis in seconds, andrunassets the user the script runs as.
Scripts that finish with exit code 0 count as successful, and the result is written to the CodeDeploy agent log. Indentation errors and wrong paths are the most common reasons a valid-looking file fails.
Package the revision with AppSpec at the top level
Zip the contents of the folder, not the folder itself, so appspec.yml is at the archive root:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
- Used Book in Good Condition
cd my-app
zip -r ../my-app.zip .Then upload and register the revision. The aws deploy push command uploads the bundle to S3 and registers the revision with the application in one step:
aws deploy push
--application-name my-app
--s3-location s3://your-bucket/my-app.zip
--source .Use an S3 bucket in the same Region as the deployment. Cross-Region placement is one of the causes AWS lists for revision-download failures.
Step 2: Choose a deployment type
Chandra had to decide between in-place and blue/green before creating the deployment group. The choice changes which instances get the new code and whether a second environment exists during the rollout.
| Question | In-place | Blue/green |
|---|---|---|
| Which instances receive the revision | The existing instances in the deployment group | Replacement instances that CodeDeploy creates for the deployment |
| Traffic handling | Updates happen on the instances that are already serving | Traffic can be shifted to the replacement environment through a load balancer, when that is configured |
| Separate environment to validate before cutover | Not created | Created, so the new environment can be checked before traffic moves |
| Infrastructure needed beyond the group | None beyond the targets | A load balancer if you want traffic routing |
| Best fit for a first deployment | A single group with a small number of existing instances and the fewest moving parts | A workload where you must validate a full replacement environment and already run a load balancer |
Blue/green does not promise zero downtime or automatic rollback by itself. Those outcomes depend on how your load balancer, health checks, and deployment configuration are set up. (AWS: Working with deployments in CodeDeploy)
Step 3: Create the deployment group and select targets
The deployment group decides which instances are in scope. It can select targets in three ways: individually tagged EC2 instances, members of an EC2 Auto Scaling group, or both. For a first deployment, a tag selector is easiest to reason about because you can see exactly which instances match.
- Tag each target instance in the EC2 console with a key and value that only the test servers carry, for example
Environmentwith the valuecodedeploy-test. - In the CodeDeploy console, open the application and choose Create deployment group.
- Give the group a name and select the service role CodeDeploy uses to act on your behalf.
- Under the environment configuration, select Amazon EC2 instances and enter the same tag key and value.
- Choose the deployment type you selected in Step 2 and save the group.
Check the match before you deploy. Every instance you expect should appear in the group’s instance list. An untagged or mistagged server is silently excluded, which is a common first-deployment surprise.
Rank #4
Step 4: Prepare each target instance
Each target needs two things before the deployment starts.
The CodeDeploy agent
The agent must be installed and running on every target. Follow the installation steps in AWS’s agent documentation for your operating system and Region. On a Linux instance, confirm the service is running with sudo service codedeploy-agent status. The agent writes its own log to /var/log/aws/codedeploy-agent/codedeploy-agent.log, which is the first place to look when something goes wrong. (AWS: Working with the CodeDeploy agent)
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteAWS’s agent release history lists version 2.1.0, dated September 7, 2026. That release adds native support for the RESTART deployment mode and changes security handling so the agent rejects any AppSpec path that resolves outside the revision directory. Keep hook locations and file sources inside the bundle, and check the release history for the version supported in your Region and on your operating system before you install.
Best Value
The instance profile
The instance must have an IAM instance profile whose role lets it reach the revision bucket and the CodeDeploy endpoints. A missing profile or insufficient permissions is the most frequent cause of agent communication and S3 download failures that AWS documents. Attach the profile to the instance, then confirm the instance is tagged as your deployment group expects.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Step 5: Deploy and verify the lifecycle events
With the group ready, Chandra started the deployment from the group’s page:
- In the CodeDeploy console, open the application and select the deployment group.
- Choose Create deployment.
- Select the revision you registered in Step 1, then start the deployment.
- Open the new deployment and expand each instance to see its lifecycle events.
For an in-place deployment on Linux, the events run in this order: ApplicationStop, DownloadBundle, BeforeInstall, Install, AfterInstall, ApplicationStart, and ValidateService. An event with no hook in your AppSpec still appears, and it should complete without error. Success means every instance reports the deployment as succeeded, and the last event, ValidateService, has run your check script and returned 0.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Verify the result on the server, not only in the console. Load the page or call the endpoint your validate script checks, and confirm the copied files are at the destination path in the AppSpec.
When the first deployment fails
Start with the failed lifecycle event in the deployment details, then work through the causes below. Change one setting at a time, and redeploy after each change so you know which fix worked. These checks follow AWS’s troubleshooting guidance. (AWS: Troubleshoot EC2/On-Premises deployment issues, AWS: General troubleshooting issues)
Agent and access
- Confirm the agent is installed and the service is running on the failing instance.
- Confirm the instance has the correct IAM instance profile and that the role can read the revision bucket.
- Confirm the revision bucket is in the same Region as the deployment.
- Confirm the instance can reach AWS endpoints. Network rules that block them stop the agent from communicating.
- Check memory and disk space. Low resources can cause failures during download or unbundling.
Revision and AppSpec
- Confirm
appspec.ymlis at the top level of the zip, and that there is only one AppSpec file in the revision. - Validate the YAML. Indentation and quoting mistakes are the usual cause.
- Check that every
source,destination, and hooklocationpath exists and resolves inside the revision or the intended destination.
Scripts and previous revisions
- Read the script output in the agent log, and confirm the script exits with code 0.
- Note that the ApplicationStop, BeforeBlockTraffic, and AfterBlockTraffic scripts can come from the previously successful deployment’s AppSpec file. Other scripts come from the current revision. If a failure occurs in one of those three events, review the previously deployed revision as well.
AWS recommends sending deployment logs to CloudWatch Logs for central monitoring, which makes it easier to compare a failing instance with a working one.
Quick Recap
Before the next deployment
- The AppSpec file is named
appspec.yml, is valid YAML, and sits at the root of the zip. - Every source, destination, and hook path matches a real file or location.
- The deployment group’s tag or Auto Scaling selector returns exactly the instances you expect.
- The agent is running on every target, and each instance profile can read the revision bucket.
- The deployment type matches what you need to validate, and any load balancer it depends on is configured.
- You have a log location and a check that proves the new version is live.
“
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Free tools Windows power users keep installed
One-click scans. No signup required.
