#+ATTR_HTML: align="center"; margin-right="auto"; margin-left="auto"
=lsp-mode= uses =lsp-docker= to run language servers using in containers

[[./images/logo.png]]

* Table of Contents                                       :TOC_4_gh:noexport:
  - [[#preconfigured-language-servers][Preconfigured language servers]]
  - [[#usage][Usage]]
    - [[#emacslsplsp-docker-langservers][emacslsp/lsp-docker-langservers]]
      - [[#configuration][Configuration]]
      - [[#how-it-works][How it works]]
    - [[#emacslsplsp-docker-full][emacslsp/lsp-docker-full]]
      - [[#flags][Flags]]
        - [[#emacs][Emacs]]
        - [[#spacemacs][Spacemacs]]
  - [[#docker-over-tramp-tbd][Docker over TRAMP (TBD)]]
  - [[#see-also][See also]]
  - [[#maintainers][Maintainers]]

** Preconfigured language servers
   =emacslsp/lsp-docker-langservers= has the following content:
   - Language servers:
     | Language              | Language Server                   |
     |-----------------------+-----------------------------------|
     | Bash                  | [[https://github.com/mads-hartmann/bash-language-server][bash-language-server]]              |
     | C++                   | [[https://github.com/MaskRay/ccls][ccls]]                              |
     | CSS/LessCSS/SASS/SCSS | [[https://github.com/vscode-langservers/vscode-css-languageserver-bin][css]]                               |
     | Dockerfile            | [[https://github.com/rcjsuen/dockerfile-language-server-nodejs][dockerfile-language-server-nodejs]] |
     | Go                    | [[https://golang.org/x/tools/cmd/gopls][gopls]]                             |
     | HTML                  | [[https://github.com/vscode-langservers/vscode-html-languageserver][html]]                              |
     | JavaScript/TypeScript | [[https://github.com/theia-ide/typescript-language-server][typescript-language-server]]        |
     | Python                | [[https://github.com/palantir/python-language-server][pyls]]                              |
** Usage
   There are 2 supported containers:
   - [[#emacslsplsp-docker-langservers][emacslsp/lsp-docker-langservers]]
   - [[#emacslsplsp-docker-full][emacslsp/lsp-docker-full]]

** emacslsp/lsp-docker-langservers
   This container is used by =lsp-docker= to run =Language Servers= for =lsp-mode= over local sources.
   =You must pull the container before lsp-docker can use it=
*** Configuration
    - Clone the repo
      #+begin_src bash
      git clone https://github.com/emacs-lsp/lsp-docker
      #+end_src
    - Pull the container
      #+begin_src bash
      docker pull emacslsp/lsp-docker-langservers
      #+end_src
    - Add repo to load path and register the docker clients in your =~/.emacs= file
      #+begin_src elisp
      ;; Uncomment the next line if you are using this from source
      ;; (add-to-list 'load-path "<path-to-lsp-docker-dir>")
      (require 'lsp-docker)

      (defvar lsp-docker-client-packages
          '(lsp-css lsp-clients lsp-bash lsp-go lsp-pyls lsp-html lsp-typescript
            lsp-terraform lsp-cpp))

      (defvar lsp-docker-client-configs
         (list
         (list :server-id 'bash-ls :docker-server-id 'bashls-docker :server-command "bash-language-server start")
         (list :server-id 'clangd :docker-server-id 'clangd-docker :server-command "ccls")
         (list :server-id 'css-ls :docker-server-id 'cssls-docker :server-command "css-languageserver --stdio")
         (list :server-id 'dockerfile-ls :docker-server-id 'dockerfilels-docker :server-command "docker-langserver --stdio")
         (list :server-id 'gopls :docker-server-id 'gopls-docker :server-command "gopls")
         (list :server-id 'html-ls :docker-server-id 'htmls-docker :server-command "html-languageserver --stdio")
         (list :server-id 'pyls :docker-server-id 'pyls-docker :server-command "pyls")
         (list :server-id 'ts-ls :docker-server-id 'tsls-docker :server-command "typescript-language-server --stdio")))

      (require 'lsp-docker)
      (lsp-docker-init-clients
        :path-mappings '(("path-to-projects-you-want-to-use" . "/projects"))
        :client-packages lsp-docker-client-packages
        :client-configs lsp-docker-client-configs)
      #+end_src
*** How it works
    =lsp-mode= starts the image passed as =:docker-image-id= and mounts =:path-mappings= in the container. Then when the process is started =lsp-mode= translates the local paths to =docker= path and vice versa using the =:path-mappings= specified when calling =lsp-docker-init-default-clients=. You may use =lsp-enabled-clients= and =lsp-disabled-clients= to control what language server will be used to run for a particular project(refer to =lsp-mode= FAQ on how to configure .dir-locals).

** emacslsp/lsp-docker-full
    The container =emacslsp/lsp-docker-full= contains:
    - The above language servers
    - =Emacs28= compiled with native JSON support for better performance.
*** Flags
    | Flag            | Purpose                                | Default                                               |
    |-----------------+----------------------------------------+-------------------------------------------------------|
    | EMACS_D_VOLUME  | Emacs folder to use for =/root/.emacs= | Emacs: =$(pwd)/emacs.d= Spacemacs: =$(pwd)/spacemacs= |
    | PROJECTS_VOLUME | Directory to mount at /Projects        | =$(pwd)/demo-projects/=                               |
    | TZ              | Timezone to user in container          | Europe/Minsk                                          |
    | DOCKER_FLAGS    | Any additional docker flags            | N/A                                                   |
**** Emacs
     - Clone =lsp-docker=.
       #+begin_src bash
       git clone https://github.com/emacs-lsp/lsp-docker
       cd lsp-docker
       #+end_src
     - Run
       #+begin_src bash
       bash start-emacs.sh
       #+end_src
**** Spacemacs
     - Clone =lsp-docker=.
       #+begin_src bash
       git clone https://github.com/emacs-lsp/lsp-docker
       cd lsp-docker
       #+end_src
     - Clone spacemacs repo
       #+begin_src bash
       # Clone spacemacs develop
       git clone -b develop https://github.com/syl20bnr/spacemacs spacemacs
       #+end_src
     - Run
       #+begin_src bash
       EMACS_D_VOLUME=/path/to/spacemacs bash start-spacemacs.sh
       #+end_src
** Docker over TRAMP (TBD)
   Docker running the language servers and hosting the sources, Emacs running on the desktop machine and connecting to docker instance over TRAMP.
** See also
   - [[https://github.com/Silex/docker.el][docker]] - package for managing =docker= images/containers.
** Maintainers
   - [[https://github.com/yyoncho][yyoncho]]
   - [[https://github.com/rnikoopour][rnikoopour]]