### Retrieve system process list

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Example request and response format for the GET /admin/docker/ps endpoint.

```text
UID        PID  PPID C SZ   RSS PSR STIME TTY      STAT START   TIME COMMAND
root         1     0 0  1000 2000  0 08:00 ?       Ss   Aug03  0:05 /sbin/init
discourse   234  232 2 5000 150000 1 08:05 ?       Sl   Aug03 10:30 unicorn master -E production
...
```

```bash
curl "http://localhost:3000/admin/docker/ps"
```

--------------------------------

### Upgrade Method Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Example request for triggering a background upgrade.

```ruby
# POST /admin/docker/update
# { path: "/var/www/discourse" }
# Spawns background upgrade process
```

--------------------------------

### Latest Method Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Example request for fetching latest version information.

```ruby
# GET /admin/docker/latest?path=/var/www/discourse
# Returns latest version info for core Discourse
```

--------------------------------

### Configure Bundle Install

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Command used for bundle installation with retry and parallel job settings.

```ruby
bundle install --retry 3 --jobs 4
```

--------------------------------

### Redis Key Value Examples

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Example values for keys used by Docker Manager to track upgrade status, progress, and logs in Redis.

```text
logs:/var/www/discourse:v3.0.0 = "Running migrations...\nCompiling assets...\n"
percent:/var/www/discourse:v3.0.0 = "50"
status:/var/www/discourse:v3.0.0 = "running"
upgrade:/var/www/discourse = "abc123def456..."
```

--------------------------------

### Start Upgrade Method

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Initiates the upgrade process for the selected repository or repositories.

```javascript
@action
start()
```

```javascript
// User clicks "Start Upgrade"
await this.start();
```

--------------------------------

### StatusMessage Structure and Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Defines the schema and provides an example for upgrade status updates.

```json
{
  "type": "status",
  "value": "string|null",
  "repos": ["string"]
}
```

```json
{
  "type": "status",
  "value": "complete",
  "repos": ["discourse"]
}
```

--------------------------------

### Example log output format

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/errors.md

Shows the structure of a typical upgrade log entry.

```text
[2026-08-03 10:15:30] Docker Manager: Upgrade started
[2026-08-03 10:15:31] $ bundle install --retry 3 --jobs 4
[2026-08-03 10:15:45] Bundle complete...
[2026-08-03 10:16:00] FAILED: 'bundle exec rake assets:precompile' exited with a return value of 1
[2026-08-03 10:16:00] Docker Manager: FAILED TO UPGRADE
```

--------------------------------

### PercentMessage Structure and Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Defines the schema and provides an example for progress percentage updates.

```json
{
  "type": "percent",
  "value": "integer",
  "repos": ["string"]
}
```

```json
{
  "type": "percent",
  "value": 50,
  "repos": ["discourse"]
}
```

--------------------------------

### Initiate upgrade with startUpgrade

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Starts the upgrade process for the repository and updates the upgrading state.

```javascript
async startUpgrade()
```

```javascript
await repo.startUpgrade();
// Upgrade process initiated for this repo
```

--------------------------------

### LogMessage Structure and Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Defines the schema and provides an example for real-time log messages.

```json
{
  "type": "log",
  "value": "string",
  "repos": ["string"]
}
```

```json
{
  "type": "log",
  "value": "Running migrations...",
  "repos": ["discourse"]
}
```

--------------------------------

### ReposResponse Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Example JSON payload for the ReposResponse type.

```json
{
  "repos": [
    {
      "name": "discourse",
      "path": "/var/www/discourse",
      "branch": "origin/main",
      "official": true,
      "id": "discourse",
      "version": "abc123...",
      "pretty_version": "v3.0.1",
      "url": "https://github.com/discourse/discourse",
      "upgrading": false
    }
  ],
  "upgrade_required": false
}
```

--------------------------------

### Bundle Install Failure Debugging

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/errors.md

Error message and debug commands for troubleshooting bundle installation failures.

```text
FAILED: 'bundle install --retry 3 --jobs 4' exited with a return value of 1
```

```bash
cd /var/www/discourse
bundle install --verbose
```

--------------------------------

### Start upgrade process

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Marks the repository as upgrading in Redis to prevent concurrent operations.

```ruby
def start_upgrading
```

```ruby
if repo.start_upgrading
  # Successfully marked as upgrading
else
  # Already being upgraded
end
```

--------------------------------

### UpgradeProgress Structure and Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Defines the schema for tracking the state of an ongoing repository upgrade.

```json
{
  "logs": "string",
  "percentage": "integer",
  "status": "string|null",
  "repos": ["string"]
}
```

```json
{
  "logs": "Cycling Unicorn...\nStopping workers...\nRunning migrations...\n",
  "percentage": 45,
  "status": "running",
  "repos": ["discourse"]
}
```

--------------------------------

### GET /admin/docker/ps

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/README.md

Returns a list of system processes, sorted by memory usage.

```APIDOC
## GET /admin/docker/ps

### Description
Returns system process list (ps aux output) sorted by memory usage.

### Method
GET

### Endpoint
/admin/docker/ps
```

--------------------------------

### Usage of commitUrl helper

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/components-helpers.md

Examples showing how to generate commit links or plain text based on provided arguments.

```javascript
import commitUrl from "./commit-url";

// Result: <a class='commit-hash' title='abc123...' href='https://github.com/discourse/discourse/commit/abc123...'>v3.0.1</a>
commitUrl("custom-class", "abc123def456...", "v3.0.1", "https://github.com/discourse/discourse.git")

// Result: v3.0.1
commitUrl("custom-class", "abc123...", "v3.0.1", null)

// Result: ""
commitUrl("custom-class", "abc123...", null, "https://github.com/discourse/discourse")
```

