compose install

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>

__tests__/compose/compose.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Copyright 2025 actions-toolkit authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {describe, expect, it, jest, test, afterEach} from '@jest/globals';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import * as rimraf from 'rimraf';
+import * as semver from 'semver';
+
+import {Context} from '../../src/context';
+import {Exec} from '../../src/exec';
+
+import {Compose} from '../../src/compose/compose';
+
+const tmpDir = fs.mkdtempSync(path.join(process.env.TEMP || os.tmpdir(), 'compose-compose-'));
+const tmpName = path.join(tmpDir, '.tmpname-jest');
+
+jest.spyOn(Context, 'tmpDir').mockImplementation((): string => {
+  fs.mkdirSync(tmpDir, {recursive: true});
+  return tmpDir;
+});
+
+jest.spyOn(Context, 'tmpName').mockImplementation((): string => {
+  return tmpName;
+});
+
+afterEach(() => {
+  rimraf.sync(tmpDir);
+});
+
+describe('isAvailable', () => {
+  it('docker cli', async () => {
+    const execSpy = jest.spyOn(Exec, 'getExecOutput');
+    const compose = new Compose({
+      standalone: false
+    });
+    await compose.isAvailable();
+    // eslint-disable-next-line jest/no-standalone-expect
+    expect(execSpy).toHaveBeenCalledWith(`docker`, ['compose'], {
+      silent: true,
+      ignoreReturnCode: true
+    });
+  });
+  it('standalone', async () => {
+    const execSpy = jest.spyOn(Exec, 'getExecOutput');
+    const compose = new Compose({
+      standalone: true
+    });
+    await compose.isAvailable();
+    // eslint-disable-next-line jest/no-standalone-expect
+    expect(execSpy).toHaveBeenCalledWith(`compose`, [], {
+      silent: true,
+      ignoreReturnCode: true
+    });
+  });
+});
+
+describe('printVersion', () => {
+  it('docker cli', async () => {
+    const execSpy = jest.spyOn(Exec, 'exec');
+    const compose = new Compose({
+      standalone: false
+    });
+    await compose.printVersion();
+    expect(execSpy).toHaveBeenCalledWith(`docker`, ['compose', 'version'], {
+      failOnStdErr: false
+    });
+  });
+  it('standalone', async () => {
+    const execSpy = jest.spyOn(Exec, 'exec');
+    const compose = new Compose({
+      standalone: true
+    });
+    await compose.printVersion();
+    expect(execSpy).toHaveBeenCalledWith(`compose`, ['version'], {
+      failOnStdErr: false
+    });
+  });
+});
+
+describe('version', () => {
+  it('valid', async () => {
+    const compose = new Compose();
+    expect(semver.valid(await compose.version())).not.toBeUndefined();
+  });
+});
+
+describe('parseVersion', () => {
+  // prettier-ignore
+  test.each([
+    ['Docker Compose version v2.31.0', '2.31.0'],
+  ])('given %p', async (stdout, expected) => {
+    expect(Compose.parseVersion(stdout)).toEqual(expected);
+  });
+});

__tests__/compose/install.test.itg.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2025 actions-toolkit authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {describe, expect, test} from '@jest/globals';
+import * as fs from 'fs';
+
+import {Install} from '../../src/compose/install';
+
+const maybe = !process.env.GITHUB_ACTIONS || (process.env.GITHUB_ACTIONS === 'true' && process.env.ImageOS && process.env.ImageOS.startsWith('ubuntu')) ? describe : describe.skip;
+
+maybe('download', () => {
+  // prettier-ignore
+  test.each(['latest'])(
+    'install compose %s', async (version) => {
+      await expect((async () => {
+        const install = new Install({
+          standalone: true
+        });
+        const toolPath = await install.download(version);
+        if (!fs.existsSync(toolPath)) {
+          throw new Error('toolPath does not exist');
+        }
+        const binPath = await install.installStandalone(toolPath);
+        if (!fs.existsSync(binPath)) {
+          throw new Error('binPath does not exist');
+        }
+      })()).resolves.not.toThrow();
+    }, 60000);
+});

