Introduction to Octopus Deploy on Windows Server 2022

Octopus Deploy is a best-of-breed deployment automation server designed specifically for the challenges of continuous delivery. While CI tools like Jenkins, TeamCity, and GitHub Actions excel at building and testing software, Octopus Deploy specializes in the deployment side: managing environments (Dev, Test, Staging, Production), orchestrating release lifecycles, tracking what version of every application is deployed where, and providing auditable deployment history. On Windows Server 2022, Octopus Server runs as a Windows service backed by a SQL Server database. This guide covers server installation, Tentacle configuration, environments and lifecycles, deployment steps for IIS, the Octopus CLI, and integration with common CI systems.

Prerequisites for Octopus Server on Windows Server 2022

Before installing Octopus Server, ensure the following are in place:

Windows Server 2022 Standard or Datacenter edition
SQL Server 2019 or 2022 (Express, Standard, or Enterprise) — Octopus requires a SQL Server database; it cannot use SQLite or other engines. SQL Server Express is sufficient for small teams.
At least 4 GB of RAM for a production instance; 2 GB for a small team/test instance
.NET 6 Runtime or later (the installer will prompt to install it if missing)
TCP port 8080 (HTTP) or 443 (HTTPS) open for the web UI and API
TCP port 10943 open if using Polling Tentacles (Tentacle initiates the connection to the server)

Create the Octopus SQL database in advance. Connect to SQL Server and run:

CREATE DATABASE OctopusDeploy
GO
CREATE LOGIN [OctopusDeployUser] WITH PASSWORD = 'StrongP@ssw0rd!'
GO
USE OctopusDeploy
GO
CREATE USER [OctopusDeployUser] FOR LOGIN [OctopusDeployUser]
GO
ALTER ROLE [db_owner] ADD MEMBER [OctopusDeployUser]
GO

Installing Octopus Server

Download the Octopus Server installer from https://octopus.com/downloads. The Windows installer (Octopus.x.y.z-x64.msi) provides a GUI installation wizard. For automated/unattended installation:

msiexec /i Octopus.2024.3.1-x64.msi /quiet /norestart RUNMANAGERONCOMPLETE=0

After the MSI installs, configure Octopus Server using the command-line manager. Open an elevated PowerShell window and run the configuration wizard:

cd "C:Program FilesOctopus DeployOctopus"

# Create the Octopus instance
.Octopus.Server.exe create-instance --instance="OctopusServer" --config="C:OctopusOctopusServer.config"

# Configure the database connection
.Octopus.Server.exe database --instance="OctopusServer" --connectionString="Server=.SQLEXPRESS;Database=OctopusDeploy;User Id=OctopusDeployUser;Password=StrongP@ssw0rd!;"

# Set the web portal URL and port
.Octopus.Server.exe configure --instance="OctopusServer" --webForceSSL=false --webListenPrefixes="http://localhost:8080/"

# Create the first administrator account
.Octopus.Server.exe admin --instance="OctopusServer" --username="admin" --email="[email protected]" --password="OctopusAdmin@123"

# Install and start as a Windows service
.Octopus.Server.exe service --instance="OctopusServer" --install --start

Verify the service is running:

Get-Service -Name "OctopusDeploy" | Select-Object Name, Status, StartType

Open a browser and navigate to http://localhost:8080 (or the server’s IP/hostname) to access the Octopus web portal.

Octopus Web UI Overview

After logging in, the Octopus web portal presents the main dashboard showing recent deployments and their status. The navigation is organized around the key concepts:

Projects — Your applications and their deployment processes
Environments — Dev, Test, Staging, Production, etc.
Infrastructure — Deployment targets (Tentacles, SSH connections, cloud targets)
Library — Packages (the built-in NuGet feed), step templates, variable sets, certificates
Releases — Snapshots of a project at a specific version, ready to deploy
Deployments — Instances of a release being deployed to an environment

Creating Environments and Lifecycles

Environments represent the stages your software passes through on the way to production. Create environments via the web UI under Infrastructure > Environments, or via the Octopus CLI:

octo create-environment --name="Development" --server="http://octopus:8080" --apiKey="API-YOURKEY"
octo create-environment --name="Staging"     --server="http://octopus:8080" --apiKey="API-YOURKEY"
octo create-environment --name="Production"  --server="http://octopus:8080" --apiKey="API-YOURKEY"

A Lifecycle defines the order environments must be deployed to and whether promotion between them is automatic or manual. Navigate to Library > Lifecycles and create a new lifecycle with phases for Development → Staging → Production, where Production requires manual promotion.

