Merge pull request #2605 from OctopusDeploy/ellen/update-first-deploy…

…ment-guide

Jan 2025 First deployment guide updates

dictionary-octopus.txt

@@ -117,6 +117,8 @@ externalusers
 failstep
 fanout
 Fargate
+Favorited
+Favoriting
 feedcred
 Feedz.io
 fieldnames

src/pages/docs/getting-started/first-deployment/add-deployment-targets.mdx

@@ -1,17 +1,67 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2025-01-07
 title: Add deployment targets
 description: Step by step guide on how to add deployment targets in Octopus Deploy.
 navOrder: 70
 hideInThisSection: true
 ---
-import AddDeploymentTargets from 'src/shared-content/concepts/add-deployment-targets.include.md';
+With Octopus, you can deploy software to:
 
-<AddDeploymentTargets />
+- Kubernetes
+- Windows
+- Linux
+- Azure
+- AWS
+- Offline package drop
+- Cloud region
 
-The next step will [deploy a sample package](/docs/getting-started/first-deployment/deploy-a-package) to those deployment targets.
+Regardless of where you’re deploying your software, these machines and services are known as your deployment targets.
+
+## Add deployment target
+
+1. From the left Deploy menu, click **Deployment Targets**.
+
+:::figure
+![Deployment Targets page](/docs/getting-started/first-deployment/images/deployment-targets-page.png)
+:::
+
+2. Click **Add Deployment Target**.
+3. Use the category tabs to filter by deployment target type.
+4. Click **Add** on the deployment target you want to add.
+
+### Name
+
+Give your deployment target a descriptive name, for example, `Hello world tutorial target`.
+
+### Environments
+
+We’ll scope this deployment target to one environment. Later, you can add additional targets and scope them to your other environments.
+
+5. Select **Development** from the **Environments** dropdown list.
+
+### Target Tags
+
+Octopus uses target tags to select which deployment target a project should deploy to. Later, you’ll add the same target tag to your deployment process. You can deploy to multiple targets simply by adding this tag.
+
+6. Add a new target tag by typing it into the field. For this example, we’ll use `tutorial-target`.
+
+:::figure
+![Deployment target form](/docs/getting-started/first-deployment/images/deployment-target-form.png)
+:::
+
+Fill in the other sections of the deployment target form. If you need guidance, please refer to the relevant documentation:
+
+- [Kubernetes](/docs/kubernetes/targets)
+- [Windows](/docs/infrastructure/deployment-targets/tentacle/windows)
+- [Linux](/docs/infrastructure/deployment-targets/linux)
+- [Azure](/docs/infrastructure/deployment-targets/azure)
+- [AWS](/docs/infrastructure/deployment-targets/amazon-ecs-cluster-target)
+- [Offline package drop](/docs/infrastructure/deployment-targets/offline-package-drop)
+- [Cloud region](/docs/infrastructure/deployment-targets/cloud-regions)
+
+Next, let’s [deploy a sample package](/docs/getting-started/first-deployment/deploy-a-package) to your deployment target.
 
 ### All guides in this tutorial series
 
