Skip to content

Made the fact we only support a version for six months clearer. #3002

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BobJWalker merged 5 commits into from
Jan 8, 2026
Merged

Made the fact we only support a version for six months clearer. #3002

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6a9cb7b
Made the fact we only support a version for six months clearer. Adde…
BobJWalker Jan 8, 2026
7941948
Clarifying it's a major.minor - not major.minor.patch
BobJWalker Jan 8, 2026
db12733
Markdown lint fun
BobJWalker Jan 8, 2026
df15d77
More markdown lint fun
BobJWalker Jan 8, 2026
aae7242
Yet even more markdown fun
BobJWalker Jan 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions src/pages/docs/administration/upgrading/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,19 +25,19 @@ Octopus Deploy connects to a SQL Server database, and can be hosted:
### Upgrade process

When running on Windows, the typical (manual) upgrade process is:

- Run the MSI to install the latest binaries.
- After the MSI finishes, it will close, and the **Octopus Manager** is launched to update each instance.

Once the **Octopus Manager** starts the upgrade process, downtime _will_ occur. The upgrade should take anywhere from a minute to 30 minutes to complete depending on the number of database changes, the database's size, and compute resources. A good rule of thumb is: the greater the delta between versions, the longer the downtime. An upgrade from 2019.2.1 to 2020.5.1 will generally take longer than an upgrade from 2020.4.1 to 2020.5.1.
Once the **Octopus Manager** starts the upgrade process, downtime *will* occur. The upgrade should take anywhere from a minute to 30 minutes to complete depending on the number of database changes, the database's size, and compute resources. A good rule of thumb is: the greater the delta between versions, the longer the downtime. An upgrade from 2019.2.1 to 2020.5.1 will generally take longer than an upgrade from 2020.4.1 to 2020.5.1.

:::div{.hint}
[Automating your upgrade process](/docs/administration/upgrading/guide/automate-upgrades) will help reduce the total upgrade time. Automation also mitigates risk, as all steps, including backups, will be followed. We've found companies who automate their upgrade process are much more likely to stay up to date. The smaller the delta between versions, the faster the upgrade.
:::

**Upgrades and the Service Watchdog**