Installing the Octopus Tentacle on Target Servers

Octopus Tentacles are lightweight agents installed on the servers you want to deploy to. There are two communication modes:

Listening Tentacle — The Tentacle listens on TCP port 10933; Octopus Server initiates the connection. Requires port 10933 open inbound on the target server.
Polling Tentacle — The Tentacle initiates an outbound connection to Octopus Server on port 10943. Useful when the target server is behind a NAT or firewall that blocks inbound connections.

Download the Tentacle MSI from the Octopus downloads page and install silently:

msiexec /i Octopus.Tentacle.2024.3.1-x64.msi /quiet /norestart

Configure a Listening Tentacle from an elevated PowerShell prompt on the target server:

cd "C:Program FilesOctopus DeployTentacle"

.Tentacle.exe create-instance --instance="Tentacle" --config="C:OctopusTentacleTentacle.config"
.Tentacle.exe new-certificate --instance="Tentacle" --if-blank
.Tentacle.exe configure --instance="Tentacle" --reset-trust
.Tentacle.exe configure --instance="Tentacle" --app="C:OctopusApplications" --port=10933 --noListen=false
.Tentacle.exe configure --instance="Tentacle" --trust="THUMBPRINT_OF_OCTOPUS_SERVER_CERT"
.Tentacle.exe service --instance="Tentacle" --install --start

Get the Octopus Server certificate thumbprint from the web UI under Configuration > Thumbprint. After the Tentacle is running, register it with Octopus Server:

.Tentacle.exe register-with --instance="Tentacle" --server="http://octopus:8080" --apiKey="API-YOURKEY" --name="WebServer01" --env="Production" --role="web-server"

For a Polling Tentacle, add --noListen=true and --server-comms-port=10943 to the configure step, and register it the same way.

Configuring a Deployment Project and Process

In the Octopus web portal, create a new Project, assign it a lifecycle, and then define its deployment process. A deployment process is a sequence of steps that Octopus executes in order. Common step types include:

Deploy a Package — Extract a NuGet package to a directory
Deploy to IIS — Configure an IIS website or application from a package
Run a Script — Execute PowerShell, Bash, or C# script on the target
Send Slack Notification — Notify a Slack channel on deployment success/failure
Manual Intervention — Pause and require a human approval before proceeding

The Deploy to IIS Step

The Deploy to IIS step is the most commonly used step for Windows web deployments. It handles extracting the package, configuring IIS bindings, application pools, and virtual directories. In the Octopus web portal, add a new step to your project’s deployment process, select Deploy to IIS, and configure:

Package ID — The NuGet package ID from the built-in feed or an external feed
Website name — The IIS website to deploy to (created if it does not exist)
Application pool name — The application pool (created if it does not exist)
Bindings — HTTP/HTTPS bindings with port and optional hostname
Physical path — Where to extract the package on disk (e.g., C:inetpubmyapp)

Octopus performs a blue-green deployment by default: it extracts to a versioned folder, then swaps the IIS binding to point to the new version, minimizing downtime.

The Built-in NuGet Feed

Octopus Server includes a built-in NuGet-compatible package repository. Your CI system pushes build artifacts to this feed, and Octopus pulls from it during deployment. The feed URL is:

http://octopus-server:8080/nuget/packages

Push a package to the built-in feed using the NuGet CLI:

nuget push MyApp.1.2.3.nupkg -Source http://octopus-server:8080/nuget/packages -ApiKey API-YOURKEY

Or using the Octopus CLI:

octo push --package=MyApp.1.2.3.nupkg --server=http://octopus-server:8080 --apiKey=API-YOURKEY

Octopus CLI (octo.exe) Key Commands

The Octopus CLI (octo.exe) is the command-line interface for interacting with Octopus Server. It is available as a standalone executable and as a .NET global tool. Install it as a global tool:

dotnet tool install --global Octopus.DotNet.Cli

Create a release and deploy it:

# Create a release
octo create-release --project="MyWebApp" --version="1.2.3" --packageVersion="1.2.3" --server=http://octopus:8080 --apiKey=API-YOURKEY

# Deploy a release to an environment
octo deploy-release --project="MyWebApp" --version="1.2.3" --deployTo="Staging" --server=http://octopus:8080 --apiKey=API-YOURKEY --waitForDeployment --progress

# Deploy to Production after Staging succeeds
octo deploy-release --project="MyWebApp" --version="1.2.3" --deployTo="Production" --server=http://octopus:8080 --apiKey=API-YOURKEY --waitForDeployment