__tests__/compose/install.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Copyright 2025 actions-toolkit authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {describe, expect, it, jest, test, afterEach} from '@jest/globals';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import * as rimraf from 'rimraf';
+import osm = require('os');
+
+import {Install} from '../../src/compose/install';
+
+const tmpDir = fs.mkdtempSync(path.join(process.env.TEMP || os.tmpdir(), 'compose-install-'));
+
+afterEach(function () {
+  rimraf.sync(tmpDir);
+});
+
+describe('download', () => {
+  // prettier-ignore
+  test.each([
+    ['v2.31.0', false],
+    ['v2.32.4', true],
+    ['latest', true]
+  ])(
+  'acquires %p of compose (standalone: %p)', async (version, standalone) => {
+      const install = new Install({standalone: standalone});
+      const toolPath = await install.download(version);
+      expect(fs.existsSync(toolPath)).toBe(true);
+      let composeBin: string;
+      if (standalone) {
+        composeBin = await install.installStandalone(toolPath, tmpDir);
+      } else {
+        composeBin = await install.installPlugin(toolPath, tmpDir);
+      }
+      expect(fs.existsSync(composeBin)).toBe(true);
+    },
+    100000
+  );
+
+  // prettier-ignore
+  test.each([
+    // following versions are already cached to htc from previous test cases
+    ['v2.31.0'],
+    ['v2.32.4'],
+  ])(
+  'acquires %p of compose with cache', async (version) => {
+    const install = new Install({standalone: false});
+    const toolPath = await install.download(version);
+    expect(fs.existsSync(toolPath)).toBe(true);
+  });
+
+  // prettier-ignore
+  test.each([
+    ['v2.27.1'],
+    ['v2.28.0'],
+  ])(
+  'acquires %p of compose without cache', async (version) => {
+    const install = new Install({standalone: false});
+    const toolPath = await install.download(version, true);
+    expect(fs.existsSync(toolPath)).toBe(true);
+  });
+
+  // TODO: add tests for arm
+  // prettier-ignore
+  test.each([
+    ['win32', 'x64'],
+    ['win32', 'arm64'],
+    ['darwin', 'x64'],
+    ['darwin', 'arm64'],
+    ['linux', 'x64'],
+    ['linux', 'arm64'],
+    ['linux', 'ppc64'],
+    ['linux', 's390x'],
+  ])(
+  'acquires compose for %s/%s', async (os, arch) => {
+      jest.spyOn(osm, 'platform').mockImplementation(() => os as NodeJS.Platform);
+      jest.spyOn(osm, 'arch').mockImplementation(() => arch);
+      const install = new Install();
+      const composeBin = await install.download('latest');
+      expect(fs.existsSync(composeBin)).toBe(true);
+    },
+    100000
+  );
+});
+
+describe('getDownloadVersion', () => {
+  it('returns latest download version', async () => {
+    const version = await Install.getDownloadVersion('latest');
+    expect(version.version).toEqual('latest');
+    expect(version.downloadURL).toEqual('https://github.com/docker/compose/releases/download/v%s/%s');
+    expect(version.releasesURL).toEqual('https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/compose-releases.json');
+  });
+  it('returns v2.24.3 download version', async () => {
+    const version = await Install.getDownloadVersion('v2.24.3');
+    expect(version.version).toEqual('v2.24.3');
+    expect(version.downloadURL).toEqual('https://github.com/docker/compose/releases/download/v%s/%s');
+    expect(version.releasesURL).toEqual('https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/compose-releases.json');
+  });
+});
+
+describe('getRelease', () => {
+  it('returns latest GitHub release', async () => {
+    const version = await Install.getDownloadVersion('latest');
+    const release = await Install.getRelease(version);
+    expect(release).not.toBeNull();
+    expect(release?.tag_name).not.toEqual('');
+  });
+  it('returns v2.24.3 GitHub release', async () => {
+    const version = await Install.getDownloadVersion('v2.24.3');
+    const release = await Install.getRelease(version);
+    expect(release).not.toBeNull();
+    expect(release?.id).toEqual(138380726);
+    expect(release?.tag_name).toEqual('v2.24.3');
+    expect(release?.html_url).toEqual('https://github.com/docker/compose/releases/tag/v2.24.3');
+  });
+  it('unknown release', async () => {
+    const version = await Install.getDownloadVersion('foo');
+    await expect(Install.getRelease(version)).rejects.toThrow(new Error('Cannot find Compose release foo in https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/compose-releases.json'));
+  });
+});

