Upgrading a Server Installation

today • 3 min read

Server v2.x Server Admin

CircleCI Server version 2.x is no longer a supported release. Please consult your account team for help in upgrading to a supported release.

This document describes the process for upgrading your CircleCI Server installation to v2.19.

Nomad Launch Configuration
Org Rename Script
Upgrade Steps Overview

Nomad Launch Configuration

Before upgrading to v2.19, follow this guide to update your nomad launch configuration.

Org Rename Script

If upgrading directly from v2.17 (or below) and you have ever had issues with renaming an organization within CircleCI or you suspect that an organization rename might have happened at any point follow the steps below. If you are running Server v2.18.x already you can skip this section.

SSH into your Services machine
REPL into workflows-conductor by running the following: sudo docker exec -it workflows-conductor lein repl :connect 6005
Go to this link for the org rename script. Copy/paste this script into the REPL session. It will run migration and output current progress.
If any ERROR messages are present in the output please report back to your CSM or reach out to support.

Upgrade Steps Overview

Follow these steps to upgrade your CircleCI Server version.

1. Snapshot for Rollback

This step is optional but recommended

To take a snapshot of your installation:

Go to the Management Console (e.g. your-circleci-hostname.com:8800) and click Stop Now to stop the CircleCI service.

Figure 1. Stop CircleCI
Ensure no jobs are running on the nomad clients – you can check this by running nomad status
Navigate to the AWS EC2 management console and select your Services machine instance
Select Actions > Image > Create Image – Select the No Reboot option if you want to avoid downtime at this point. This image creation step creates an AMI that can be readily launched as a new EC2 instance to restore your installation.

Figure 2. Snapshot Image Creation

It is also possible to automate this process with the AWS API. Subsequent AMIs/snapshots are only as large as the difference (changed blocks) since the last snapshot, such that storage costs are not necessarily larger for more frequent snapshots, see Amazon’s EBS snapshot billing document for details. Once you have the snapshot you are free to make changes on the Services machine.

If you do need to rollback at any point, see our guide to restoring from a backup.

2. Updating Replicated

a. Prerequisites

Your installation is Ubuntu 14.04 or 16.04 based.
Your installation is not airgapped and you can access the internet from it.
We will be updating to Replicated v2.38.6, but first we need to check you are running at least v2.10.3 on your Services machine. To check this, SSH into the Services machine and run the following:
```
replicated --version
```
If you are running a version of Replicated pre v2.10.3 please reach out to support@circleci.com. If you are already on v2.38.6 or above you can skip the next step and move to upgrade the CircleCI application

b. Preparations

Remember to take a snapshot (described above) before starting the Replicated update process

Stop the CircleCI application by clicking the Stop Now button on the Dashboard. Application shutdown takes a few minutes. Wait for the status to become “Stopped” before continuing.

Figure 3. Stop the CircleCI Application

Alternatively you can SSH into the Services machine and stop the CircleCI application from the command line:
```
replicatedctl app stop
```
You can check the status using the followng:
```
replicatedctl app status inspect
```
Example Output:
```
[
    {
        "AppID": "edd9471be0bc4ea04dfca94718ddf621",
        "Sequence": 2439,
        "State": "stopped",
        "DesiredState": "stopped",
        "Error": "",
        "IsCancellable": false,
        "IsTransitioning": false,
        "LastModifiedAt": "2018-10-23T22:00:21.314987894Z"
    }
]
```
For the replicated update to succeed, it is necessary to update docker to the recommended version, 17.12.1. Check which version you are running with docker version and if you need to update, follow these steps:
```
sudo apt-get install docker-ce=17.12.1~ce-0~ubuntu
```
Pin the Docker version using the following command:
```
sudo apt-mark hold docker-ce
```

c. Perform Update

Perform the Replicated update by executing the update script as follows:

curl -sSL "https://get.replicated.com/docker?replicated_tag=2.38.6" | sudo bash

Double-check your replicated and docker versions:

replicatedctl version    # 2.38.6
docker -v                # 17.12.1

Restart the app with

replicatedctl app start

The application will take a few minutes to spin up. You can check the progress in the administration dashboard or by executing;

replicatedctl app status inspect

Example output:

[
    {
        "AppID": "edd9471be0bc4ea04dfca94718ddf621",
        "Sequence": 2439,
        "State": "started",
        "DesiredState": "started",
        "Error": "",
        "IsCancellable": true,
        "IsTransitioning": true,
        "LastModifiedAt": "2018-10-23T22:04:05.00374451Z"
    }
]

3. Upgrade CircleCI Server

Once you are running the latest version of Replicated, click the View Update button in the Management Console dashboard.

Figure 4. View Available Updates
Click Install next to the version you wish to install.

Please refresh your screen intermittently during the install process to avoid unnecessary waiting.

Figure 5. View Available Releases

The install process may take several minutes and the install status will be displayed both on the Releases page and the main Dashboard.
Once the installation is finished, navigate to the Dashboard to start your installation - Note the middle box on the Dashboard will read "CircleCI is up to date" when you are running the latest version.

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Suggest an edit to this page (please read the contributing guide first).
To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.