# List existing releases
octo list-releases --project="MyWebApp" --server=http://octopus:8080 --apiKey=API-YOURKEY

# List deployments
octo list-deployments --project="MyWebApp" --server=http://octopus:8080 --apiKey=API-YOURKEY

Channels and Versioning

Octopus Channels allow a single project to have multiple deployment paths for different release tracks — for example, a stable channel that deploys to all environments, and a hotfix channel that skips Development and Staging and deploys directly to Production. Channels also enforce version range rules using NuGet version range syntax:

Stable channel: [1.0,) — any version 1.0 or higher
Pre-release channel: -beta suffix required
Hotfix channel: requires tag hotfix

Integrating Octopus with Jenkins

Install the Octopus Deploy Jenkins plugin. After configuring the plugin with your Octopus Server URL and API key under Manage Jenkins > Configure System, use the Octopus steps in a Jenkinsfile:

pipeline {
    agent { label 'windows-server-2022' }

    stages {
        stage('Build') {
            steps {
                bat 'MSBuild.exe MySolution.sln /t:Build /p:Configuration=Release'
            }
        }
        stage('Package') {
            steps {
                bat 'octo pack --id=MyWebApp --version=1.0.%BUILD_NUMBER% --basePath=./publish --outFolder=./artifacts'
            }
        }
        stage('Push to Octopus') {
            steps {
                bat 'octo push --package=./artifacts/MyWebApp.1.0.%BUILD_NUMBER%.nupkg --server=http://octopus:8080 --apiKey=%OCTOPUS_API_KEY%'
            }
        }
        stage('Create Release') {
            steps {
                bat 'octo create-release --project=MyWebApp --version=1.0.%BUILD_NUMBER% --server=http://octopus:8080 --apiKey=%OCTOPUS_API_KEY%'
            }
        }
        stage('Deploy to Dev') {
            steps {
                bat 'octo deploy-release --project=MyWebApp --version=1.0.%BUILD_NUMBER% --deployTo=Development --server=http://octopus:8080 --apiKey=%OCTOPUS_API_KEY% --waitForDeployment'
            }
        }
    }
}

Integrating Octopus with GitHub Actions

Octopus provides official GitHub Actions in the GitHub Marketplace. A complete workflow that builds, packages, pushes, creates a release, and deploys:

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: windows-2022

    steps:
      - uses: actions/checkout@v4

      - name: Setup MSBuild
        uses: microsoft/setup-msbuild@v2

      - name: Build
        run: msbuild MySolution.sln /t:Restore;Publish /p:Configuration=Release /p:PublishUrl=./publish

      - name: Install Octopus CLI
        uses: OctopusDeploy/install-octopus-cli-action@v3
        with:
          version: "*"

      - name: Package application
        run: octo pack --id=MyWebApp --version=1.0.${{ github.run_number }} --basePath=./publish --outFolder=./artifacts

      - name: Push package to Octopus
        uses: OctopusDeploy/push-package-action@v3
        with:
          api_key: ${{ secrets.OCTOPUS_API_KEY }}
          server: ${{ secrets.OCTOPUS_SERVER }}
          packages: ./artifacts/MyWebApp.1.0.${{ github.run_number }}.nupkg

      - name: Create Octopus release
        uses: OctopusDeploy/create-release-action@v3
        with:
          api_key: ${{ secrets.OCTOPUS_API_KEY }}
          server: ${{ secrets.OCTOPUS_SERVER }}
          project: MyWebApp
          release_number: 1.0.${{ github.run_number }}

      - name: Deploy to Development
        uses: OctopusDeploy/deploy-release-action@v3
        with:
          api_key: ${{ secrets.OCTOPUS_API_KEY }}
          server: ${{ secrets.OCTOPUS_SERVER }}
          project: MyWebApp
          release_number: 1.0.${{ github.run_number }}
          environments: Development

Summary

Octopus Deploy on Windows Server 2022 delivers a purpose-built deployment automation platform that complements CI tools. The server installs as a Windows service backed by SQL Server, and its web UI provides clear visibility into what is deployed where across all environments. Tentacles — both Listening and Polling — provide flexible connectivity to target servers across network boundaries. The Deploy to IIS step handles blue-green ASP.NET deployments natively. The built-in NuGet feed, Octopus CLI, channels for release branching, and integrations with Jenkins, GitHub Actions, and TeamCity make Octopus the deployment hub that ties together every stage of a Windows-centric continuous delivery pipeline.

Links

Newsletter

Contact

How to Set Up Windows Server 2022 with Grafana