github.com/ddev/ddev@v1.23.2-0.20240519125000-d824ffe36ff3/containers/ddev-ssh-agent/README.md (about)

     1  # ddev-ssh-agent Docker Image
     2  
     3  originally forked from <https://github.com/nardeas/docker-ssh-agent>
     4  at `fb6822d0003d1c0a795e183f5d257c2540fa74a4`.
     5  
     6  ## Overview
     7  Docker container image for DDEV's ddev-ssh-agent container.
     8  
     9  This container image is part of DDEV, and not typically used stand-alone.
    10  
    11  ### Features
    12  
    13  Provides an ssh-agent inside the docker network.
    14  
    15  ## Instructions
    16  
    17  Use [DDEV](https://ddev.readthedocs.io)
    18  
    19  ### Building and pushing to Docker Hub
    20  
    21  See [DDEV docs](https://ddev.readthedocs.io/en/stable/developers/release-management/#pushing-docker-images-with-the-github-actions-workflow)
    22  
    23  
    24  ## Source:
    25  [ddev-ssh-agent](https://github.com/ddev/ddev/tree/master/containers/ddev-ssh-agent)
    26  
    27  ## Maintained by:
    28  The [DDEV Docker Maintainers](https://github.com/ddev)
    29  
    30  ## Where to get help:
    31  * [DDEV Community Discord](https://discord.gg/5wjP76mBJD)
    32  * [Stack Overflow](https://stackoverflow.com/questions/tagged/ddev)
    33  
    34  ## Where to file issues:
    35  https://github.com/ddev/ddev/issues
    36  
    37  ## Documentation:
    38  * https://ddev.readthedocs.io/en/stable/users/support/
    39  * https://ddev.com/
    40  
    41  ## What is DDEV?
    42  
    43  [DDEV](https://github.com/ddev/ddev) is an open source tool for launching local web development environments in minutes. It supports PHP, Node.js, and Python (experimental).
    44  
    45  These environments can be extended, version controlled, and shared, so you can take advantage of a Docker workflow without Docker experience or bespoke configuration. Projects can be changed, powered down, or removed as easily as they’re started.
    46  
    47  ## License
    48  
    49  View [license information](https://github.com/ddev/ddev/blob/master/LICENSE) for the software contained in this image.
    50  
    51  As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).
    52  
    53  As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.
    54  
    55  
    56  
    57  # Original copy from nardeas/ssh-agent
    58  
    59  [![Pulls](https://img.shields.io/docker/pulls/nardeas/ssh-agent.svg)](https://img.shields.io/docker/pulls/nardeas/ssh-agent.svg?style=flat-square)
    60  [![Size](https://images.microbadger.com/badges/image/nardeas/ssh-agent.svg)](https://microbadger.com/images/nardeas/ssh-agent "Get your own image badge on microbadger.com")
    61  
    62  Lets you store your SSH authentication keys in a dockerized ssh-agent that can provide the SSH authentication socket for other containers. Works in macOS and Linux environments.
    63  
    64  ## Why?
    65  
    66  On macOS you cannot simply forward your authentication socket to a Docker container to be able to e.g clone private repositories that you have access to. You don't want to copy your private key to all containers either. The solution is to add your keys only once to a long-lived ssh-agent container that can be used by other containers and stopped when not needed anymore.
    67  
    68  ## hub.docker.com
    69  
    70  You can pull the image from [DockerHub](https://hub.docker.com/r/nardeas/ssh-agent/) via
    71  
    72  ```
    73  docker pull nardeas/ssh-agent
    74  ```
    75  
    76  ## How to use
    77  
    78  ### Quickstart
    79  
    80  If you don't want to build your own images, here's a 3-step guide:
    81  
    82  1\. Run agent
    83  
    84  ```
    85  docker run -d --name=ssh-agent nardeas/ssh-agent
    86  ```
    87  
    88  2\. Add your keys
    89  
    90  ```
    91  docker run --rm --volumes-from=ssh-agent -v ~/.ssh:/.ssh -it nardeas/ssh-agent ssh-add /root/.ssh/id_rsa
    92  ```
    93  
    94  3\. Now run your actual container:
    95  
    96  ```
    97  docker run -it --volumes-from=ssh-agent -e SSH_AUTH_SOCK=/.ssh-agent/socket ubuntu:latest /bin/bash
    98  ```
    99  
   100  **Run script**
   101  
   102  You can run the `run.sh` script which will build the images for you, launch the ssh-agent and add your keys. If your keys are password protected (hopefully) you will need to input your passphrase.
   103  
   104  Launch everything:
   105  
   106  ```
   107  ./run.sh
   108  ```
   109  
   110  Remove your keys from ssh-agent and stop container:
   111  
   112  ```
   113  ./run.sh -s
   114  ```
   115  
   116  ### Step by step
   117  
   118  #### 0. Build
   119  
   120  Navigate to the project directory and launch the following command to build the image:
   121  
   122  ```
   123  docker build -t docker-ssh-agent:latest -f Dockerfile .
   124  ```
   125  
   126  #### 1. Run a long-lived container
   127  
   128  ```
   129  docker run -d --name=ssh-agent docker-ssh-agent:latest
   130  ```
   131  
   132  #### 2. Add your ssh keys
   133  
   134  Run a temporary container with volume mounted from host that includes your SSH keys. SSH key id_rsa will be added to ssh-agent (you can replace id_rsa with your key name):
   135  
   136  ```
   137  docker run --rm --volumes-from=ssh-agent -v ~/.ssh:/.ssh -it docker-ssh-agent:latest ssh-add /root/.ssh/id_rsa
   138  ```
   139  
   140  The ssh-agent container is now ready to use.
   141  
   142  #### 3. Add ssh-agent socket to other container
   143  
   144  If you're using `docker-compose` this is how you forward the socket to a container:
   145  
   146  ```
   147    volumes_from:
   148      - ssh-agent
   149    environment:
   150      - SSH_AUTH_SOCK=/.ssh-agent/socket
   151  ```
   152  
   153  ##### For non-root users
   154  
   155  The above only works for root. ssh-agent socket is accessible only to the user which started this agent or for root user. So other users don't have access to `/.ssh-agent/socket`. If you have another user in your container you should do the following:
   156  
   157  1. Install `socat` utility in your container
   158  2. Make proxy-socket in your container:
   159  
   160  ```
   161  sudo socat UNIX-LISTEN:~/.ssh/socket,fork UNIX-CONNECT:/.ssh-agent/socket &
   162  ```
   163  
   164  3. Change the owner of this proxy-socket
   165  
   166  ```
   167  sudo chown $(id -u) ~/.ssh/socket
   168  ```
   169  
   170  4. You will need to use different SSH_AUTH_SOCK for this user:
   171  
   172  ```
   173  SSH_AUTH_SOCK=~/.ssh/socket
   174  ```
   175  
   176  ##### Without docker-compose
   177  
   178  Here's an example how to run a Ubuntu container that uses the ssh authentication socket:
   179  
   180  ```
   181  docker run -it --volumes-from=ssh-agent -e SSH_AUTH_SOCK=/.ssh-agent/socket ubuntu:latest /bin/bash
   182  ```
   183  
   184  ### Deleting keys from the container
   185  
   186  Run a temporary container and delete all known keys from ssh-agent:
   187  
   188  ```
   189  docker run --rm --volumes-from=ssh-agent -it docker-ssh-agent:latest ssh-add -D
   190  ```