Octopus Server Linux Container

Running Octopus Server inside a container lets you avoid installing Octopus directly on top of your infrastructure and makes getting up and running with Octopus as simple as a one line command. Upgrading to the latest version of Octopus is just a matter of running a new container with the new image version.

We are confident in the Octopus Server Linux Container’s reliability and performance. Octopus Cloud runs the Octopus Server Linux Container in AKS clusters in Azure. But to use the Octopus Server Linux Container in Octopus Cloud, we had to make some design decisions and level up our knowledge about Docker concepts.

We recommend the use of the Octopus Server Linux Container if you are okay with all of these conditions:

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 itself.
You understand Octopus Deploy is a stateful, not a stateless application, requiring additional monitoring.

We publish linux/amd64 Docker images for each Octopus Server release and they are available on DockerHub.

Introducing the Octopus Server Linux Docker image

This page describes how to run Octopus Server in the Linux Container.

Note: When using Linux containers on a Windows machine, please ensure you have switched to Linux Containers.

Getting started

Although there are a few different configuration options, the following is a simple example of starting the Octopus Server Linux container:

$ docker run --interactive --detach --name OctopusDeploy --publish 1322:8080 --env ACCEPT_EULA="Y" --env DB_CONNECTION_STRING="..." octopusdeploy/octopusdeploy

We run in detached mode with --detach to allow the container to run in the background.
The --interactive argument ensures that STDIN is kept open which is required since internally this is what the running Octopus.Server.exe process is waiting on to close.
Setting --name OctopusServer gives us an easy to remember name for this container. This is optional, but we recommend you provide a name that is meaningful to you, as that will make it easier to perform actions on the container later if necessary.
Using --publish 1322:8080 maps the container port 8080 to 1322 on the host so that the Octopus instance is accessible outside this sever.
To set the connection string we provide an environment variable DB_CONNECTION_STRING (this can be to a local database or an external database).

In this example, we run the image octopusdeploy/octopusdeploy without an explicit tag, running the latest version of Octopus Server that’s been published to DockerHub.

Running Octopus Server in a Container

This section walks through some of the different ways you can run the Octopus Server Linux Container, from docker compose to using a full orchestration service such as Kubernetes:

Migration

You may already have an existing Octopus Server running on Windows Server or running in a Windows container that you wish to run in a Linux Container. This section walks through the different options and considerations for migration to the Octopus Server Linux Container.

Configuration

Support for authentication providers differs depending on how you host Octopus Server. Please see our authentication provider compatibility section to ensure any existing authentication provider is supported when running Octopus in a Linux Container.

When running an Octopus Server Image, the following values can be provided to configure the running Octopus Server instance.

Master Key

If you do not specify a master key when Octopus is first run, Octopus will generate one for you, which you then must pass as the MASTER_KEY environment variable with each subsequent run. However, it is also possible to generate your own master key which is used by Octopus when configuring the database.

Master keys must be a 128 bit string that is then base 64 encoded. You can generate a random string to use as the master key with the command:

openssl rand 16 | base64

Environment variables

Read the Docker docs about setting environment variables.

Name
DB_CONNECTION_STRING	Connection string to the database to use
MASTER_KEY	The Master Key to use to connect to an existing database. If not supplied, and the database does not exist, it will generate a new one. The Master Key is mandatory if the database exists.
OCTOPUS_SERVER_BASE64_LICENSE	Your license key for Octopus Deploy. If left empty, it will try and create a free license key for use
ADMIN_USERNAME	The admin user to create for the Octopus Server
ADMIN_PASSWORD	The password for the admin user for the Octopus Server
ADMIN_EMAIL	The email associated with the admin user account
TASK_CAP	Sets the task cap for this node. If not specified the default is 5.
DISABLE_DIND	The Linux image will by default attempt to run Docker-in-Docker to support execution containers for workers. This requires the image be launched with privileged permissions. Setting `DISABLE_DIND` to `Y` prevents Docker-in-Docker from being run when the container is booted.

Exposed container ports

Read Docker docs about exposing ports.

Port
8080	Port for API and HTTP portal
443	SSL Port for API and HTTP portal
10943	Port for Polling Tentacles to contact the server

Volume mounts

Read the Docker docs about mounting volumes.

Name	Description	Mount source
/import	Imports from this folder if Octopus Migrator metadata.json exists then migrator `Import` takes place on startup	Host filesystem or container
/repository	Package path for the built-in package repository	Shared storage
/artifacts	Path where artifacts are stored	Shared storage
/taskLogs	Path where task logs are stored	Shared storage
/eventExports	Path where event audit logs are exported	Shared storage
/cache	Path where cached files e.g. signature and delta files (used for package acquisition) are stored	Host filesystem or container

Note: We recommend using shared storage when mounting the volumes for files that need to be shared between multiple octopus container nodes, e.g. artifacts, packages, task logs, and event exports.

Upgrading

When the volumes are externally mounted to the host filesystem, upgrades between Octopus versions are much easier. We can picture the upgrade process with a container as being similar to moving a standard Octopus Server since containers, being immutable, don’t themselves get updated.

Similar to moving an instance, to perform the container upgrade you will need the Master Key that was used to set up the original database. The Master Key for an Octopus Server in a container can be found by using the container exec command:

> docker container exec <container name/ID> /Octopus/Octopus.Server show-master-key --console --instance OctopusServer

5qJcW9E6B99teMmrOzaYNA==

When you have the Master Key, you can stop the running Octopus Server container instance (delete it if you plan on using the same name), and run almost the same command as before, but this time, pass in the Master Key as an environment variable and reference the new Octopus Server version. When this new container starts up, it will use the same credentials and detect that the database has already been set up and use the Master Key to access its sensitive values:

$ docker run --interactive --detach --name OctopusServer --publish 1322:8080 --env DB_CONNECTION_STRING="..." --env MASTER_KEY "5qJcW9E6B99teMmrOzaYNA==" octopusdeploy/octopusdeploy

The standard backup and restore procedures for the data stored on the filesystem and the connected SQL Server still apply as per normal Octopus installations.

Troubleshooting

If you’re running into issues with the Octopus Server Linux Container then please use our Troubleshooting guide.

Learn more

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 4, 2023

Edit on GitHub