Octopus Deploy Documentation

Getting Started

Last updated

This Getting Started series walks you through a simple deployment with Octopus Deploy and explains the Octopus Deploy fundamentals so that you can take on more complicated deployments by the end of the series.

1. Hosting the Octopus Deploy Server

The first thing to decide is where to host your Octopus Deploy server. You can install your own self-hosted instance or use Octopus Cloud which is hosted and maintained by Octopus Deploy.

Installing the Self-hosted Octopus Deploy Server

  1. Download the installer from Resources ➜ Downloads
  2. Run the installer on your machine and follow the installation instructions.
  3. Once installed, click Get started... and follow the installer wizard to set up your instance.
  4. Click Install.

Create a Cloud Instance

  1. Create an account by clicking Start free trial at octopus.com/trial
  2. From the instances screen, click Create cloud instance and follow the set up instructions.
  3. Confirm the details you've provided, agree to the terms and click Looks good. Deploy my Octopus!.

2. Configure your Deployment Environments

Octopus needs to connect to the Infrastructure you'll be using to deploy your software. You can deploy to Windows servers, Linux servers, Microsoft Azure, an Offline Package Drop, Cloud Regions, or Kubernetes. These are known as your deployment targets, and they are organized into environments so you can promote your software through your deployment pipeline, for instance, from Development to Test and finally into Production.

Creating Environments

  1. Navigate to Infrastructure ➜ Environments and click ADD ENVIRONMENT.
  2. Give your new environment a meaningful name. We recommend creating environments called Development, Test, and Production.
  3. Click SAVE.

Creating Deployment Targets

  1. Navigate to Infrastructure ➜ Deployment Targets and click ADD DEPLOYMENT TARGET.
  2. Choose the type of Deployment Target you want to set up and follow these instructions for your target type.

Learn More

Environments and Deployment Targets
Deployment targets represent the servers, machines, and cloud services where your software and services will be deployed. Octopus organizes your deployment targets into groups called environments so you can promote your software through your deployment pipeline. For instance, from Development to Test and finally into Production.

Target Roles
Target roles allow you to “tag” deployment targets with a specific keyword which can be used in your deployments.

Tentacle Agent
When you deploy to servers, running either Windows, Linux, or Mac, you need to install the Tentacle Agent, a lightweight agent service, on your servers so they can communicate with the Octopus server in either listening or polling mode. A Tentacle Agent isn't required for deploying to Azure Web Apps, Kubernetes clusters, Azure Service Fabric, or Azure Cloud Service targets.

Lifecycles give you control over the way releases are promoted between environments.

3. Package and Upload Your Software

Before you can deploy software with Octopus Deploy, you need to bundle all the files required for the software to run into a supported package. The package must be versioned and stored in a repository. Octopus Deploy includes a built-in repository and supports external package feeds.

Packaging Software

  1. Give your package a package ID.
  2. Choose and apply a versioning scheme.
  3. Create the package in a supported format.

Uploading a Package

  1. Navigate to Library ➜ Packages and click UPLOAD PACKAGE.
  2. Select your package and click SAVE.

New to Octopus and don’t have a package?

Use our example package to quickly create your first deployment. hello-world.1.0.0.zip

Learn More

Packaging Your Applications
A package is an archive (zip, tar, NuGet) that contains all the files needed to run your software. You can host packages in external repositories or the built-in Octopus repository.

There are many more tools you might choose to use to create your package, but as long as you can create one of our supported packages you can deploy your applications with Octopus Deploy.

Build Server Integration
Most Octopus users automate their existing tool chain to push packages to their Octopus Deploy server with our build server integrations. But you can manually upload the package or host it in an external repository.

4. Define Your Deployment Process

Octopus Deploy is designed to work with teams following agile software development methodologies, that is, continuously deploying software, iterating, making changes, and redeploying. Before you can deploy, you need to create a project with your deployment process. The deployment process contains all the information needed to have your teams successfully deploy every time.

Create a Project

  1. Select Projects from the main navigation, and click ADD PROJECT.
  2. Give the project a name and add a description.
  3. If you want to change the project group select the project group from the dropdown menu.
  4. If you want to change the lifecycle select the lifecycle from the dropdown menu.
  5. Click SAVE and you will be taken to the newly created project's overview page.

Setting up Variables

  1. From your new project's overview page, click Variables.
  2. Give the variable a name, for instance, Greeting.
  3. Enter the first value for the variable, for instance, Hello, Test, in the value field.
  4. Define the scope for the value, for instance, by selecting the Test environment.
  5. Click ADD ANOTHER VALUE and enter the second value for the variable, for instance, Hello, Production.
  6. Define the scope for this value, for instance, by selecting the Production environment.
  7. Save the variable by clicking SAVE.

Define the Deployment Process

  1. From your new Project's Overview page, click DEFINE YOUR DEPLOYMENT PROCESS and click ADD STEP.
  2. To create a simple step for your first deployment select the Run a Script step.
  3. Give the step a name, for instance, Say Hello.
  4. For the execution Location, leave the selection at the default Deployment targets and select a target role.
  5. For the script section, paste the following PowerShell script into the Inline Source Code text box: ​ Write-Host
  6. Select the variable Greeting from the insert variable tool (#{}) next to the script editor, and click SAVE.

Learn More

Projects let you manage multiple software projects from the Octopus Web Portal. For each project you have, you define a deployment process, configuration variables, and the environments the software will be deployed to.

Deployment Process
The deployment process is a series of steps, each step contains a specific action (or set of actions) that is executed as part of the deployment process every time your software is deployed.

Octopus lets you define variables for configuration values that change, so you can have a different value for each environment or deployment target. For example you might have different values for database connection strings, emails, or passwords.

5. Deploy your Release

Once you have access to an Octopus server, your infrastructure is configured, your applications packaged, and the deployment process defined, you're ready to start deploying your software.

Creating a Release

  1. With your deployment process defined, you can create a release on the project's overview page, by clicking CREATE RELEASE.
  2. Give the release a version number, add any release notes you'd like to include, and click SAVE.

Deploying a Release

  1. Select the release you want to deploy.
  2. Click DEPLOY TO... or DEPLOY TO (Environment).
  3. If you selected DEPLOY TO..., select the environment to be deployed to.
  4. Click DEPLOY.

Learn More

Creating a Release
A Release is a snapshot of your deployment process, configuration variables, and software packages. Releases are created from projects and deployed via a lifecycle to your environments.

Deploying Releases
When you deploy a release, you are executing the deployment process with all the associated details, as they existed when the release was created. You can deploy a release as many times as you want to.


Welcome! We use cookies and data about how you use our website allow us to improve the website and your experience, and resolve technical errors. Our website uses cookies and shares some of your data with third party analytics companies for these purposes.

If you decline, we will respect your privacy. A single cookie will be used in your browser to remember your preference.