If you are using the [Service Watchdog](/docs/administration/managing-infrastructure/service-watchdog), you will need to cancel it before you start your upgrade and recreate it after the upgrade is finished. Documentation on canceling the watchdog can be found [here](/docs/administration/managing-infrastructure/service-watchdog/#ServiceWatchdog-CancelingTheWatchdog).
#### Upgrades and the Service Watchdog

If you are using the [Service Watchdog](/docs/administration/managing-infrastructure/service-watchdog), you will need to cancel it before you start your upgrade and recreate it after the upgrade is finished. Please see [documentation on canceling the watchdog](/docs/administration/managing-infrastructure/service-watchdog/#ServiceWatchdog-CancelingTheWatchdog).

### Upgrading a highly available Octopus Deploy instance

Expand All @@ -60,10 +60,10 @@ The Windows Service is split across multiple folders to make upgrading easy and
- **Home Folder**: The home folder stores configuration, logs, and other items unique to your instance. The home folder is separate from the install location to make it easier to upgrade, downgrade, uninstall/reinstall without affecting your instance. The default location of the home folder is `C:\Octopus`. Except in rare cases, this folder is left unchanged by the upgrade process.
- **Instance Information**: The Octopus Deploy Manager allows you to configure 1 to N instances per Windows Server. The **Octopus Manager** stores a list of all the instances in the `C:\ProgramData\Octopus\OctopusServer\Instances` folder. Except in rare cases, this folder is left unchanged by the upgrade process.
- **Server Folders**: Logs, artifacts, packages, and event exports are too big for Octopus Deploy to store in a SQL Server database. The server folders are sub-folders in `C:\Octopus\`. Except in rare cases, these folders are left unchanged by an upgrade.
- **Tentacles**: Octopus Deploy connects to deployment targets via the Tentacle service. Each version of Octopus Deploy includes a specific Tentacle version. Tentacle upgrades do not occur until _after_ the Octopus Deploy server is upgraded. Tentacle upgrades are optional; any Tentacle greater than 4.x will work [with any modern version of Octopus Deploy](/docs/support/compatibility). We recommend you upgrade them to get the latest bug fixes and security patches when convenient.
- **Tentacles**: Octopus Deploy connects to deployment targets via the Tentacle service. Each version of Octopus Deploy includes a specific Tentacle version. Tentacle upgrades do not occur until *after* the Octopus Deploy server is upgraded. Tentacle upgrades are optional; any Tentacle greater than 4.x will work [with any modern version of Octopus Deploy](/docs/support/compatibility). We recommend you upgrade them to get the latest bug fixes and security patches when convenient.
- **Calamari**: The Tentacles facilitate communication between Octopus Deploy and the deployment targets. Calamari is the software that does the actual deployments. Calamari and Octopus Deploy are coupled together. Calamari is upgraded automatically during the first deployment to a target.

## Octopus Deploy Server release schedule
## Supported Octopus Deploy Server Versions

<OctopusReleases />

Expand Down
20 changes: 13 additions & 7 deletions src/pages/docs/best-practices/self-hosted-octopus/installation-guidelines.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ navOrder: 10
hideInThisSection: true
---
import OctopusInstanceMixedOSWarning from 'src/shared-content/administration/octopus-instance-mixed-os-warning.include.md'
import OctopusReleases from 'src/shared-content/installation/octopus-releases.include.md';

Octopus Deploy supports two hosting options:

Expand All @@ -22,6 +23,10 @@ There are three components to an Octopus Deploy instance:

This document will provide you with guidelines and recommendations for self-hosting Octopus Deploy.

## Supported Octopus Deploy Server Versions

<OctopusReleases />

## Host Octopus on Windows Server or as a Linux Container

Our recommendation is to host Octopus Deploy Windows Server over the Octopus Server Linux Container unless you are okay with **all** these conditions:
Expand All @@ -30,19 +35,20 @@ Our recommendation is to host Octopus Deploy Windows Server over the Octopus Ser
- You are okay running at least one [worker](/docs/infrastructure/workers) to handle tasks typically done by the Octopus Server. The Octopus Server Linux Container doesn't include PowerShell Core or Python.
- You are familiar with Docker concepts, specifically around debugging containers, volume mounting, and networking.
- You are comfortable with one of the underlying hosting technologies for Docker containers; Kubernetes, ACS, ECS, AKS, EKS, or Docker Swarm.
- You understand Octopus Deploy is a stateful, not a stateless application, requiring additional monitoring.
- You understand Octopus Deploy is a stateful, not a stateless application, requiring additional monitoring.

<OctopusInstanceMixedOSWarning />

We are confident in the Octopus Server Linux Container's reliability and performance. After all, Octopus Cloud runs on the Octopus Linux container in AKS clusters in Azure. For more information, please see [Octopus Server Linux Container](/docs/installation/octopus-server-linux-container).

## Create a single production instance

One question we get asked a lot is "should we have a single instance to deploy to all environments or have an Octopus Deploy instance per environment?" Unless there is a business requirement, our recommendation is to have a single instance to deploy to all environments and use Octopus Deploy's RBAC controls to manage permissions. We recommend this to avoid the maintenance overhead involved with having an instance per environment.
One question we get asked a lot is "should we have a single instance to deploy to all environments or have an Octopus Deploy instance per environment?" Unless there is a business requirement, our recommendation is to have a single instance to deploy to all environments and use Octopus Deploy's RBAC controls to manage permissions. We recommend this to avoid the maintenance overhead involved with having an instance per environment.

Of the customers who opt for an instance per environment, we see them have an instance for **development** and **test** environments with another instance for **staging** and **production** environments.
Of the customers who opt for an instance per environment, we see them have an instance for **development** and **test** environments with another instance for **staging** and **production** environments.

If you chose this instance configuration, you would need a process to:

- Clone all the variable sets and project variables, and notify you when a new scoped variable is added.
- Sync the deployment and runbook processes, but skip over steps assigned to **development** and **test**.
- Update any user step templates to the latest version.
Expand All @@ -55,15 +61,15 @@ Using the Octopus Deploy API, all of that is possible; however, it will require

## Run the Octopus Service, SQL server, and files on separate infrastructure

It is possible to run the Octopus Deploy service, SQL Server, and file storage on the same Windows Server or container orchestrator. That is not recommended for production instances of Octopus Deploy. Aside from having a single point of failure, it can lead to performance issues.
It is possible to run the Octopus Deploy service, SQL Server, and file storage on the same Windows Server or container orchestrator. That is not recommended for production instances of Octopus Deploy. Aside from having a single point of failure, it can lead to performance issues.

The database should run on a dedicated SQL Server, or using a managed SQL Server like AWS RDS, or Azure SQL. The files should be stored on a NAS, SAN, or on a managed file storage platform like Azure File Storage that supports SMB/CIFS. Shared services like these are managed by dedicated individuals, such as DBAs or Network Admins. They provide common day 2 maintenance such as backups, restoring, and performance monitoring.

While it is possible to run SQL Server in container, we do not recommend it for production use. Whenever possible use a managed SQL Server like AWS RDS or Azure SQL, or use a SQL Server already managed by DBAs.

## Use a load balancer for the Octopus Deploy UI

The Octopus Deploy UI is a stateless React single-page application that leverages a RESTful API for its data. We recommend using a load balancer for Octopus Deploy as soon as possible. This will make it much easier to move to high availability. In addition, it'll be easy to rebuild or change the underlying Windows Server or to move to Linux Containers in the future.
The Octopus Deploy UI is a stateless React single-page application that leverages a RESTful API for its data. We recommend using a load balancer for Octopus Deploy as soon as possible. This will make it much easier to move to high availability. In addition, it'll be easy to rebuild or change the underlying Windows Server or to move to Linux Containers in the future.

Any standard load balancer, be it F5, Netscaler, or provided via a cloud provider, will work. If you need a small load balancer, NGINX will provide all the functionality you’ll need.

Expand All @@ -89,7 +95,7 @@ The Octopus server will process additional tasks, such as applying retention pol

Use the following table below as a starting point for your compute resources. You are responsible for monitoring the resources consumed and ensuring your Octopus Deploy infrastructure isn't under or over-provisioned.

| Task Cap Per Node | Windows Compute Resources | Container Compute Resources | Database on Virtual Machines | Azure DTUs |
| Task Cap Per Node | Windows Compute Resources | Container Compute Resources | Database on Virtual Machines | Azure DTUs |
| ----------------- | ------------------------- | ---------------------------------- | ---------------------------- | ------------ |
| 5 - 10 | 2 Cores / 4 GB RAM | 150m - 1000m / 1500 Mi - 3000 Mi | 2 Cores / 4 GB RAM | 50 DTUs |
| 20 | 4 Cores / 8 GB RAM | 1000m - 2000m / 3000 Mi - 6000 Mi | 2 Cores / 8 GB RAM | 100 DTUs |
Expand All @@ -99,7 +105,7 @@ Use the following table below as a starting point for your compute resources. Yo

## Use High Availability at scale

While it is possible to configure a single-node instance to process 100+ deployments concurrently, it is not something we recommend. Once you go beyond 40 concurrent deployments, we recommend using Octopus Deploy's High Availability to scale horizontally. 40 to 80 concurrent deployments per Octopus Deploy node tends to the "sweet spot" for the maximum number of concurrent deployments.
While it is possible to configure a single-node instance to process 100+ deployments concurrently, it is not something we recommend. Once you go beyond 40 concurrent deployments, we recommend using Octopus Deploy's High Availability to scale horizontally. 40 to 80 concurrent deployments per Octopus Deploy node tends to the "sweet spot" for the maximum number of concurrent deployments.

Please see our [implementation guide for High Availability](/docs/best-practices/self-hosted-octopus/high-availability) for more details.

Expand Down
44 changes: 22 additions & 22 deletions src/pages/docs/installation/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ There are three components to an Octopus Deploy instance:
- **Files or BLOB Storage** Some larger files - like [packages](/docs/packaging-applications/package-repositories), artifacts, and deployment task logs - aren't suitable to be stored in the database and are stored on the file system instead. This can be a local folder, a network file share, or a cloud provider's storage.

All inbound traffic to Octopus Deploy is via:

- HTTP/HTTPS (ports 80/443)
- Polling tentacles (port 10943)
- gRPC (port 8443)
Expand All @@ -44,30 +45,34 @@ When installed, the self-hosted Octopus Server:

Before you install Octopus Deploy, review the software and hardware [requirements](/docs/installation/requirements/), and make sure you have access to an instance of [SQL Server Database](/docs/installation/sql-server-database) that you can use with Octopus Deploy.

## Supported Octopus Deploy Server Versions

<OctopusReleases />

## Install Octopus as a Windows Service \{#install-octopus}

1. [Download](https://Octopus.com/downloads/server) the Octopus installer.
1. Start the Octopus Installer, click **Next**, accept the **Terms in the License Agreement** and click **Next**.
1. Accept the default **Destination Folder** or choose a different location and click **Next**.
1. Click **Install**, and give the app permission to **make changes to your device**.
1. Click **Finish** to exit the installation wizard and launch the **Getting started wizard** to configure your Octopus Server.
1. Click **Get started...** and either enter your details to start a free trial of Octopus Deploy or enter your **license key** and click **Next**.
1. Accept the default **Home Directory** or enter a location of your choice and click **Next**.
1. Decide whether to use a **Local System Account** or a **Custom Domain Account**.
- [Download](https://Octopus.com/downloads/server) the Octopus installer.
- Start the Octopus Installer, click **Next**, accept the **Terms in the License Agreement** and click **Next**.
- Accept the default **Destination Folder** or choose a different location and click **Next**.
- Click **Install**, and give the app permission to **make changes to your device**.
- Click **Finish** to exit the installation wizard and launch the **Getting started wizard** to configure your Octopus Server.
- Click **Get started...** and either enter your details to start a free trial of Octopus Deploy or enter your **license key** and click **Next**.
- Accept the default **Home Directory** or enter a location of your choice and click **Next**.
- Decide whether to use a **Local System Account** or a **Custom Domain Account**.

Learn more about the [permissions required for the Octopus Windows Service](/docs/installation/permissions-for-the-octopus-windows-service/) or using a [Managed Service Account](/docs/installation/managed-service-account).

9. On the **Database** page, click the drop-down arrow in the **Server Name** field to detect the SQL Server Database. Octopus will create the database for you which is the recommended process; however, you can also [create your own database](/docs/installation/sql-server-database/#creating-the-database).
10. Enter a name for the database, and click **Next** and **OK** to **create the database**.
- On the **Database** page, click the drop-down arrow in the **Server Name** field to detect the SQL Server Database. Octopus will create the database for you which is the recommended process; however, you can also [create your own database](/docs/installation/sql-server-database/#creating-the-database).
- Enter a name for the database, and click **Next** and **OK** to **create the database**.

Be careful **not** to use the name of an existing database as the setup process will install Octopus into that pre-existing database.

11. Accept the default port and directory or enter your own and click **Next**.
12. If you're using **username and passwords stored in Octopus** authentication mode, enter the username and password that will be used for the Octopus administrator. If you are using [active directory](/docs/security/authentication/active-directory), enter the active directory user details.
- Accept the default port and directory or enter your own and click **Next**.
- If you're using **username and passwords stored in Octopus** authentication mode, enter the username and password that will be used for the Octopus administrator. If you are using [active directory](/docs/security/authentication/active-directory), enter the active directory user details.

You can configure additional [Authentication Providers](/docs/security/authentication) for the Octopus Server after the server has been installed.

12. Click **Install**.
- Click **Install**.

When the installation has completed, click **Finish** to launch the **Octopus Manager**.

Expand Down Expand Up @@ -109,14 +114,9 @@ Click **Open in browser** to launch the **Octopus Web Portal** and log in using

The **Octopus Web Portal** is where you'll manage your infrastructure, projects, deployment process, access the built-in repository, and manage your deployments and releases.

## Releases of Octopus Deploy Server

<OctopusReleases />

## Learn more

- [Troubleshooting the Octopus installation](/docs/installation/troubleshooting)
- [Configure your infrastructure](/docs/infrastructure)
- [Upgrading guide](/docs/administration/upgrading)
- [Automating Octopus installation](/docs/installation/automating-installation)

- [Troubleshooting the Octopus installation](/docs/installation/troubleshooting)
- [Configure your infrastructure](/docs/infrastructure)
- [Upgrading guide](/docs/administration/upgrading)
- [Automating Octopus installation](/docs/installation/automating-installation)
Loading