dev.Dockerfile

@@ -17,6 +17,7 @@
 ARG NODE_VERSION=20
 ARG DOCKER_VERSION=27.2.1
 ARG BUILDX_VERSION=0.19.3
+ARG COMPOSE_VERSION=2.32.4
 ARG UNDOCK_VERSION=0.8.0
 
 FROM node:${NODE_VERSION}-alpine AS base
@@ -76,6 +77,7 @@ RUN --mount=type=bind,target=.,rw \
 
 FROM docker:${DOCKER_VERSION} AS docker
 FROM docker/buildx-bin:${BUILDX_VERSION} AS buildx
+FROM docker/compose-bin:v${COMPOSE_VERSION} AS compose
 FROM crazymax/undock:${UNDOCK_VERSION} AS undock
 
 FROM deps AS test
@@ -85,6 +87,8 @@ RUN --mount=type=bind,target=.,rw \
     --mount=type=bind,from=docker,source=/usr/local/bin/docker,target=/usr/bin/docker \
     --mount=type=bind,from=buildx,source=/buildx,target=/usr/libexec/docker/cli-plugins/docker-buildx \
     --mount=type=bind,from=buildx,source=/buildx,target=/usr/bin/buildx \
+    --mount=type=bind,from=compose,source=/docker-compose,target=/usr/libexec/docker/cli-plugins/docker-compose \
+    --mount=type=bind,from=compose,source=/docker-compose,target=/usr/bin/compose \
     --mount=type=bind,from=undock,source=/usr/local/bin/undock,target=/usr/bin/undock \
     --mount=type=secret,id=GITHUB_TOKEN \
   GITHUB_TOKEN=$(cat /run/secrets/GITHUB_TOKEN) yarn run test:coverage --coverageDirectory=/tmp/coverage

src/compose/compose.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright 2025 actions-toolkit authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as core from '@actions/core';
+
+import {Docker} from '../docker/docker';
+import {Exec} from '../exec';
+
+export interface ComposeOpts {
+  standalone?: boolean;
+}
+
+export class Compose {
+  private _version: string;
+  private _versionOnce: boolean;
+  private readonly _standalone: boolean | undefined;
+
+  constructor(opts?: ComposeOpts) {
+    this._standalone = opts?.standalone;
+    this._version = '';
+    this._versionOnce = false;
+  }
+
+  public async isStandalone(): Promise<boolean> {
+    const standalone = this._standalone ?? !(await Docker.isAvailable());
+    core.debug(`Compose.isStandalone: ${standalone}`);
+    return standalone;
+  }
+
+  public async getCommand(args: Array<string>) {
+    const standalone = await this.isStandalone();
+    return {
+      command: standalone ? 'compose' : 'docker',
+      args: standalone ? args : ['compose', ...args]
+    };
+  }
+
+  public async isAvailable(): Promise<boolean> {
+    const cmd = await this.getCommand([]);
+
+    const ok: boolean = await Exec.getExecOutput(cmd.command, cmd.args, {
+      ignoreReturnCode: true,
+      silent: true
+    })
+      .then(res => {
+        if (res.stderr.length > 0 && res.exitCode != 0) {
+          core.debug(`Compose.isAvailable cmd err: ${res.stderr.trim()}`);
+          return false;
+        }
+        return res.exitCode == 0;
+      })
+      .catch(error => {
+        core.debug(`Compose.isAvailable error: ${error}`);
+        return false;
+      });
+
+    core.debug(`Compose.isAvailable: ${ok}`);
+    return ok;
+  }
+
+  public async version(): Promise<string> {
+    if (this._versionOnce) {
+      return this._version;
+    }
+    this._versionOnce = true;
+    const cmd = await this.getCommand(['version']);
+    this._version = await Exec.getExecOutput(cmd.command, cmd.args, {
+      ignoreReturnCode: true,
+      silent: true
+    }).then(res => {
+      if (res.stderr.length > 0 && res.exitCode != 0) {
+        throw new Error(res.stderr.trim());
+      }
+      return Compose.parseVersion(res.stdout.trim());
+    });
+    return this._version;
+  }
+
+  public async printVersion() {
+    const cmd = await this.getCommand(['version']);
+    await Exec.exec(cmd.command, cmd.args, {
+      failOnStdErr: false
+    });
+  }
+
+  public static parseVersion(stdout: string): string {
+    const matches = /\sv?([0-9a-f]{7}|[0-9.]+)/.exec(stdout);
+    if (!matches) {
+      throw new Error(`Cannot parse compose version`);
+    }
+    return matches[1];
+  }
+}