--------------------------------

### Get upgrade version

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the version string set during the start_upgrading process.

```ruby
def upgrade_version
```

--------------------------------

### Request Docker upgrade progress

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Example request and response for fetching current upgrade progress.

```bash
curl "http://localhost:3000/admin/docker/progress?path=/var/www/discourse&version=abc123..."
```

```json
{
  "progress": {
    "logs": "Cycling Unicorn, to free up memory\nStopping 3 worker(s)...\n",
    "percentage": 35,
    "status": "running",
    "repos": ["discourse"]
  }
}
```

--------------------------------

### GET /admin/docker/repos

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/INDEX.md

Retrieves the list of repositories and their current versions.

```APIDOC
## GET /admin/docker/repos

### Description
Retrieves the list of repositories and their current versions.

### Method
GET

### Endpoint
/admin/docker/repos
```

--------------------------------

### LatestVersionInfo Structure and Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Defines the schema for remote version information used for version comparison.

```json
{
  "path": "string",
  "version": "string",
  "pretty_version": "string|null",
  "commits_behind": "integer",
  "date": "datetime|null"
}
```

```json
{
  "path": "/var/www/discourse",
  "version": "xyz789abc123...",
  "pretty_version": "v3.1.0",
  "commits_behind": 12,
  "date": "2026-08-03T10:30:00Z"
}
```

--------------------------------

### GET /admin/docker/latest

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Fetches latest remote version info for all repositories.

```APIDOC
## GET /admin/docker/latest

### Description
Fetches latest remote version info for all repositories. Returns array of objects with version details.

### Method
GET

### Endpoint
/admin/docker/latest

### Parameters
#### Query Parameters
- **path** (string) - Required - Set to "all"

### Response
#### Success Response (200)
- **repos** (Array) - List of repository version details

#### Response Example
{
  "repos": [
    {
      "path": "string",
      "version": "string",
      "pretty_version": "string|null",
      "commits_behind": "integer",
      "date": "datetime|null"
    }
  ]
}
```

--------------------------------

### GET /admin/docker/repos

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Fetches all repositories from the backend. Results are cached in memory.

```APIDOC
## GET /admin/docker/repos

### Description
Fetches all repositories from the backend. Results are cached in memory; subsequent calls return cached array without API request.

### Method
GET

### Endpoint
/admin/docker/repos

### Response
#### Success Response (200)
- **repos** (Array) - List of repository objects
- **upgrade_required** (boolean|null) - Indicates if an upgrade is required

#### Response Example
{
  "repos": [
    {
      "name": "string",
      "path": "string",
      "branch": "string",
      "official": "boolean",
      "plugin": "object|null",
      "fork": "boolean|null",
      "id": "string",
      "version": "string",
      "pretty_version": "string|null",
      "url": "string",
      "upgrading": "boolean|null",
      "upgrade_version": "string|null"
    }
  ],
  "upgrade_required": null
}
```

--------------------------------

### Usage of newCommits helper

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/components-helpers.md

Examples showing how to generate comparison links or localized text based on the number of commits behind.

```javascript
import newCommits from "./new-commits";

// Result: <a href='https://github.com/discourse/discourse/compare/abc123...xyz789'>12 new commits</a>
newCommits(12, "abc123def456...", "xyz789abc123...", "https://github.com/discourse/discourse.git")

// Result: 12 new commits
newCommits(12, "abc123...", "xyz789...", null)

// Result: ""
newCommits(0, "abc123...", "xyz789...", "https://github.com/discourse/discourse")

// Result: ""
newCommits(null, "abc123...", "xyz789...", "https://github.com/discourse/discourse")
```

--------------------------------

### GET /admin/upgrade

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Redirects the user to the current update endpoint.

```APIDOC
## GET /admin/upgrade

### Description
Redirects to /admin/update.

### Method
GET

### Endpoint
/admin/upgrade

### Response
#### Success Response (301)
- **Status Code** (301) - Moved Permanently
```

--------------------------------

### RepositoryInfo Structure and Example

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/types.md

Defines the schema for repository data returned by the /admin/docker/repos endpoint.

```json
{
  "name": "string",
  "path": "string",
  "branch": "string",
  "official": "boolean",
  "plugin": "AdminPluginData|null",
  "fork": "boolean|null",
  "id": "string",
  "version": "string",
  "pretty_version": "string|null",
  "url": "string",
  "upgrading": "boolean|null",
  "upgrade_version": "string|null"
}
```

```json
{
  "name": "discourse",
  "path": "/var/www/discourse",
  "branch": "origin/main",
  "official": true,
  "plugin": null,
  "fork": null,
  "id": "discourse",
  "version": "abc123def456...",
  "pretty_version": "v3.0.1 +5",
  "url": "https://github.com/discourse/discourse",
  "upgrading": false,
  "upgrade_version": null
}
```

--------------------------------

### GET /admin/docker/progress

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/INDEX.md

Tracks the progress of an ongoing upgrade process.

```APIDOC
## GET /admin/docker/progress

### Description
Tracks the progress of an ongoing upgrade process.

### Method
GET

### Endpoint
/admin/docker/progress
```

--------------------------------

### GET /admin/docker/ps

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/INDEX.md

Monitors the status of Docker processes.

```APIDOC
## GET /admin/docker/ps

### Description
Monitors the status of Docker processes.

### Method
GET

### Endpoint
/admin/docker/ps
```

--------------------------------

### GET /admin/docker/latest

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Fetches the latest version information for the repository from the remote source.

