circleci · rosieyohannan · Dec 11, 2025 · Nov 4, 2025 · Nov 4, 2025 · Nov 4, 2025
@@ -14,6 +14,8 @@ content:
     start_path: docs/reference
   - url: .
     start_path: docs/orbs
+  - url: .
+    start_path: docs/server-admin-4.9
   - url: .
     start_path: docs/server-admin-4.8
   - url: .
@@ -49,7 +51,7 @@ asciidoc:
     serverversion46: 4.6.6
     serverversion47: 4.7.11
     serverversion48: 4.8.5
-    serverversion: 3.4.8
+    serverversion49: 4.9.0
     terraformversion: 0.15.4
     dockerversion: v28
     kubectlversion: 1.19

@@ -79,7 +79,7 @@ NOTE: During the installation process, you may use the following command to gene
 [#api-token]
 === a. API token
 
-The application requires a Kubernetes Secret containing an API token. This API token is used to facilitate internal API communication to the API service. Use a random string and store it securely. CircleCI will not be able to recover this value if lost. You have two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.
+The application requires a Kubernetes Secret containing an API token. This API token is used to facilitate internal API communication to `api-service`. Use a random string and store it securely. CircleCI will not be able to recover this value if lost. You have two options depending on whether you want to create the Kubernetes Secret, or if you want CircleCI to create it for you.
 
 [tabs]
 ====
@@ -188,7 +188,8 @@ keyset:
 
 [#postgres-credentials]
 ==== i. Credentials
-The application requires a Kubernetes Secret containing PostgreSQL credentials. This requirement applies when using either the internal (default) or an externally hosted instance of PostgreSQL. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets you have two options.
+
+The application requires a Kubernetes Secret containing PostgreSQL credentials. This Secret is required when using either the internal (default) or an externally hosted instance of PostgreSQL. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets there are two options.
 
 [tabs]
 ====
@@ -264,7 +265,7 @@ postgresql:
 
 === e. MongoDB credentials
 
-The application requires a Kubernetes Secret containing MongoDB credentials. This requirement applies when using either the internal (default) or an externally hosted instance of MongoDB. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets you have two options.
+The application requires a Kubernetes Secret containing MongoDB credentials. This Secret is required when using either the internal (default) or an externally hosted MongoDB instance. CircleCI will not be able to recover the values if lost. Based on how you prefer to manage Kubernetes Secrets, there are two options:
 
 [tabs]
 ====

@@ -1,4 +1,5 @@
 = Additional considerations
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: This page presents some items that should be considered when starting an air-gapped installation of CircleCI server v4.8.
 :experimental:

@@ -1,4 +1,5 @@
 = Example `values.yaml`
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: This page presents an example values.yaml file to help with setting up an air-gapped installation of CircleCI server v4.8.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 1 - Prerequisites
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :experimental:
 :page-description: A guide to installing CircleCI server v4.8 in an air-gapped environment. Requirements, images and Helm charts.

@@ -1,4 +1,5 @@
 = Phase 2 - Configure object storage
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: How to configure object storage through MinIO to run CircleCI server v4.8 in an air-gapped environment.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 3 - install CircleCI server
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: How to install the CircleCI server v4.8 Helm deployment to an air-gapped environment.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 4 - Configure Nomad clients
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: How to configure Nomad clients to run with CircleCI server v4.8 in an air-gapped environment.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 5 - Test your installation
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: How to test your CircleCI server v4.8 installation in an air-gapped environment.
 :experimental:

@@ -1,4 +1,5 @@
 = Hardening your cluster
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: This section provides supplemental information on hardening your Kubernetes cluster for CircleCI server v4.8.
 :experimental:

@@ -1,4 +1,5 @@
 = Installation reference
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Reference documentation for installing CircleCI server v4.8.
 :experimental:

@@ -1,4 +1,5 @@
 = Installing server behind a proxy
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Learn how to install CircleCI server v4.8 behind a proxy.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 1 AWS - Prerequisites
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Find the general and infrastructure-specific requirements that are needed in order to configure the CircleCI server v4.8 application.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 1 GCP - Prerequisites
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Find the general and infrastructure-specific requirements that are needed in order to configure the CircleCI server v4.8 application.
 :env-gcp:

@@ -1,4 +1,5 @@
 = Phase 2 AWS - core services
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Installation guide for CircleCI server v4.8 core services.
 :env-aws:

@@ -1,4 +1,5 @@
 = Phase 2 GCP - core services
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Installation guide for CircleCI server v4.8 core services.
 :env-gcp:

@@ -1,4 +1,5 @@
 = Phase 3 AWS - execution environments
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Installation guide for CircleCI server v4.8 execution environments.
 :env-aws:

@@ -1,4 +1,5 @@
 = Phase 3 GCP - execution environments
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Installation guide for CircleCI server v4.8 execution environments.
 :experimental:

@@ -1,4 +1,5 @@
 = Phase 4 AWS - post installation
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: CircleCI server v4.8 post installation steps.
 :env-aws:

@@ -1,4 +1,5 @@
 = Phase 4 GCP - post installation
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: CircleCI server v4.8 post installation steps.
 :env-gcp:

@@ -1,4 +1,5 @@
 = Upgrade server
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: "This document lists the steps required to upgrade a CircleCI server v4.8 installation."
 :experimental:
@@ -53,4 +54,4 @@ helm upgrade circleci-server oci://cciserver.azurecr.io/circleci-server -n $name
 
 . Deploy and run link:https://github.com/circleci/realitycheck[`reality check`] in your test environment to ensure your installation is fully operational.
 
-. Migrate any existing machine runner instances from the launch agent to the machine runner 3.0 agent, see the xref:guides:execution-runner:migrate-from-launch-agent-to-machine-runner-3-on-linux.adoc#[migration guide]. The launch agent is not supported.
+. Migrate any existing machine runner instances from the launch agent to the machine runner 3.0 agent, see the xref:guides:execution-runner:migrate-from-launch-agent-to-machine-runner-3-on-linux.adoc#[Migration Guide]. The launch agent is not supported.
@@ -1,4 +1,5 @@
 = Application lifecycle
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Learn about CircleCI server v4.8 semantic versioning and release schedules.
 :experimental:

@@ -1,15 +1,15 @@
 = Backup and restore
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: This document outlines recommendations for how to back up and restore your CircleCI server v4.8 instance data and state.
 :experimental:
 
 [#overview-backup]
 == Overview
 
-When operating and administering CircleCI server, you will need to consider how to maintain backups and recover your installation, should there be a need to migrate it to another cluster or recover from a critical event.
+When operating and administering CircleCI server, you will need to maintain backups and recover your installation if you need to migrate to another cluster or recover from a critical event.
 
-CircleCI recommends link:https://velero.io/[Velero] for backup and restore. The benefit of this approach is that it not only restores your application's data,
-but it also restores the state of the Kubernetes cluster and its resources at the time of the backup. CirleCI server supports backup and restore with Velero `1.12`. This document outlines recommendations for how to back up and restore your CircleCI server instance data and state using link:https://velero.io/[Velero].
+CircleCI recommends link:https://velero.io/[Velero] for backup and restore. The benefit of this approach is in restoring your application's data along with the state of the Kubernetes cluster and its resources at the time of the backup. CirleCI server supports backup and restore with Velero `1.12`. This document outlines recommendations for how to back up and restore your CircleCI server instance data and state using link:https://velero.io/[Velero].
 
 NOTE: Backup and restore of the CircleCI services is dependent on Velero. If your cluster is lost, you will not be able to restore CircleCI until you have successfully started Velero in the cluster. From there you can recover the CircleCI services.
 

@@ -1,4 +1,5 @@
 = CircleCI server security features
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: This document outlines security features built into CircleCI server v4.8 and related integrations.
 :experimental:

@@ -1,9 +1,10 @@
 = Configuring external services
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: This document describes how to configure the following external services for use with a CircleCI server v4.8 installation
 :experimental:
 
-This page describes how to configure external services for use with either a new CircleCI server v4.8 installation or migrating internal PostgreSQL and MongoDB data from existing CircleCI server v4.8 installation to your externalized datastores.
+This page describes how to configure external services for use with a new CircleCI server v4.8 installation. Migration to externalized PostgreSQL and MongoDB is also supported and described in this guide.
 
 [#postgresql]
 == PostgreSQL
@@ -68,7 +69,7 @@ Consider running at least two PostgreSQL replicas to allow recovery from primary
 
 NOTE: If you are doing a fresh install of CircleCI server, then you can skip this section and head to <<connecting-your-external-postgres>>
 
-When a CircleCI server instance is deployed, Postgres is deployed internally by default via its helm chart. However, as an operator, you may wish to externalize this database to have better control over scalability and availability. Once you have configured your external Postgres, you may use the guide below to migrate your Postgres data to your external database.
+When a CircleCI server instance is deployed, PostgreSQL is deployed internally by default via its Helm chart. However, as an operator, you may wish to externalize this database to have better control over scalability and availability. Once you have configured your external PostgreSQL, you may use the guide below to migrate your PostgreSQL data to your external database.
 
 CAUTION: This process requires downtime.
 
@@ -103,31 +104,31 @@ kubectl exec -it -n "$namespace" "$PG_POD" -- bash
 psql -h <your-external-postgres-host> -U postgres -p <your-external-postgres-port>
 ----
 
-You should be able to connect to your external Postgres at this point. If not, resolve any issues before proceeding.
+You should be able to connect to your external PostgreSQL at this point. If not, resolve any issues before proceeding.
 
 TIP: You may use `helm upgrade ...` to restore your CircleCI server instance to a running state.
 
 ==== 3. Generate export of your internal PostgreSQL
 
-. Retrieve your internal Postgres credentials:
+. Retrieve your internal PostgreSQL credentials:
 +
 [source,shell]
 ----
 PG_PASSWORD=$(kubectl -n "$namespace" get secrets postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)
 ----
 +
-NOTE: The username for your internal Postgres is `postgres`. The password is randomly generated unless directly set at installation.
+NOTE: The username for your internal PostgreSQL is `postgres`. The password is randomly generated unless directly set at installation.
 
-. Connect to your Postgres pod and perform a Postgres dump:
+. Connect to your PostgreSQL pod and perform a PostgreSQL dump:
 +
 [source,shell]
 ----
 kubectl -n "$namespace" exec -it "$PG_POD" -- bash -c "export PGPASSWORD='$PG_PASSWORD' && pg_dumpall -U postgres -c" > circle.sql
 ----
 +
-NOTE: This backup is created in the filesystem used by the Postgres pod. If you wish to store it locally, you may use `kubectl cp -n "$namespace" "$PG_POD":circle.sql /local/dir/circle.sql`
+NOTE: This backup is created in the filesystem used by the PostgreSQL pod. If you wish to store it locally, you may use `kubectl cp -n "$namespace" "$PG_POD":circle.sql /local/dir/circle.sql`
 
-. Clean up the Postgres Dump. Your internally deployed Postgres uses the username `postgres`. However, during the restore, the Postgres dump will drop all resources before trying to create new ones, including the `postgres` user. Access the Postgres pod where the dump is stored and run the following commands on the Postgres dump file to remove the lines that would delete the Postgres user.
+. Clean up the PostgreSQL Dump. Your internally deployed PostgreSQL uses the username `postgres`. However, during the restore, the PostgreSQL dump will drop all resources before trying to create new ones, including the `postgres` user. Access the PostgreSQL pod where the dump is stored and run the following commands on the PostgreSQL dump file to remove the lines that would delete the PostgreSQL user.
 +
 [source,shell]
 ----
@@ -141,14 +142,14 @@ sed -i".bak" '/ALTER ROLE postgres WITH SUPERUSER INHERIT CREATEROLE CREATEDB LO
 
 ==== 4. Restore your data in your external PostgreSQL
 
-While still connected to your the internally deployed Postgres, restore the dumped data to your external Postgres:
+While still connected to your the internally deployed PostgreSQL, restore the dumped data to your external PostgreSQL:
 
 [source,shell]
 ----
 psql -h <your-external-postgres-host> -U postgres -p <your-external-postgres-port> < circle.sql
 ----
 
-Now your external Postgres will have your CircleCI server data. In the next section you will update CircleCI server to point to your external Postgres.
+Now your external PostgreSQL will have your CircleCI server data. In the next section you will update CircleCI server to point to your external PostgreSQL.
 
 [#connecting-your-external-postgres]
 === Connecting your external PostgreSQL instance to CircleCI server
@@ -200,7 +201,7 @@ postgresql:
 ----
 --
 
-The changes will take effect upon running `helm install/upgrade`. If you are completing a migration to an externalized PostgreSQL instance then when you perform `helm upgrade`, the scaled down pods will be scaled back to their replica numbers as defined by your `values.yaml`.
+The changes will take effect upon running `helm install/upgrade`. If you are completing a migration to an externalized PostgreSQL instance, when you perform `helm upgrade` the scaled down application pods will be scaled back to their replica numbers as defined by your `values.yaml`.
 
 
 [#backing-up-postgresql]
@@ -224,7 +225,7 @@ NOTE: If using your own MongoDB instance, it needs to be version 3.6 or higher.
 
 NOTE: If you are doing a fresh install of CircleCI server, then you can skip this section and head to <<connecting-your-external-mongodb>>
 
-When a CircleCI server instance deployed, MongoDB is deployed internally by default via its helm chart. However, as an operator, you may wish to externalize this database to have better control over scalability and availability. Once you have configured your external MongoDB, you may use the guide below to migrate your Mongo data to your external database.
+When a CircleCI server instance deployed, MongoDB is deployed internally by default via its Helm chart. However, as an operator, you may wish to externalize this database to have better control over scalability and availability. Once you have configured your external MongoDB, you may use the guide below to migrate your Mongo data to your external database.
 
 CAUTION: This process requires downtime.
 
@@ -361,4 +362,4 @@ mongodb:
 ----
 --
 
-The changes will take effect upon running `helm install/upgrade`. If you are completing a migration to an externalized MongoDB instance then when you perform `helm upgrade`, the scaled down pods will be scaled back to their replica numbers as defined by your `values.yaml`.
+The changes will take effect upon running `helm install/upgrade`. If you are completing a migration to an externalized MongoDB instance, when you perform `helm upgrade` the scaled down application pods will be scaled back to their replica numbers as defined by your `values.yaml`.
@@ -1,4 +1,5 @@
 = Data retention in server
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Learn how to configure data retention policies for MongoDB, PostgreSQL, and object storage buckets in your CircleCI server installation.
 :experimental:

@@ -1,12 +1,13 @@
 = Expanding internal database volumes
+:page-noindex: true
 :page-platform: Server v4.8, Server Admin
 :page-description: Expanding internal database volumes for CircleCI server v4.8.
 :experimental:
 
 [#overview]
 == Overview
 
-If you have chosen to deploy either of the CircleCI databases (MongoDB or PostgreSQL) within the cluster, rather than externally provisioning these databases, there may come a point at which the storage space initially made available to these databases is no longer sufficient. Internal databases in your Kubernetes cluster make use of link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/[persistent volumes] for persistent storage. The size of these volumes is determined by persistence volume claims (PVCs). These PVCs request storage space based on what has been made available to the nodes in your cluster.
+If you deployed CircleCI databases (MongoDB or PostgreSQL) internally within the cluster, their storage may eventually become insufficient. Internal databases in your Kubernetes cluster make use of link:https://kubernetes.io/docs/concepts/storage/persistent-volumes/[persistent volumes] for persistent storage. The size of these volumes is determined by persistence volume claims (PVCs). These PVCs request storage space based on what has been made available to the nodes in your cluster.
 
 This document runs through the steps required to increase PVCs to expand the space available to your internally deployed databases. This operation should not require any downtime, unless you need to restart your database pods.