src/compose/install.ts

@@ -0,0 +1,196 @@
+/**
+ * Copyright 2025 actions-toolkit authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import * as core from '@actions/core';
+import * as httpm from '@actions/http-client';
+import * as tc from '@actions/tool-cache';
+import * as semver from 'semver';
+import * as util from 'util';
+
+import {Cache} from '../cache';
+import {Context} from '../context';
+
+import {DownloadVersion} from '../types/compose/compose';
+import {GitHubRelease} from '../types/github';
+import {Docker} from '../docker/docker';
+
+export interface InstallOpts {
+  standalone?: boolean;
+}
+
+export class Install {
+  private readonly _standalone: boolean | undefined;
+
+  constructor(opts?: InstallOpts) {
+    this._standalone = opts?.standalone;
+  }
+
+  /*
+   * Download compose binary from GitHub release
+   * @param v: version semver version or latest
+   * @param ghaNoCache: disable binary caching in GitHub Actions cache backend
+   * @returns path to the compose binary
+   */
+  public async download(v: string, ghaNoCache?: boolean): Promise<string> {
+    const version: DownloadVersion = await Install.getDownloadVersion(v);
+    core.debug(`Install.download version: ${version.version}`);
+
+    const release: GitHubRelease = await Install.getRelease(version);
+    core.debug(`Install.download release tag name: ${release.tag_name}`);
+
+    const vspec = await this.vspec(release.tag_name);
+    core.debug(`Install.download vspec: ${vspec}`);
+
+    const c = semver.clean(vspec) || '';
+    if (!semver.valid(c)) {
+      throw new Error(`Invalid Compose version "${vspec}".`);
+    }
+
+    const installCache = new Cache({
+      htcName: 'compose-dl-bin',
+      htcVersion: vspec,
+      baseCacheDir: path.join(os.homedir(), '.bin'),
+      cacheFile: os.platform() == 'win32' ? 'docker-compose.exe' : 'docker-compose',
+      ghaNoCache: ghaNoCache
+    });
+
+    const cacheFoundPath = await installCache.find();
+    if (cacheFoundPath) {
+      core.info(`Compose binary found in ${cacheFoundPath}`);
+      return cacheFoundPath;
+    }
+
+    const downloadURL = util.format(version.downloadURL, vspec, this.filename());
+    core.info(`Downloading ${downloadURL}`);
+
+    const htcDownloadPath = await tc.downloadTool(downloadURL);
+    core.debug(`Install.download htcDownloadPath: ${htcDownloadPath}`);
+
+    const cacheSavePath = await installCache.save(htcDownloadPath);
+    core.info(`Cached to ${cacheSavePath}`);
+    return cacheSavePath;
+  }
+
+  public async installStandalone(binPath: string, dest?: string): Promise<string> {
+    core.info('Standalone mode');
+    dest = dest || Context.tmpDir();
+
+    const binDir = path.join(dest, 'compose-bin-standalone');
+    if (!fs.existsSync(binDir)) {
+      fs.mkdirSync(binDir, {recursive: true});
+    }
+    const binName: string = os.platform() == 'win32' ? 'compose.exe' : 'compose';
+    const composePath: string = path.join(binDir, binName);
+    fs.copyFileSync(binPath, composePath);
+
+    core.info('Fixing perms');
+    fs.chmodSync(composePath, '0755');
+
+    core.addPath(binDir);
+    core.info('Added Compose to PATH');
+
+    core.info(`Binary path: ${composePath}`);
+    return composePath;
+  }
+
+  public async installPlugin(binPath: string, dest?: string): Promise<string> {
+    core.info('Docker plugin mode');
+    dest = dest || Docker.configDir;
+
+    const pluginsDir: string = path.join(dest, 'cli-plugins');
+    if (!fs.existsSync(pluginsDir)) {
+      fs.mkdirSync(pluginsDir, {recursive: true});
+    }
+    const binName: string = os.platform() == 'win32' ? 'docker-compose.exe' : 'docker-compose';
+    const pluginPath: string = path.join(pluginsDir, binName);
+    fs.copyFileSync(binPath, pluginPath);
+
+    core.info('Fixing perms');
+    fs.chmodSync(pluginPath, '0755');
+
+    core.info(`Plugin path: ${pluginPath}`);
+    return pluginPath;
+  }
+
+  private async isStandalone(): Promise<boolean> {
+    const standalone = this._standalone ?? !(await Docker.isAvailable());
+    core.debug(`Install.isStandalone: ${standalone}`);
+    return standalone;
+  }
+
+  private filename(): string {
+    let arch: string;
+    switch (os.arch()) {
+      case 'x64': {
+        arch = 'x86_64';
+        break;
+      }
+      case 'ppc64': {
+        arch = 'ppc64le';
+        break;
+      }
+      case 'arm': {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const arm_version = (process.config.variables as any).arm_version;
+        arch = arm_version ? 'armv' + arm_version : 'arm';
+        break;
+      }
+      case 'arm64': {
+        arch = 'aarch64';
+        break;
+      }
+      default: {
+        arch = os.arch();
+        break;
+      }
+    }
+    const platform: string = os.platform() == 'win32' ? 'windows' : os.platform();
+    const ext: string = os.platform() == 'win32' ? '.exe' : '';
+    return util.format('docker-compose-%s-%s%s', platform, arch, ext);
+  }
+
+  private async vspec(version: string): Promise<string> {
+    const v = version.replace(/^v+|v+$/g, '');
+    core.info(`Use ${v} version spec cache key for ${version}`);
+    return v;
+  }
+
+  public static async getDownloadVersion(v: string): Promise<DownloadVersion> {
+    return {
+      version: v,
+      downloadURL: 'https://github.com/docker/compose/releases/download/v%s/%s',
+      releasesURL: 'https://raw.githubusercontent.com/docker/actions-toolkit/main/.github/compose-releases.json'
+    };
+  }
+
+  public static async getRelease(version: DownloadVersion): Promise<GitHubRelease> {
+    const http: httpm.HttpClient = new httpm.HttpClient('docker-actions-toolkit');
+    const resp: httpm.HttpClientResponse = await http.get(version.releasesURL);
+    const body = await resp.readBody();
+    const statusCode = resp.message.statusCode || 500;
+    if (statusCode >= 400) {
+      throw new Error(`Failed to get Compose releases from ${version.releasesURL} with status code ${statusCode}: ${body}`);
+    }
+    const releases = <Record<string, GitHubRelease>>JSON.parse(body);
+    if (!releases[version.version]) {
+      throw new Error(`Cannot find Compose release ${version.version} in ${version.releasesURL}`);
+    }
+    return releases[version.version];
+  }
+}