```APIDOC
## GET /admin/docker/latest

### Description
Fetches latest version info from remote. Updates the repository's latest object with the response and updates the last checked timestamp.

### Method
GET

### Endpoint
/admin/docker/latest
```

--------------------------------

### Define Upgrade Subprocess Environment

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Example of environment variables received by the upgrade subprocess initiated by the AdminController.

```bash
UPGRADE_USER_ID=42
UPGRADE_PATH=/var/www/discourse
UPGRADE_REPO_VERSION=abc123def456...
RAILS_ENV=production
```

--------------------------------

### GET /admin/docker/latest

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/INDEX.md

Retrieves remote version information for the managed repositories.

```APIDOC
## GET /admin/docker/latest

### Description
Retrieves remote version information for the managed repositories.

### Method
GET

### Endpoint
/admin/docker/latest
```

--------------------------------

### JavaScript MessageBus Subscription

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Example implementation for subscribing to real-time upgrade updates in JavaScript.

```javascript
this.messageBus.subscribe("/docker/update", (msg) => {
  if (msg.type === "log") {
    console.log(msg.value);
  } else if (msg.type === "percent") {
    console.log(`Progress: ${msg.value}%`);
  } else if (msg.type === "status") {
    console.log(`Status: ${msg.value}`);
  }
});
```

--------------------------------

### MessageBus Handler Implementation

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrade-store.md

Example handler for processing incoming MessageBus updates to update the upgradeStore state.

```javascript
onMessage(msg) {
  switch (msg.type) {
    case "log":
      this.upgradeStore.consoleOutput += msg.value + "\n";
      break;
    case "percent":
      this.upgradeStore.progressPercentage = msg.value;
      break;
    case "status":
      this.upgradeStore.upgradeStatus = msg.value;
      if (msg.value === "complete") {
        // Trigger page refresh
        this.session.requiresRefresh = true;
      }
      break;
  }
}
```

--------------------------------

### upgrade()

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Executes the complete upgrade sequence, including validation, git operations, dependency installation, database migrations, and asset compilation.

```APIDOC
## upgrade()

### Description
Executes the complete upgrade sequence, including validation, git operations, dependency installation, database migrations, and asset compilation. Raises a RuntimeError if the upgrade fails.

### Parameters
None

### Return Type
None
```

--------------------------------

### GET /admin/docker/latest

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/README.md

Fetches the latest remote version information for a specific repository path.

```APIDOC
## GET /admin/docker/latest

### Description
Returns latest remote version info, showing commits behind, latest tag, and date.

### Method
GET

### Endpoint
/admin/docker/latest

### Parameters
#### Query Parameters
- **path** (string) - Required - The repository path to check.
```

--------------------------------

### Repo.startUpgrade()

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Initiates the upgrade process for the repository.

```APIDOC
## Repo.startUpgrade()

### Description
Triggers the upgrade process for the current repository instance.
```

--------------------------------

### Consume upgrade store in components

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrade-store.md

Example of binding upgrade store properties to a Glimmer component template.

```javascript
import Component from "@glimmer/component";
import { service } from "@ember/service";

export default class UpgradeProgressComponent extends Component {
  @service upgradeStore;
  
  get progressPercentage() {
    return this.upgradeStore.progressPercentage;
  }
  
  get isRunning() {
    return this.upgradeStore.running;
  }
  
  get logs() {
    return this.upgradeStore.consoleOutput;
  }
  
  <template>
    {{#if this.isRunning}}
      <div class="progress">
        Progress: {{this.progressPercentage}}%
      </div>
      <div class="console">
        <pre>{{this.logs}}</pre>
      </div>
    {{/if}}
  </template>
}
```

--------------------------------

### Upgrade All Action

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Handles the transition to the update route for all repositories.

```javascript
@action
upgradeAllButton()
```

```javascript
// User clicks "Upgrade All" button
this.router.transitionTo("update.show", "all");
// Navigates to /admin/update/all
```

--------------------------------

### Initialize WebServerAdapter

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/web-server-adapter.md

Creates a new adapter instance bound to an upgrader.

```ruby
adapter = DockerManager::WebServerAdapter.new(upgrader)
```

--------------------------------

### Initialize Repo Instance

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Creates a new Repo instance with optional initial attributes, handling special transformations for latest and plugin properties.

```javascript
constructor(attributes = {})
```

```javascript
const repo = new Repo({
  id: "discourse",
  name: "discourse",
  version: "abc123...",
  latest: { version: "def456..." }
});
```

--------------------------------

### UpdateRoute setupController hook

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Initializes the controller and checks for main branch warnings.

```javascript
setupController(controller, model)
```

--------------------------------

### Manage repository lifecycle and upgrades

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Demonstrates loading repositories, checking for new versions, initiating upgrades, and polling for progress status.

```javascript
// Load all repositories
const repos = await Repo.findAll();

// Find specific repository
const discourse = await Repo.find("discourse");

// Check for updates
await discourse.findLatest();
if (discourse.hasNewVersion) {
  console.log(`Updates available: ${discourse.prettyVersion} → ${discourse.prettyLatestVersion}`);
}

// Initiate upgrade
await discourse.startUpgrade();

// Poll progress
let progress = await discourse.findProgress();
while (progress.status === "running") {
  console.log(`Progress: ${progress.percentage}%`);
  await new Promise(r => setTimeout(r, 1000));
  progress = await discourse.findProgress();
}

// Handle completion
if (progress.status === "complete") {
  console.log("Upgrade complete!");
} else if (progress.status === "failed") {
  console.log("Upgrade failed!");
}
```

--------------------------------

### Upgrade Store Initialization

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrade-store.md

Initializes the upgrade store with progress data fetched from the repository.