@@ -24,5 +74,6 @@ The next step will [deploy a sample package](/docs/getting-started/first-deploym
 ### Further reading for deployment targets
 
 - [Deployment Targets](/docs/infrastructure/deployment-targets)
-- [Deployment Documentation](/docs/deployments)
+- [Targets Tags](/docs/infrastructure/deployment-targets/target-tags)
+- [Deployments](/docs/deployments)
 - [Patterns and Practices](/docs/deployments/patterns)

src/pages/docs/getting-started/first-deployment/approvals-with-manual-interventions.md

@@ -1,45 +1,73 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2023-01-01
+modDate: 2025-01-07
 title: Approvals with Manual Interventions
 description: Step by step guide on how to use Manual Interventions in Octopus Deploy for approvals
 navOrder: 60
 hideInThisSection: true
 ---
 
-[Getting Started - Manual Intervention](https://www.youtube.com/watch?v=ePQjCClGfZQ)
+The **Manual Intervention Required** step lets you add approvals or manual checks to your deployment process. When manual intervention occurs, the deployment will pause and wait for approval or rejection from a member of a nominated responsible team.
 
-The manual intervention step accomplishes approvals in Octopus Deploy.  A deployment will pause when a manual intervention step is encountered and wait for approval or a rejection from a member of the specified team.
+## Add manual intervention step
 
-1. From the *Hello world* project you created earlier, click on **Process** on the left menu.
-1. Click **ADD STEP**.
-1. Select the **Other** tile to filter the types of steps.
-1. Scroll down and click **ADD** on the **Manual Intervention Required** tile.
-1. Accept the default name for the script and leave the **Enabled** check-box ticked.
-1. Leave the **Container Image** set on the default.
-1. Enter "Please verify the Production environment is ready before proceeding" in the **Instructions**.
-1. Select "Octopus Administrators" and "Octopus Managers" as **Responsible Teams**
-1. Select "Run only for specific environments" and select *Production* in the **Environments** conditions.
-1. Click the **SAVE** button.
+1. From the *Hello world deployment* project you created earlier, click **Process** in the left menu.
+2. Click **Add Step**.
+3. Select the **Other** category to filter the types of steps.
+4. Locate the Manual Intervention Required card and click **Add Step**.
 
-Right now, the step is configured to execute after the hello world script runs.  It makes much more sense for the approval to come before any other step.
+:::figure
+![Add Manual Intervention Required step to deployment process](/docs/getting-started/first-deployment/images/manual-intervention-step.png)
+:::
+
+### Step name
+
+You can leave this as the default *Manual Intervention Required*.
+
+### Instructions
+
+5. Copy the message below and paste it into the **Instructions** field.
+
+```
+Please verify the Production environment is ready before proceeding.
+```
+
+### Responsible Teams
 
-1. Click on the overflow menu next to the **Filter by name** text box, and select **Reorder Steps**
-1. Reorder the steps, so the manual intervention is the first one on the list.
-1. Click on **DONE** and then click on **SAVE**.
+6. Select **Octopus Administrators** and **Octopus Managers** from the **Responsible Teams** dropdown list.
+
+### Environments
+
+7. Select **Run only for specific environments**.
+8. Select **Production** from the **Environments** dropdown list.
+
+You can skip the other sections of this page for this tutorial.
+
+## Reorder deployment steps
+
+Currently, your deployment process will run manual intervention after the script step. In a real deployment scenario, it makes more sense to run manual intervention before any other step.
+
+1. Click the overflow menu **⋮** next to the **Filter by name** search box and click **Reorder Steps**.
+2. Reorder the steps so manual intervention is at the top of the list.
+3. Click **Done**.
+4. **Save** your deployment process.
 
 :::figure
-![Reorder steps](/docs/getting-started/first-deployment/images/img-reordersteps.png)
+![Reorder steps](/docs/getting-started/first-deployment/images/reorder-steps.png)
 :::
 
-Please create a new release and deploy it through to **Production**.  You will see the approval step being skipped in *Development* and *Testing*.  When you deploy to **Production**, the deployment will pause, and you will need to approve it before continuing.
+## Release and deploy
+
+1. Create a new release and deploy it through to the Production environment.
+
+You will notice manual intervention doesn’t run in the Development or Staging environments. When the deployment reaches Production, it will pause and request approval.
 
 :::figure
-![Manual intervention is required in production](/docs/getting-started/first-deployment/images/img-manualintervention.png)
+![Manual intervention is required in production](/docs/getting-started/first-deployment/images/manual-intervention.png)
 :::
 
-The next step will [add deployment targets](/docs/getting-started/first-deployment/add-deployment-targets).
+Your project is coming together well! Next, let's add a [deployment target](/docs/getting-started/first-deployment/add-deployment-targets).
 
 ### All guides in this tutorial series
 
@@ -52,5 +80,5 @@ The next step will [add deployment targets](/docs/getting-started/first-deployme
 ### Further reading for approvals
 
 - [Manual Intervention and Approvals](/docs/projects/built-in-step-templates/manual-intervention-and-approvals)
-- [Deployment Documentation](/docs/deployments)
+- [Deployments](/docs/deployments)
 - [Patterns and Practices](/docs/deployments/patterns)

src/pages/docs/getting-started/first-deployment/define-and-use-variables.md

@@ -8,8 +8,6 @@ navOrder: 50
 hideInThisSection: true
 ---
 
-[Getting Started - Variables](https://www.youtube.com/watch?v=Hd71uhcD61E)
-
 Octopus lets you define variables and scope them for use in different phases of your deployments. Variables allow you to have a consistent deployment process across your infrastructure without having to hard-code or manually update configuration settings that differ across environments, deployment targets, channels, or tenants.
 
 ## Add a variable
@@ -88,6 +86,6 @@ Great job! Next, let's build on your deployment process and [add an approval pro
 
 ### Further reading for variables
 
-- [Variable Documentation](/docs/projects/variables)
-- [Deployment Documentation](/docs/deployments)
+- [Variables](/docs/projects/variables)
+- [Deployments](/docs/deployments)
 - [Patterns and Practices](/docs/deployments/patterns)

src/pages/docs/getting-started/first-deployment/deploy-a-package.md

@@ -1,59 +1,94 @@
 ---
 layout: src/layouts/Default.astro
 pubDate: 2023-01-01
-modDate: 2024-04-19
+modDate: 2025-01-7
 title: Deploy a sample package
 description: Step by step guide on how to deploy a sample package Octopus Deploy
 navOrder: 80
 hideInThisSection: true
 ---
 
-Octopus Deploy's primary purpose is to push software packages, .zip, .jar, .war, .tar, .nupkg, etc., to your deployment targets.  Octopus Deploy requires all your assets, binaries, configuration files, CSS files, and more to run your application to be packaged up.  Typically this is done by your build server.
+Deploying software with Octopus often involves deploying packages, for example, `.zip`, `.nupkg`, `.jar`, `.tar`, etc. In this section, we'll walk you through the steps to deploy a sample hello world package to your deployment target.
 
-Packages must have the following attributes:
+:::div{.hint}
+To learn about supported formats, versioning, and packaging applications, refer to the [packaging documentation](/docs/packaging-applications).
+:::
+
+## Before your start
+
+Please download our sample package:
+
+- [hello-world.1.0.0.zip](https://octopus.com/images/docs/hello-world.1.0.0.zip)
+
+## Upload package
+
+1. From the left Deploy menu, click **Packages**.
+
+:::figure
+![Packages page](/docs/getting-started/first-deployment/images/packages-page.png)
+:::
+
+2. Click **Upload Package**.
+3. Select the package you want to upload.
+
+
+## Add deploy package step
 
-- Package ID. i.e., `hello-world`.
-- Version number, i.e., `1.0.0`. 
-- Package format, i.e., `.zip`.
+Add a step to the deployment process to push that package to your deployment target.
 
-:::div{.success}
-To learn more about supported formats, versioning, and packaging applications, refer to the [packaging documentation](/docs/packaging-applications).
+1. From the left Deploy menu, click **Projects**.
+2. Select the **Hello world deployment** project.
+3. Click **Process** in the left menu.
+4. Click **Add Step**.
+5. Select the **Package** category to filter the types of steps.
+6. Locate the Deploy a Package card and click **Add Step**.
+
+:::figure
+![Add Deploy a Package step to deployment process](/docs/getting-started/first-deployment/images/deploy-package-step.png)
 :::
 
-The following is a sample package that could be deployed with Octopus Deploy:
+### Step name
+
+You can leave this as the default *Deploy a Package*.
+
+### Target tags
+
+7. Select **tutorial-target** from the **Target Tags** dropdown list.
+
+:::div{.hint}
+**Context for target tags**
 
-> [hello-world.1.0.0.zip](https://octopus.com/images/docs/hello-world.1.0.0.zip)
+When configuring your deployment process, you can click a target tag to see the deployment targets and environments the step will run on.
 
-You can manually upload that package to the Octopus built-in repository in the Octopus Web Portal.
+:::figure
+![Target tags popover that shows correlating deployment targets](/docs/getting-started/first-deployment/images/target-tags-popover.png)
+:::
+
+### Package
 
-1. Navigating to the **Library** tab.
-1. Click **UPLOAD PACKAGE**.
-1. Select the package you want to upload and click **UPLOAD**.
+8. Select **hello-world** from the **Package ID** dropdown list.
 
-Add a step to the hello world deployment process to push that package to the desired deployment target.
+You can skip the other sections of this page for this tutorial.
 
-1. Click the **Projects** link in the top menu.
-1. Select the **Hello World** project.
-1. Click the **Process** link in the left menu.
-1. Click the **ADD STEP** button.
-1. Select the **Package** tile.
-1. Click **ADD** on the **Deploy a Package** tile.
-1. Leave the **Step Name** and the **Enabled** check-box as is.
-1. Select *hello-world* as the tag in **Target Tags**.
-1. Select *hello-world* as the **Package ID**.
-1. Click the **SAVE** button.
+**Save** your deployment process and you can move on to create and deploy a release.
 
 :::figure
-![Deploy a package step with target tag and package selected](/docs/getting-started/first-deployment/images/img-deploypackage.png)
+![Deploy a package step with target tag and package selected](/docs/getting-started/first-deployment/images/deploy-package-step-form.png)
 :::
 
-Please create a new release and deploy it to *Development*.  The release will deploy the *hello world* package to *dev-server-01*.
+## Release and deploy
+
+1. Create a new release and deploy it to the Development environment.
+
+The release will deploy the *hello world* package to the *Hello world tutorial target*.
 
 :::figure
-![Deploy a package results](/docs/getting-started/first-deployment/images/img-releasehwpackage.png)
+![Task log of deploying a package to the Hello world tutorial target](/docs/getting-started/first-deployment/images/deploy-package-task-log.png)
 :::
 
-You have now completed the deployment tutorial!  This tutorial has focused on running sample scripts and deploying sample packages to your servers.  It is now time to add your applications to Octopus Deploy.  
+You completed the first deployment tutorial, well done! 🎉  
+
+In this series you built a multi-step deployment process, used scoped variables, and deployed a sample package to a deployment target. It's now time to add your applications to Octopus Deploy.
 
 ### All guides in this tutorial series
 
@@ -65,7 +100,7 @@ You have now completed the deployment tutorial!  This tutorial has focused on ru
 
 ### Further reading for deploying packages and integrating your CI/CD pipeline
 
-- [Deployment Process Documentation](/docs/projects/deployment-process)
-- [Deployment Documentation](/docs/deployments)
+- [Packaging Applications](/docs/packaging-applications)
+- [Deployment Processes](/docs/projects/deployment-process)
+- [Deployments](/docs/deployments)
 - [Patterns and Practices](/docs/deployments/patterns)
-- [Customizable End to End CI/CD Tutorials](https://octopus.com/docs/guides)

src/pages/docs/getting-started/first-deployment/index.mdx

@@ -73,7 +73,7 @@ Octopus lands you in the process step template library.
 2. In the **Featured** category, locate the Run a Script card and click **Add Step**.
 
 :::figure
-![Featured step templates](/docs/getting-started/first-deployment/images/add-step.png)
+![Add Run a Script step to deployment process](/docs/getting-started/first-deployment/images/run-script-step.png)
 :::
 
 ### Step Name
@@ -157,6 +157,15 @@ You successfully completed your first deployment! 🎉
 
 Up next, we’ll introduce you to the [power of variables](/docs/getting-started/first-deployment/define-and-use-variables).
 
+:::div{.hint}
+**⭐ Favoriting projects**
+
+To easily navigate back to a project, you can mark it as a favorite by clicking the star icon next to the project name. Favorited projects will appear in the Deploy menu.
+
+:::figure
+![How to favorite a project](/docs/getting-started/first-deployment/images/add-favourite-project.png)
+:::
+
 ### All guides in this tutorial series
 
 1. First deployment (this page)