Docker Language Server

The Docker Language Server is a language server for providing language features for file types in the Docker ecosystem (Dockerfiles, Compose files, and Bake files).

Requirements

The Docker Language Server relies on some features that are dependent on Buildx. If Buildx is not available as a Docker CLI plugin then those features will not be available.

Features

• Dockerfile
  • hover support for images to show vulnerability information from Docker Scout
  • suggested image tag updates from Docker Scout
  • Dockerfile linting support from BuildKit and Buildx
• Compose files
  • code completion
  • code navigation
  • document outline support
  • error reporting
  • formatting
  • highlight named references of services, networks, volumes, configs, and secrets
  • hover tooltips
  • inlay hints for overridden attribute values
  • open links to images
  • rename preparation
  • rename named references
• Bake files
  • code completion
  • code navigation
  • document outline support
  • error reporting
  • formatting
  • hover tooltips
  • inferring variable values

Installing

Ensure you have Go 1.24 or greater installed, check out this repository and then run make install. Alternatively you can run go install github.com/docker/docker-language-server/cmd/docker-language-server@latest to get the latest version.

Development

Building

Run make build to generate a binary of the Docker Language Server.

Linting

The Docker Language Server uses golangci-lint to lint the project. Run make lint to lint the project for issues.

Testing

Run make test to run the unit tests. If the BuildKit tests do not work, make sure that docker buildx build works from the command line.

If you would like to run the tests inside of a Docker container, run make test-docker which will build a Docker image with the test code and then execute the tests from within the Docker container. Note that this requires the Docker daemon's UNIX socket to be mounted.

Releasing

Follow the following steps to create a new release of the Docker Language Server:

1. Run the "prepare release" workflow with the desired bump in semantic versioning. This workflow will update CHANGELOG.md and cause a pull request to be created.
2. Review the generated pull request. Do not be alarmed that no automated build checks have been run for this pull request. As the changes should all be inside the CHANGELOG.md file, no code changes have actually happened so no build will be triggered.
   1. The change should update the "Unreleased" version header to the desired semantic version with today's date (based on UTC) appended to it.
   2. It will also update the link at the bottom of the Markdown for the purposes of comparing between the previous tag and the tag that will be created.
   3. If the above changes look good, approve the pull request and merge it manually.
3. As aforementioned, no builds will be triggered because the changes were made to a Markdown file. Use the "Run workflow" button to manually trigger the "build" workflow.
4. The workflow will run the tests, create the release, build the binaries, and attach the binaries to the release.
5. When the workflow has completed, open the releases page. It should have been automatically generated by the workflow and the resulting binaries should be attached to that release.

CLI Usage

The main command for docker-language-server is docker-language-server start with --stdio or --address :12345:

When run in stdio mode, requests and responses will be written to stdin and stdout. All logging is always written to stderr.

Language server for Docker

Usage:
  docker-language-server [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  start       Start the Docker LSP server

Flags:
      --debug     Enable debug logging
  -h, --help      help for docker-language-server
      --verbose   Enable verbose logging
  -v, --version   version for docker-language-server

Use "docker-language-server [command] --help" for more information about a command.

Language Server Configuration

Initialization Options

On startup, the client can include initialization options on the initial initialize request.

1. If the client is also using rcjsuen/dockerfile-language-server, then some results in textDocument/publishDiagnostics will be duplicated across the two language servers. By setting the experimental dockerfileExperimental.removeOverlappingIssues to true, the Docker Language Server will suppress the duplicated results. Note that this setting may be renamed or removed at any time.
2. Telemetry can be configured on server startup with the telemetry field. You can read more about this in TELEMETRY.md.
3. Compose support can be disabled on server initialization by setting the experimental dockercomposeExperimental.composeSupport attribute to false. The default value is true.

{
  "initializationOptions": {
    "dockercomposeExperimental": {
      "composeSupport:": true | false
    },
    "dockerfileExperimental": {
      "removeOverlappingIssues:": true | false
    },
    "telemetry": "all" | "error" | "off"
  }
}

Experimental Capabilities

To support textDocument/codeLens, the client must provide a command with the id dockerLspClient.bake.build for executing the build. If this is supported, the client can define its experimental capabilities as follows. The server will then respond that it supports code lens requests and return results for textDocument/codeLens requests for Bake HCL files.

{
  "capabilities": {
    "experimental:": {
      "dockerLanguageServerCapabilities": {
          "commands": [
            "dockerLspClient.bake.build"
          ]
      }
    }
  }
}

Supported Clients

The Docker Language Server team develops and maintains the Docker DX Visual Studio Code extension.

See CLIENTS.md for details about how to configure the Docker Language Server with other language clients.

Telemetry

See TELEMETRY.md for details about what kind of telemetry we collect and how to configure your telemetry settings.

tliron/glsp Fork

This project includes a fork of the tliron/glsp GitHub repository. The code can be found inside the internal/tliron/glsp folder.