iop/dist/docker/index.d.ts

Ship Docker Anywhere

import { SSHClient } from "../ssh";
import { ServiceEntry, IopSecrets } from "../config/types";
export interface DockerNetworkOptions {
    name: string;
}
export interface DockerContainerOptions {
    name: string;
    image: string;
    network?: string;
    networkAliases?: string[];
    ports?: string[];
    volumes?: string[];
    envVars?: Record<string, string>;
    restart?: string;
    labels?: Record<string, string>;
    configHash?: string;
    command?: string;
    logDriver?: string;
    logOpts?: Record<string, string>;
}
export interface DockerBuildOptions {
    context: string;
    dockerfile?: string;
    tags?: string[];
    buildArgs?: Record<string, string>;
    target?: string;
    platform?: string;
    verbose?: boolean;
}
export declare class DockerClient {
    private sshClient?;
    private serverHostname?;
    private verbose;
    constructor(sshClient?: SSHClient, serverHostname?: string, verbose?: boolean);
    /**
     * Log a message with server hostname prefix or general log if no server context
     */
    private log;
    /**
     * Log a warning with server hostname prefix or general warning if no server context
     */
    private logWarn;
    /**
     * Log an error with server hostname prefix or general error if no server context
     */
    private logError;
    /**
     * Execute a Docker command via SSH if sshClient is available
     */
    private execRemote;
    /**
     * Execute a command locally
     */
    private static _runLocalCommand;
    static build(options: DockerBuildOptions): Promise<void>;
    static tag(sourceImage: string, targetImage: string, verbose?: boolean): Promise<void>;
    /**
     * Save a Docker image to a tar archive
     */
    static save(imageName: string, outputPath: string, verbose?: boolean): Promise<void>;
    /**
     * Save a Docker image to a compressed tar.gz archive for faster transfer
     * Tries pigz (parallel gzip) first for faster compression, falls back to gzip, then uncompressed tar
     */
    static saveCompressed(imageName: string, outputPath: string, verbose?: boolean): Promise<void>;
    static push(imageName: string, registry?: string, verbose?: boolean): Promise<void>;
    /**
     * Check if Docker is installed and working on remote server
     */
    checkInstallation(): Promise<boolean>;
    /**
     * Install Docker if not already installed on remote server
     */
    install(): Promise<boolean>;
    /**
     * Login to Docker registry
     */
    login(registry: string, username: string, password: string): Promise<boolean>;
    /**
     * Logout from Docker registry
     */
    logout(registry: string): Promise<boolean>;
    /**
     * Pull a Docker image
     */
    pullImage(image: string): Promise<boolean>;
    /**
     * Force pull a Docker image, ensuring we get the latest version from the registry
     * This removes the image first if it exists locally, then pulls it again
     */
    forcePullImage(image: string): Promise<boolean>;
    /**
     * Load a Docker image from a tar archive
     */
    loadImage(archivePath: string): Promise<boolean>;
    /**
     * Load a Docker image from a compressed tar.gz archive
     * Tries pigz (parallel decompression) first, then gunzip, then uncompressed fallback
     */
    loadCompressedImage(archivePath: string): Promise<boolean>;
    /**
     * Check if a network exists
     */
    networkExists(name: string): Promise<boolean>;
    /**
     * Create a Docker network
     */
    createNetwork(options: DockerNetworkOptions): Promise<boolean>;
    /**
     * Check if a container is connected to a specific network
     */
    isContainerConnectedToNetwork(containerName: string, networkName: string): Promise<boolean>;
    /**
     * Connect a container to a network
     */
    connectContainerToNetwork(containerName: string, networkName: string): Promise<boolean>;
    /**
     * Check if a container exists
     */
    containerExists(name: string): Promise<boolean>;
    /**
     * Check if a container is running
     */
    containerIsRunning(name: string): Promise<boolean>;
    /**
     * Start an existing container
     */
    startContainer(name: string): Promise<boolean>;
    /**
     * Stop a container
     */
    stopContainer(name: string): Promise<boolean>;
    /**
     * Remove a container
     */
    removeContainer(name: string): Promise<boolean>;
    /**
     * Create and run a new container
     */
    createContainer(options: DockerContainerOptions): Promise<boolean>;
    /**
     * Ensure a container is running - creates it if it doesn't exist, starts it if stopped
     */
    ensureContainer(options: DockerContainerOptions): Promise<boolean>;
    /**
     * Get the health status of a container.
     * Returns 'healthy', 'unhealthy', 'starting', or null if health status is not available.
     */
    getContainerHealth(containerName: string): Promise<string | null>;
    /**
     * Find all containers (running or stopped) whose names match a prefix
     * @param namePrefix The container name prefix to match
     * @returns Array of container names
     */
    findContainersByPrefix(namePrefix: string): Promise<string[]>;
    /**
     * Run a health check using project-specific DNS targets
     * @param proxyContainerName Name of the iop-proxy container (should be "iop-proxy")
     * @param targetNetworkAlias Network alias of the container to check (e.g., "web") - DEPRECATED, use projectSpecificTarget
     * @param targetContainerName Name of the container to check
     * @param projectName The project name for network isolation
     * @param appPort The port the app is listening on (default: 80)
     * @param healthCheckPath The health check endpoint path (default: "/up")
     * @returns true if the health check endpoint returns 200, false otherwise
     */
    checkHealthWithIopProxy(proxyContainerName: string, targetNetworkAlias: string, targetContainerName: string, projectName: string, appPort?: number, healthCheckPath?: string): Promise<boolean>;
    /**
     * Execute a command inside a running container
     */
    execInContainer(containerName: string, command: string): Promise<{
        success: boolean;
        output: string;
    }>;
    /**
     * Prune unused Docker resources (containers, networks, images, build cache) on the remote server.
     */
    prune(): Promise<boolean>;
    /**
     * Prune all unused Docker images on the remote server.
     */
    pruneImages(): Promise<boolean>;
    /**
     * Check available disk space and return info about usage
     */
    checkDiskSpace(): Promise<{
        available: number;
        used: number;
        total: number;
        usedPercent: number;
    }>;
    /**
     * Clean up old iop deployment artifacts from /tmp
     */
    cleanupTempFiles(): Promise<boolean>;
    /**
     * Perform comprehensive disk cleanup before deployment
     */
    performPreDeploymentCleanup(): Promise<{
        success: boolean;
        spaceBefore: number;
        spaceAfter: number;
        tempFilesCleanedUp: boolean;
        dockerImagesCleanedUp: boolean;
    }>;
    /**
     * Inspect a container and return its configuration
     */
    inspectContainer(containerName: string): Promise<any>;
    /**
     * Convert a iop service definition to Docker container options
     */
    static serviceToContainerOptions(service: ServiceEntry, projectName: string, secrets: IopSecrets): DockerContainerOptions;
    /**
     * Find containers by label filter
     * @param labelFilter Docker label filter string (e.g., "iop.app=blog", "iop.color=blue")
     * @returns Array of container names matching the filter
     */
    findContainersByLabel(labelFilter: string): Promise<string[]>;
    /**
     * Find containers by label filter within a specific project
     * @param labelFilter Docker label filter string (e.g., "iop.app=web", "iop.color=blue")
     * @param projectName Project name to scope the search to
     * @returns Array of container names matching the filter within the project
     */
    findContainersByLabelAndProject(labelFilter: string, projectName: string): Promise<string[]>;
    /**
     * Get container labels
     * @param containerName Name of the container
     * @returns Object with container labels or empty object if none found
     */
    getContainerLabels(containerName: string): Promise<Record<string, string>>;
    /**
     * Determines the current active color (blue/green) for an app
     * @param appName Name of the app
     * @returns 'blue', 'green', or null if no containers exist
     */
    getCurrentActiveColor(appName: string): Promise<"blue" | "green" | null>;
    /**
     * Determines the current active color (blue/green) for an app within a specific project
     * @param appName Name of the app
     * @param projectName Project name to scope the search to
     * @returns 'blue', 'green', or null if no containers exist
     */
    getCurrentActiveColorForProject(appName: string, projectName: string): Promise<"blue" | "green" | null>;
    /**
     * Gets the inactive color (opposite of current active)
     * @param appName Name of the app
     * @returns 'blue' or 'green' - the color that should be used for new deployment
     */
    getInactiveColor(appName: string): Promise<"blue" | "green">;
    /**
     * Gets the inactive color (opposite of current active) for a specific project
     * @param appName Name of the app
     * @param projectName Project name to scope the search to
     * @returns 'blue' or 'green' - the color that should be used for new deployment
     */
    getInactiveColorForProject(appName: string, projectName: string): Promise<"blue" | "green">;
    /**
     * Creates a container with zero-downtime deployment labels
     * @param options Standard container options
     * @param appName Application name
     * @param color Color for this deployment (blue/green)
     * @param replicaIndex Replica index (1-based)
     * @param active Whether this container is currently active
     * @returns true if container was created successfully
     */
    createContainerWithLabels(options: DockerContainerOptions, appName: string, color: "blue" | "green", replicaIndex: number, active: boolean): Promise<boolean>;
    /**
     * Switches network aliases from old color to new color atomically
     * @param appName Name of the app
     * @param newColor The color to switch to
     * @param networkName The network name
     * @returns true if successful
     */
    switchNetworkAlias(appName: string, newColor: "blue" | "green", networkName: string): Promise<boolean>;
    /**
     * Switches network aliases from old color to new color atomically within a specific project
     * @param appName Name of the app
     * @param newColor The color to switch to
     * @param networkName The network name
     * @param projectName Project name to scope the search to
     * @returns true if successful
     */
    switchNetworkAliasForProject(appName: string, newColor: "blue" | "green", networkName: string, projectName: string): Promise<boolean>;
    /**
     * Updates container labels to mark them as active/inactive
     * Note: Docker doesn't support updating labels after container creation,
     * so this function is a no-op. Labels are set correctly during creation.
     * @param appName Name of the app
     * @param activeColor The color to mark as active
     * @returns true (always successful since labels are set during creation)
     */
    updateActiveLabels(appName: string, activeColor: "blue" | "green"): Promise<boolean>;
    /**
     * Performs graceful shutdown of containers with SIGTERM
     * @param containerNames Array of container names to shut down
     * @param gracefulTimeoutSeconds Time to wait for graceful shutdown (default: 30)
     * @returns true if all containers shut down successfully
     */
    gracefulShutdown(containerNames: string[], gracefulTimeoutSeconds?: number): Promise<boolean>;
    /**
     * Find all containers managed by iop for a specific project
     * @param projectName The project name to filter by
     * @returns Array of container names belonging to the project
     */
    findProjectContainers(projectName: string): Promise<string[]>;
    /**
     * Find all app containers for a specific project
     * @param projectName The project name to filter by
     * @returns Array of container names for apps in the project
     */
    findProjectAppContainers(projectName: string): Promise<string[]>;
    /**
     * Find all service containers for a specific project
     * @param projectName The project name to filter by
     * @returns Array of container names for services in the project
     */
    findProjectServiceContainers(projectName: string): Promise<string[]>;
    /**
     * Get detailed information about a project's containers
     * @param projectName The project name to analyze
     * @returns Object with apps and services currently deployed
     */
    getProjectCurrentState(projectName: string): Promise<{
        apps: Record<string, string[]>;
        services: Record<string, string>;
    }>;
    /**
     * Get container uptime in a human-readable format
     * @param containerName Name of the container
     * @returns Human-readable uptime string (e.g., "2h 15m", "3 days") or null if error
     */
    getContainerUptime(containerName: string): Promise<string | null>;
    /**
     * Get container resource usage (CPU and memory)
     * @param containerName Name of the container
     * @returns Object with CPU and memory usage or null if error
     */
    getContainerStats(containerName: string): Promise<{
        cpuPercent: string;
        memoryUsage: string;
        memoryPercent: string;
    } | null>;
    /**
     * Get detailed container information for status display
     * @param containerName Name of the container
     * @returns Detailed container info or null if error
     */
    getContainerDetails(containerName: string): Promise<{
        uptime: string | null;
        stats: {
            cpuPercent: string;
            memoryUsage: string;
            memoryPercent: string;
        } | null;
        image: string | null;
        createdAt: string | null;
        restartCount: number;
        exitCode: number | null;
        ports: string[];
        volumes: Array<{
            source: string;
            destination: string;
            mode?: string;
        }>;
    } | null>;
}
/**
 * Create logging configuration for proxy containers (5MB max size, 5 files)
 */
export declare function createProxyLoggingConfig(): {
    logDriver: string;
    logOpts: Record<string, string>;
};
/**
 * Create logging configuration for user service containers (10MB max size, 3 files)
 */
export declare function createServiceLoggingConfig(): {
    logDriver: string;
    logOpts: Record<string, string>;
};