```javascript
const progress = await repo.findProgress();
upgradeStore.reset({
  consoleOutput: progress.logs,
  progressPercentage: progress.percentage,
  upgradeStatus: progress.status,
  repos: [repo.id]
});
```

--------------------------------

### Initiate Docker Upgrade via POST

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Use these requests to trigger an asynchronous upgrade process for a specific repository or all repositories.

```bash
curl -X POST "http://localhost:3000/admin/docker/update" \
  -d "path=/var/www/discourse" \
  -d "version=abc123..."
```

```bash
curl -X POST "http://localhost:3000/admin/docker/update" \
  -d "path=all"
```

--------------------------------

### Create a new Repo instance

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Use this factory method to instantiate a new Repo object with initial attributes.

```javascript
const repo = Repo.create({ id: "discourse", name: "discourse" });
```

--------------------------------

### Get last percentage

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Returns the current progress percentage stored in Redis.

```ruby
def last_percentage
```

--------------------------------

### Repo.findAll()

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Fetches all available repositories and populates the internal cache.

```APIDOC
## Repo.findAll()

### Description
Retrieves a list of all repositories. This call also updates the module-level `needsImageUpgrade` flag based on the backend response.

### Returns
- **Promise<Array>** - A promise that resolves to an array of repository objects.
```

--------------------------------

### Get allUpToDate Computed Property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Checks if all repositories in the model are currently up to date.

```javascript
get allUpToDate()
```

--------------------------------

### Initialize AdminController

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Class definition for AdminController, inheriting from Admin::AdminController and requiring the docker_manager plugin.

```ruby
class AdminController < Admin::AdminController
  requires_plugin PLUGIN_NAME
```

--------------------------------

### Manage Repository and Upgrades

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Find repositories, check for updates, and manage the upgrade lifecycle.

```ruby
# Find all repositories
repos = DockerManager::GitRepo.find_all

# Find a specific repository
discourse = DockerManager::GitRepo.find("/var/www/discourse")

# Check if updates available
if discourse && discourse.latest_local_commit != discourse.latest_origin_commit
  puts "Updates available: #{discourse.commits_behind} commits behind"
end

# Start upgrade
if discourse.start_upgrading
  puts "Version: #{discourse.upgrade_version}"
  # Perform upgrade...
  discourse.stop_upgrading
else
  puts "Already upgrading"
end

# Get version info
puts "Local: #{discourse.latest_local_tag_version}"
puts "Remote: #{discourse.latest_origin_tag_version}"
```

--------------------------------

### Implement Web Server Adapters

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Provides specific adapters for Unicorn and Pitchfork web servers to manage process IDs.

```ruby
class UnicornAdapter < WebServerAdapter
  def server_name
    "Unicorn"
  end
  
  def launcher_pid
    `pgrep -f unicorn_launcher`.strip.to_i
  end
  
  def master_pid
    `pgrep -f "^unicorn master -E"`.strip.to_i
  end
end
```

```ruby
class PitchforkAdapter < WebServerAdapter
  def server_name
    "Pitchfork"
  end
  
  def launcher_pid
    `pgrep -f unicorn_launcher`.strip.to_i
  end
  
  def master_pid
    `pgrep -f "^pitchfork monitor"`.strip.to_i
  end
end
```

--------------------------------

### Configuration Files

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/README.md

Core configuration files for routing, plugin metadata, and dependencies.

```text
config/routes.rb        → Route definitions
plugin.rb               → Plugin metadata
package.json            → npm dependencies
tsconfig.json           → TypeScript config
```

--------------------------------

### GET /admin/upgrade/:id

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Redirects the user to the specific update endpoint for a given ID.

```APIDOC
## GET /admin/upgrade/:id

### Description
Redirects to /admin/update/:id.

### Method
GET

### Endpoint
/admin/upgrade/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier for the update process.

### Response
#### Success Response (301)
- **Status Code** (301) - Moved Permanently
```

--------------------------------

### Retrieve System Process List

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Returns the output of the system process list, formatted based on the host operating system.

```ruby
def ps
```

--------------------------------

### Get remote commit date

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the commit date of the latest remote commit.

```ruby
def latest_origin_commit_date
```

--------------------------------

### Get outdated Computed Property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Checks if a Docker image or Ruby upgrade is required.

```javascript
get outdated()
```

--------------------------------

### Initialize GitRepo instance

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Creates a new GitRepo instance for a given path, with optional name specification.

```ruby
repo = DockerManager::GitRepo.new("/var/www/discourse", "discourse")
```

--------------------------------

### Get managerRepo Computed Property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Retrieves the docker_manager repository from the model array with caching.

```javascript
@cached
get managerRepo()
```

--------------------------------

### Upgrade Process Workflow

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/architecture.md

A visual representation of the sequential steps taken during the Docker Manager upgrade process.

```text
START
  ↓
[Validate]
  ├─ Check workers ≥ 1
  ├─ Check master/launcher PIDs valid
  └─ Mark repo as upgrading
  ↓
[Worker Management] (5%)
  ├─ Cycle server (reload)
  └─ Scale down workers
  ↓
[Git Operations] (5% → 20%)
  ├─ Fetch tags and branches
  ├─ Handle master→main rename
  └─ Checkout latest tracking ref
  ↓
[Dependencies] (20% → 30%)
  ├─ bundle install
  ├─ yarn/pnpm install
  └─ rake plugin:pull_compatible_all
  ↓
[Database] (30% → 40%)
  └─ SKIP_POST_DEPLOYMENT_MIGRATIONS=1 rake multisite:migrate
  ↓
[Assets] (40% → 80%)
  ├─ rake themes:update
  ├─ rake assets:precompile
  ├─ rake s3:upload_assets (if S3)
  └─ Progress checkpoint: 80%
  ↓
[Server Reload] (80% → 85%)
  ├─ Reload server (zero-downtime)
  └─ Wait for workers to be ready
  ↓
[Cache Clearing] (85% → 90%)
  └─ rake assets:flush_sw
  ↓
[Post-Deploy] (90% → 100%)
  ├─ rake multisite:migrate (post-deployment)
  ├─ rake s3:expire_missing_assets (if S3)
  └─ Log to staff action log
  ↓
[Cleanup]
  ├─ Mark repo as not upgrading
  └─ Clear restart flag
  ↓
COMPLETE/FAILED
```

