DOCSEARCHbyAlgolia
Submit Docs

dockhand

repository·main·Indexed 24 days ago

https://github.com/finsys/dockhand

A modern Docker management application providing real-time container management, Compose stack orchestration, and multi-environment support. Features include Git integration for automated deployments, interactive shell access, real-time log streaming, and observability metrics for CPU, memory, and disk usage. It supports SSO via OIDC and provides a Collector binary for managing local and remote Docker hosts via JSON-line communication.

Tokens
4.7K
Snippets
6
Records
33
Agent score
91%

What's inside dockhand

  1. Overview of Dockhand features

    main

    Dockhand is a modern Docker management UI designed for real-time container management, Compose stack orchestration, and multi-environment support. Key capabilities include:

    • Container Management: Real-time monitoring and lifecycle control (start, stop, restart).
    • Compose Stacks: Visual editor for managing Docker Compose deployments.
    • Git Integration: Automated deployment and synchronization of stacks from Git repositories using webhooks.
    • Multi-Environment Support: Centralized management of both local and remote Docker hosts.
    • Interactive Tools: Real-time log streaming, interactive shell access (exec), and a file browser for containers and volumes.
    • Security & Auth: SSO via OIDC, local user management, and optional RBAC (Enterprise edition).
    • Observability: Live CPU, memory, and disk metrics, network graphs, and vulnerability scanning (Grype & Trivy).

  2. Manage Collector metrics and event modes

    main

    You can dynamically adjust the collection behavior of the Collector using the following commands via stdin:

    • Set metrics interval: Use set_metrics_interval with intervalMs to change how often CPU/Memory stats are collected.
    • Set event mode: Use set_event_mode to switch between stream (real-time Docker events) and poll (periodic event fetching). Use pollIntervalMs when in poll mode.

  3. Run the Production Server Wrapper

    main

    The server.js file acts as a production wrapper for the SvelteKit application (built via @sveltejs/adapter-node). It extends the standard HTTP server with WebSocket support for terminal execution (xterm.js ↔ Docker exec) and Hawser Edge agent connections.

    To run the server, use the following command:

    node ./server.js
    node ./server.js

  4. Deploy Dockhand using Docker Compose

    main

    You can deploy Dockhand using a docker-compose.yaml file. The setup requires mounting the host's Docker socket to allow the container to interact with the Docker daemon, and a named volume for persistent data storage.

    services:
  dockhand:
    image: fnsys/dockhand:latest
    container_name: dockhand
    restart: unless-stopped
    ports:
      - 3000:3000
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - dockhand_data:/app/data

volumes:
  dockhand_data:

  5. Configure Server Environment Variables

    main

    The server's behavior is controlled via several environment variables:

    VariableDefaultDescription
    PORT3000The port the server listens on.
    HOST0.0.0.0The host address to bind to.
    HTTPS_MODEoffSet to on to enable native TLS/HTTPS.
    HTTPS_CERT_PATHRequired if HTTPS_MODE=onPath to the PEM certificate file.
    HTTPS_KEY_PATHRequired if HTTPS_MODE=onPath to the PEM private key file.
    HTTPS_CA_PATHOptionalPath to the CA certificate file.
    HSTS_MAX_AGE31536000HSTS max-age in seconds. Set to 0 to disable.
    DOCKER_SOCKET/var/run/docker.sockPath to the local Docker socket (used for fallback).

  6. Configure Drizzle ORM for Dockhand

    main

    Dockhand uses drizzle-kit for database migrations and schema management. The configuration dynamically switches between PostgreSQL and SQLite based on the DATABASE_URL environment variable.

    • PostgreSQL Mode: Triggered if DATABASE_URL starts with postgres:// or postgresql://. It uses ./src/lib/server/db/schema/pg-schema.ts as the schema and outputs migrations to ./drizzle-pg.
    • SQLite Mode: Default mode. It uses ./src/lib/server/db/schema/index.ts as the schema and outputs migrations to ./drizzle. The database file location is determined by the DATA_DIR environment variable (defaulting to ./data/dockhand.db).
    import { defineConfig } from 'drizzle-kit';

const databaseUrl = process.env.DATABASE_URL;
const isPostgres = databaseUrl && (databaseUrl.startsWith('postgres://') || databaseUrl.startsWith('postgresql://'));

export default defineConfig({
	// Use different schema files for SQLite vs PostgreSQL
	schema: isPostgres
		? './src/lib/server/db/schema/pg-schema.ts'
		: './src/lib/server/db/schema/index.ts',
	out: isPostgres ? './drizzle-pg' : './drizzle',
	dialect: isPostgres ? 'postgresql' : 'sqlite',
	dbCredentials: isPostgres
		? { url: databaseUrl! }
		: { url: `file:${process.env.DATA_DIR || './data'}/dockhand.db` }
});

  10. Configure the DataGrid component props

    main

    The DataGridProps<T> interface defines the configuration for the reusable DataGrid component. It supports features like virtual scrolling, selection, sorting, and infinite loading.

    Required Props

    • data: An array of items of type T.
    • keyField: The key of type keyof T used to uniquely identify rows.
    • gridId: A unique GridId for the grid instance.

    Virtual Scroll & Infinite Loading

    • virtualScroll: Enables virtual scrolling (default: false).
    • rowHeight: The height of a single row in pixels.
    • bufferRows: Number of rows to buffer outside the visible area.
    • hasMore: Indicates if more data is available for infinite scrolling.
    • onLoadMore: Callback triggered when reaching the loadMoreThreshold.
    • loadMoreThreshold: The number of rows from the bottom to trigger onLoadMore.

    Selection & Interaction

    • selectable: Enables row selection.
    • selectedKeys: A Set<unknown> containing the keys of currently selected rows.
    • onSelectionChange: Callback function (keys: Set<unknown>) => void triggered when selection changes.
    • onRowClick: Callback (item: T, event: MouseEvent) => void triggered when a row is clicked.
    • highlightedKey: The key of the currently highlighted row.
    • rowClass: A function (item: T) => string to apply custom CSS classes to rows.

    Sorting

    • sortState: The current DataGridSortState.
    • onSortChange: Callback (state: DataGridSortState) => void triggered when sorting changes.

    Customization Snippets

    Use Svelte snippets to override default rendering:

    • headerCell: Snippet<[ColumnConfig, DataGridSortState | undefined]>
    • cell: Snippet<[ColumnConfig, T, DataGridRowState]>
    • emptyState: Snippet
    • loadingState: Snippet

  11. Manage sidebar state with setSidebar and useSidebar

    main

    To manage the sidebar's open/closed state across components, use setSidebar to initialize the state in a parent component and useSidebar to access it in child components.

    setSidebar requires a SidebarStateProps object containing:

    • open: A getter function () => boolean to track the current state (enables bind:open support).
    • setOpen: A function (open: boolean) => void to update the state.

    useSidebar returns a SidebarState instance. Note that SidebarState is a class instance; you should not destructure it directly to avoid losing reactivity.

  12. Use the columnResize Svelte action

    main

    The columnResize Svelte action enables column resizing functionality on an HTML element (typically a resize handle div). It tracks mouse movements to calculate new widths and triggers callbacks.

    To use it, apply the action to a resize handle element using the use:columnResize directive. If you are implementing a left-side resize handle, ensure the element has the CSS class resize-handle-left so the delta calculation is inverted correctly.