src/toolkit.ts

@@ -20,6 +20,8 @@ import {Bake as BuildxBake} from './buildx/bake';
 import {Install as BuildxInstall} from './buildx/install';
 import {Builder} from './buildx/builder';
 import {BuildKit} from './buildkit/buildkit';
+import {Compose} from './compose/compose';
+import {Install as ComposeInstall} from './compose/install';
 import {Undock} from './undock/undock';
 import {GitHub} from './github';
 
@@ -39,6 +41,8 @@ export class Toolkit {
   public buildxInstall: BuildxInstall;
   public builder: Builder;
   public buildkit: BuildKit;
+  public compose: Compose;
+  public composeInstall: ComposeInstall;
   public undock: Undock;
 
   constructor(opts: ToolkitOpts = {}) {
@@ -49,6 +53,8 @@ export class Toolkit {
     this.buildxInstall = new BuildxInstall();
     this.builder = new Builder({buildx: this.buildx});
     this.buildkit = new BuildKit({buildx: this.buildx});
+    this.compose = new Compose();
+    this.composeInstall = new ComposeInstall();
     this.undock = new Undock();
   }
 }

src/types/compose/compose.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright 2025 actions-toolkit authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export interface DownloadVersion {
+  version: string;
+  downloadURL: string;
+  releasesURL: string;
+}