--------------------------------

### Perform Upgrade Controller Action

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Initiates the upgrade process by resetting the store and triggering either a bulk or single repository upgrade.

```javascript
// In controller action
@action
async performUpgrade() {
  // Reset store before starting
  this.upgradeStore.reset();
  
  // Initiate upgrade
  if (Array.isArray(this.model)) {
    await Repo.upgradeAll();
  } else {
    await this.model.startUpgrade();
  }
  
  // Real-time updates come via MessageBus
  // @see onUpgradeMessage in UpdateRoute
}
```

--------------------------------

### Manage upgrades in controllers

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrade-store.md

Handles starting and resetting upgrades within an Ember controller.

```javascript
import Controller from "@ember/controller";
import { action } from "@ember/object";
import { service } from "@ember/service";
import Repo from "../models/repo";

export default class UpgradeController extends Controller {
  @service upgradeStore;
  @service dialog;
  
  @action
  async startUpgrade() {
    // Initialize store
    this.upgradeStore.reset();
    
    // Start upgrade
    if (Array.isArray(this.model)) {
      await Repo.upgradeAll();
    } else {
      await this.model.startUpgrade();
    }
    
    // Store is updated by MessageBus handlers in Route
  }
  
  @action
  resetUpgrade() {
    this.dialog.confirm({
      didConfirm: async () => {
        // Cancel upgrade
        await this.model.resetUpgrade();
        // Clear store
        this.upgradeStore.reset();
      }
    });
  }
}
```

--------------------------------

### Upgrade all repositories

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Initiates a background upgrade process for all repositories that are not up-to-date.

```javascript
await Repo.upgradeAll();
// Upgrade process initiated
```

--------------------------------

### Initialize Upgrader instance

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Defines the constructor signature for the Upgrader class.

```ruby
def initialize(user_id, repos, from_version)
```

--------------------------------

### Implement ConsoleComponent in Controller

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/components-helpers.md

Example of integrating the Console component within an Ember controller template.

```javascript
import { service } from "@ember/service";

export default class MyController extends Controller {
  @service upgradeStore;
  
  <template>
    <DockerManager::Console 
      @output={{this.upgradeStore.consoleOutput}} 
      @followOutput={{true}}
    />
  </template>
}
```

--------------------------------

### Find an upgrading repository

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Returns the first repository currently undergoing an upgrade by calling findAll internally.

```javascript
const upgrading = await Repo.findUpgrading();
if (upgrading) {
  console.log(`${upgrading.name} is upgrading`);
}
```

--------------------------------

### ps

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Retrieves the system process list output.

```APIDOC
## ps

### Description
Returns process list output from the system, sorted by memory usage depending on the operating system.

### Parameters
None

### Return Type
Plain text (process list output)
```

--------------------------------

### Manage Web Server Processes with DockerManager::Upgrader

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/web-server-adapter.md

Demonstrates how to interact with the auto-selected web server adapter during an upgrade process to scale workers and reload the server.

```ruby
# Typically used within Upgrader context
upgrader = DockerManager::Upgrader.new(user_id, repo, version)

# Adapter is auto-selected during Upgrader initialization
adapter = upgrader.web_server  # UnicornAdapter or PitchforkAdapter

# Check current workers
puts "Active workers: #{adapter.workers.count}"

# Scale down to minimum
num_to_scale = adapter.workers.size - adapter.min_workers
adapter.scale_down_workers(num_to_scale)

# Do upgrade work...

# Reload server with new code
adapter.reload

# Restore worker count if needed
adapter.scale_up_workers(num_to_scale)
```

--------------------------------

### Get tracking ref

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Determines the ref to track for updates based on configuration or upstream branch.

```ruby
def tracking_ref
```

--------------------------------

### Get local commit date

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the commit date of the current HEAD as a DateTime object.

```ruby
def latest_local_commit_date
```

--------------------------------

### Execute Upgrade Sequence

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Initializes the upgrader and executes the full upgrade process, including validation, git operations, and asset compilation.

```ruby
upgrader = DockerManager::Upgrader.new(user.id, repo, "v3.0.0")
begin
  upgrader.upgrade
rescue => e
  # Handle error
  puts e.message
end
```

--------------------------------

### Get latest local commit SHA

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Retrieves the full SHA of the current HEAD commit.

```ruby
def latest_local_commit
```

```ruby
repo.latest_local_commit
# => "abc123def456..."
```

--------------------------------

### Get upgradeAllButtonDisabled Computed Property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Determines if the 'Upgrade All' button should be disabled based on repository status.

```javascript
get upgradeAllButtonDisabled()
```

--------------------------------

### Implement upgrade flow

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrade-store.md

Shows the lifecycle of an upgrade operation, including initialization, message bus updates, and cleanup.

```javascript
// Start upgrade
upgradeStore.reset();
await repo.startUpgrade();

// MessageBus messages update store
// Route handler updates properties:
upgradeStore.consoleOutput += msg.value + "\n";
upgradeStore.progressPercentage = msg.value;
upgradeStore.upgradeStatus = msg.value;

// Components automatically update
// <DockerManager::ProgressBar @percentage={{upgradeStore.progressPercentage}} />

// On completion
upgradeStore.reset();
```

--------------------------------

### Get Local Web URL

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/web-server-adapter.md

Returns the URL used for checking the web server status.

```ruby
adapter.local_web_url
# => "http://127.0.0.1:3000/srv/status"
```

--------------------------------

### Index Method Definition

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Defines the entry point for the Docker Manager web interface.

```ruby
def index
```

--------------------------------

### Access prettyVersion property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Retrieves a human-readable string for the local version.

```javascript
get prettyVersion()
```

--------------------------------

### DockerManager::GitRepo.find_all

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Retrieves a list of all managed git repositories, including Discourse core and installed plugins.

```APIDOC
## DockerManager::GitRepo.find_all

### Description
Returns all managed repositories, including Discourse core, the Docker Manager plugin, and all other visible plugins that contain a valid .git directory.

### Method
Class Method

### Return Type
Array<GitRepo>

### Example
```ruby
repos = DockerManager::GitRepo.find_all
```
```

--------------------------------

### Get last status

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Returns the current status string (e.g., running, complete, failed) from Redis.

```ruby
def last_status
```

--------------------------------

### Check Image Version

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Compares the current version file against the expected minimum version.

```ruby
version = File.read("/VERSION").strip
expected_version = Gem::Version.new("2.0.20260803-0122")
upgrade_image = version < expected_version
```

--------------------------------

### Get upstream branch

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the upstream branch for the current HEAD, or nil if in detached HEAD state.

```ruby
def upstream_branch
```

--------------------------------

### Run database migrations

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Commands for executing multisite migrations, with an option to skip post-deployment steps.

```ruby
SKIP_POST_DEPLOYMENT_MIGRATIONS=1 bundle exec rake multisite:migrate
```

```ruby
bundle exec rake multisite:migrate
```

--------------------------------

### Get remote URL

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the HTTPS URL of the remote origin, converting SSH URLs if necessary.

```ruby
def url
```

```ruby
repo.url
# => "https://github.com/discourse/discourse"
```

--------------------------------

### DockerManager::GitRepo.new(path, name = nil)

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Initializes a new GitRepo instance for a given repository path.

```APIDOC
## DockerManager::GitRepo.new(path, name = nil)

### Description
Creates a new GitRepo instance. Results are memoized internally to avoid repeated git command execution.

### Method
Constructor

### Parameters
- **path** (String) - Required - Absolute path to git repository
- **name** (String) - Optional - Repository name (auto-detected if nil)

### Return Type
GitRepo instance

### Example
```ruby
repo = DockerManager::GitRepo.new("/var/www/discourse", "discourse")
```
```

--------------------------------

### Get latest remote tag version

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the most recent annotated tag at the remote tracking ref.

```ruby
def latest_origin_tag_version
```

--------------------------------

### Get latest remote commit SHA

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Retrieves the full SHA of the commit at the tracking ref on the remote.

```ruby
def latest_origin_commit
```

```ruby
repo.latest_origin_commit
# => "def456abc123..."
```

--------------------------------

### Get showBanner Computed Property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Determines visibility of the banner based on dismissal status and content availability.

```javascript
get showBanner()
```

--------------------------------

### POST /admin/docker/update

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/README.md

Initiates an asynchronous background upgrade process.

```APIDOC
## POST /admin/docker/update

### Description
Spawns a background upgrade process and returns immediately.

### Method
POST

### Endpoint
/admin/docker/update
```

--------------------------------

### Instantiate Upgrader

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Creates a new upgrader instance for a specific repository and version.

```ruby
repo = DockerManager::GitRepo.find("/var/www/discourse")
upgrader = DockerManager::Upgrader.new(user.id, repo, "v3.0.0")
```

--------------------------------

### Get number of commits behind

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the count of commits the local repository is behind the remote tracking ref.

```ruby
def commits_behind
```

```ruby
repo.commits_behind
# => 15  (local is 15 commits behind)
```

--------------------------------

### Fetch all repositories

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Retrieves all repositories from the backend and caches them in memory for subsequent calls.

```javascript
const repos = await Repo.findAll();
// Returns cached result on subsequent calls
```

--------------------------------

### Get latest local tag version

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Returns the most recent annotated tag at HEAD, excluding specific tags, with commit count.

```ruby
def latest_local_tag_version
```

```ruby
repo.latest_local_tag_version
# => "v3.0.1 +5"  (5 commits since tag)
```

--------------------------------

### Find repository by path

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/git-repo.md

Locates a specific repository instance using its absolute file path.

```ruby
repo = DockerManager::GitRepo.find("/var/www/discourse")
# => <GitRepo: discourse> or nil
```

--------------------------------

### Integrate Services in Components

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/components-helpers.md

Injecting services like upgradeStore and router to access application state and navigation.

```javascript
export default class MyComponent extends Component {
  @service upgradeStore;
  @service router;
  
  get progressPercentage() {
    return this.upgradeStore.progressPercentage;
  }
}
```

--------------------------------

### Log via Adapter

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/web-server-adapter.md

Delegates logging messages to the associated upgrader instance.

```ruby
adapter.log("Scaling workers...")
# Calls upgrader.log("Scaling workers...")
```

--------------------------------

### POST /admin/docker/update

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/INDEX.md

Initiates an upgrade process for the specified repository.

```APIDOC
## POST /admin/docker/update

### Description
Initiates an upgrade process for the specified repository.

### Method
POST

### Endpoint
/admin/docker/update
```

--------------------------------

### run(cmd)

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Executes a shell command within the production environment, capturing output and publishing logs.

```APIDOC
## run(cmd)

### Description
Executes a shell command with a filtered environment, capturing all stdout and stderr. Raises a RuntimeError if the command returns a non-zero exit code.

### Parameters
- **cmd** (String) - Required - Shell command to execute

### Return Type
None
```

--------------------------------

### Configure S3 Asset Uploads

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Sets variables required to enable and configure S3 asset uploads after compilation.

```bash
export DISCOURSE_USE_S3=true
export DISCOURSE_S3_BUCKET=my-discourse-assets
export DISCOURSE_S3_CDN_URL=https://cdn.example.com
```

--------------------------------

### Backend Directory Structure

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/README.md

Organization of Ruby files within the lib/docker_manager directory.

```text
lib/docker_manager/
├── admin_controller.rb  → API endpoints
├── upgrader.rb          → Upgrade orchestration
├── git_repo.rb          → Repository operations
├── web_server_adapter.rb → Web server management
├── unicorn_adapter.rb   → Unicorn-specific
├── pitchfork_adapter.rb → Pitchfork-specific
└── fallback_compatibility_parser.rb → Version compatibility
```

--------------------------------

### Configure Admin Routes

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Defines routes under the /admin/docker/ path with admin-only access constraints.

```ruby
# config/routes.rb
scope "/admin", constraints: AdminConstraint.new do
  get "/update" => "admin#index"
  get "/docker/repos" => "admin#repos"
  get "/docker/latest" => "admin#latest"
  get "/docker/progress" => "admin#progress"
  post "/docker/update" => "admin#upgrade"
  delete "/docker/update" => "admin#reset_upgrade"
  get "/docker/ps" => "admin#ps"
  # Redirects for backward compatibility
  get "/upgrade" => redirect("/admin/update")
end
```

--------------------------------

### DockerManager::Upgrader.new

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Initializes a new upgrader instance to manage the upgrade process for specified repositories.

```APIDOC
## DockerManager::Upgrader.new(user_id, repos, from_version)

### Description
Creates a new upgrader instance bound to a specific user and set of repositories. It automatically selects the appropriate web server adapter and initializes internal state for tracking progress.

### Parameters
- **user_id** (Integer) - Required - ID of the user initiating the upgrade
- **repos** (GitRepo | Array<GitRepo>) - Required - Single repository or array of repositories to upgrade
- **from_version** (String) - Required - Version string to track for upgrade progress

### Return Type
Upgrader instance

### Example
```ruby
repo = DockerManager::GitRepo.find("/var/www/discourse")
upgrader = DockerManager::Upgrader.new(user.id, repo, "v3.0.0")
```
```

--------------------------------

### Configure Proxy Settings

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Sets proxy environment variables to be passed through to the upgrade subprocess.

```bash
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080
export no_proxy=localhost,127.0.0.1
```

--------------------------------

### POST /admin/docker/update

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Initiates an upgrade for all repositories that are not up-to-date.

```APIDOC
## POST /admin/docker/update

### Description
Initiates upgrade for all repositories that are not up-to-date. Sends POST request to initiate background upgrade process.

### Method
POST

### Endpoint
/admin/docker/update

### Parameters
#### Request Body
- **path** (string) - Required - Set to "all"

### Response
#### Success Response (200)
- **body** (string) - Plain text "OK"
```

--------------------------------

### Upgrade Method Definition

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Defines the method to initiate an upgrade.

```ruby
def upgrade
```

--------------------------------

### Detect web server adapter

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Automatically identifies the active web server (Unicorn or Pitchfork) and returns the corresponding adapter instance.

```ruby
private def web_server_adapter
```

--------------------------------

### Find Repositories

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Locates repositories based on path and upgrade status.

```ruby
def self.find_repos(path, upgrading: false)
```

```ruby
DockerManager::AdminController.find_repos("/var/www/discourse")
# Returns single GitRepo or nil

DockerManager::AdminController.find_repos("all", upgrading: true)
# Returns array of repos currently upgrading
```

--------------------------------

### Render RepoStatusComponent

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/components-helpers.md

Displays a repository status badge including version info and update indicators.

```javascript
<RepoStatus @repo={{repo}} />
```

--------------------------------

### Progress Method Definition

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Defines the method to fetch upgrade progress.

```ruby
def progress
```

--------------------------------

### Progress Response Schema

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

JSON structure for upgrade progress reporting.

```json
{
  "progress": {
    "logs": "string",
    "percentage": "integer",
    "status": "string|null",
    "repos": ["string"]
  }
}
```

--------------------------------

### Reset upgrade store state

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrade-store.md

Demonstrates various ways to reset the store state, including full resets, partial updates, and explicit clearing.

```javascript
// Reset everything
upgradeStore.reset();

// Reset with partial data
upgradeStore.reset({
  consoleOutput: initialLogs,
  progressPercentage: 30,
  upgradeStatus: "running",
  repos: ["discourse"]
});

// Reset with empty values explicitly
upgradeStore.reset({
  consoleOutput: "",
  progressPercentage: 0,
  upgradeStatus: null,
  repos: []
});
```

--------------------------------

### reset!()

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/upgrader.md

Resets the upgrade state by marking repositories as not upgrading, clearing logs, and resetting progress metrics.

```APIDOC
## reset!()

### Description
Marks repositories as not upgrading, clears all upgrade logs from Redis, resets percentage to 0, and clears status to nil.

### Parameters
None

### Return Type
None
```

--------------------------------

### Missing Web Server Error Messages

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/errors.md

Error messages displayed when the Unicorn launcher or master process is not detected.

```text
ABORTING, missing Unicorn launcher or master/monitor
No Unicorn master or launcher
```

--------------------------------

### Log upgrade status to browser console

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/errors.md

Outputs upgrade failure details and status to the browser developer console.

```javascript
console.log("Upgrade failed:", error);
console.log("Status:", this.upgradeStore.upgradeStatus);
```

--------------------------------

### Fetch Repository Information

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/endpoints.md

Retrieves a list of all managed repositories including their current version, branch, and upgrade status.

```json
{
  "repos": [
    {
      "name": "string",
      "path": "string",
      "branch": "string",
      "official": "boolean",
      "plugin": "object|null",
      "fork": "boolean|null",
      "id": "string",
      "version": "string",
      "pretty_version": "string|null",
      "url": "string",
      "upgrading": "boolean|null",
      "upgrade_version": "string|null"
    }
  ],
  "upgrade_required": "boolean|null"
}
```

```bash
curl -X GET "http://localhost:3000/admin/docker/repos" \
  -H "Authorization: Bearer token"
```

```json
{
  "repos": [
    {
      "name": "discourse",
      "path": "/var/www/discourse",
      "branch": "origin/main",
      "official": true,
      "plugin": null,
      "fork": null,
      "id": "discourse",
      "version": "abc123def456...",
      "pretty_version": "v3.0.1 +5",
      "url": "https://github.com/discourse/discourse",
      "upgrading": false,
      "upgrade_version": null
    },
    {
      "name": "docker_manager",
      "path": "/var/www/discourse/plugins/docker_manager",
      "branch": "origin/main",
      "official": true,
      "plugin": null,
      "fork": null,
      "id": "docker_manager",
      "version": "def456abc123...",
      "pretty_version": "v1.0.0",
      "url": "https://github.com/discourse/docker_manager",
      "upgrading": false,
      "upgrade_version": null
    }
  ],
  "upgrade_required": false
}
```

--------------------------------

### Compile Assets

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Command used to update themes and precompile assets.

```ruby
bundle exec rake themes:update assets:precompile
```

--------------------------------

### Fetch upgrade progress

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Retrieves the current upgrade progress for a specific list of repositories.

```javascript
const progress = await Repo.findAllProgress([repo1, repo2]);
console.log(`Progress: ${progress.percentage}%`);
```

--------------------------------

### Define UpgradeController Properties

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/controllers.md

Initializes the banner state and storage for banner messages.

```javascript
@tracked bannerDismissed = false;
banner = new TrackedArray();
```

--------------------------------

### Handle Git Command Failures

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/errors.md

Demonstrates how Git operations return nil on failure, requiring validation in consumer code.

```ruby
# ref-parse on detached HEAD returns nil
repo.run("rev-parse HEAD")  # => nil if detached

# fetch fails due to network
repo.run("fetch origin")  # => nil if network error

# checkout on invalid ref
repo.run("checkout nonexistent-branch")  # => nil if branch doesn't exist
```

```ruby
commit = repo.latest_local_commit
if commit.blank?
  # Git command failed
  # Handle gracefully
end
```

--------------------------------

### Access prettyLatestVersion property

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Retrieves a human-readable string for the remote version.

```javascript
get prettyLatestVersion()
```

--------------------------------

### Configure Web Server Port

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Sets the port for the Unicorn web server, which is used for status checks during the upgrade process.

```bash
export UNICORN_PORT=3000
```

--------------------------------

### Repos Method Definition

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/admin-controller.md

Defines the method to fetch repository information.

```ruby
def repos
```

--------------------------------

### Repo.findProgress()

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/repo-model.md

Retrieves the current status and progress of an ongoing upgrade.

```APIDOC
## Repo.findProgress()

### Description
Fetches the current progress of an upgrade operation.

### Returns
- **Promise<Object>** - Returns an object containing `status` (e.g., "running", "complete", "failed") and `percentage` (number).
```

--------------------------------

### Define Allowed Environment Variables

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

List of environment variables permitted to pass through to the upgrade subprocess.

```ruby
allowed_env = %w[
  PWD
  HOME
  SHELL
  PATH
  COMPRESS_BROTLI
  FORCE_S3_UPLOADS
  HTTP_PROXY
  HTTPS_PROXY
  NO_PROXY
  http_proxy
  https_proxy
  no_proxy
  EMBER_VERSION
]
```

--------------------------------

### Debug Failed Upgrades via CLI

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/README.md

Execute the failing command manually within the application directory to troubleshoot upgrade failures.

```bash
cd /var/www/discourse && {command}
```

--------------------------------

### Reload Web Server

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/api-reference/web-server-adapter.md

Performs a graceful server reload, including setting a restart flag and waiting for the server to become ready.

```ruby
adapter.reload
# Gracefully restarts web server with new code
```

--------------------------------

### Check Ruby Version

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Compares the current Ruby runtime version against the expected minimum version.

```ruby
ruby_version = Gem::Version.new(RUBY_VERSION)
expected_ruby_version = Gem::Version.new("3.4.10")
upgrade_ruby = ruby_version < expected_ruby_version
```

--------------------------------

### Configure Discourse Environment Variables

Source: https://github.com/discourse/docker_manager/blob/main/_autodocs/configuration.md

Set environment variables prefixed with DISCOURSE_ to pass configuration settings to the upgrade subprocess.

```bash
export DISCOURSE_SITE_URL=https://discourse.example.com
export DISCOURSE_SMTP_ADDRESS=smtp.example.com
# All DISCOURSE_* variables passed through to upgrade
```