github.com/freiheit-com/kuberpult@v1.24.2-0.20240328135542-315d5630abe6/infrastructure/docker/git-ssh/README.md (about)

     1  # Git-SSH (Docker)
     2  
     3  A simple Git-over-SSH server Docker image with UID/GID handling, based on
     4  Alpine Linux.
     5  
     6  *The [Quickstart section](#quickstart) shows the fastest way to set everything
     7  up without providing further details.*
     8  
     9  Clients (users) can interact with the server using Git after adding their
    10  public SSH key to the Git-SSH server for authentication.
    11  Within the Docker container all Git repositries are managed by a single `git`
    12  user, whos UID/GID is specified at container start.
    13  Normal (interactive shell) SSH access to the Docker host machine that runs the
    14  container is needed to add a new user/client (add an SSH public key) and create
    15  or delete Git reposities.  
    16  The UML deployment diagram in the figure below gives an overview.
    17  
    18  ![UML deployment diagram](./uml-dd-deployment-overview.png "UML deployment diagram")
    19   
    20  > Used terminology in this documentation:
    21  > * Client - Client machine that connects to the host
    22  > * Host - Host machine that runs the Docker container
    23  
    24  > Used variables in this documentation:
    25  > * `GITSSH_BASE_PATH` - Path to the directory that contains this project’s
    26  >   files (especially `Dockerfile` + other build-related files and
    27  >   `docker-compose.yml`)
    28  > * `GITSSH_GID` - GID assigned to the `git` user within the Docker container,
    29  >   e.g. `1000`.
    30  >   The access permissions of the Docker volumes content will be set to this
    31  >   GID.
    32  > * `GITSSH_UID` - UID assigned to the `git` user within the Docker container,
    33  >   e.g. `1000`.
    34  >   The acces spermissions of the Docker volumes content will be set to this
    35  >   UID.
    36  > * `GITSSH_PORT` - Network port used for the Git SSH connection, e.g. `2222`
    37  > * `REPO_NAME` - Name of the Git repository
    38  > * `SERVER` - Network address (IP/domain name) of the host
    39  > * `USER` - SSH user used to login to the host
    40  > * `VERSION` - Version of this project, e.g. `1.0.0`.
    41  >   Adheres to [Semantic Versioning](https://semver.org).
    42  
    43  ## Quickstart
    44  
    45  **How to** set everything up the fastest way possible:
    46  
    47  Step 1 (on the host):
    48  
    49  ```sh
    50  $ cd ${GITSSH_BASE_PATH}
    51  $ make build
    52  $ make prepare-deploy
    53  ```
    54  
    55  ... and adjust `docker-compose.yml`.
    56  
    57  Step 2 (on the client):
    58  
    59  ```sh
    60  $ ssh-keygen -t ed25519
    61  $ scp ~/.ssh/id_ed25519.pub ${USER}@${SERVER}:${GITSSH_BASE_PATH}/git-ssh/keys/
    62  ```
    63  
    64  Step 3 (on the host):
    65  
    66  ```sh
    67  $ make deploy
    68  ```
    69  
    70  ## Applicability
    71  
    72  The main use case for this project is to provide a very simple but secure^1
    73  solution to host Git repositories on a network (e.g., LAN/WAN/internet), using
    74  SSH key authentication.
    75  
    76  ^1: "Secure" here only means access restiction and encryption using SSH key
    77  authentication.
    78  
    79  ## Requirements
    80  
    81  For basic usage (mandatory):
    82  * Docker
    83  
    84  For easy handling (recommended):
    85  * Docker Compose
    86  * Make
    87  
    88  ## Makefile
    89  
    90  Most of the instructions in this documentation can also be run with the
    91  provided `Makefile` (which uses Docker Compose).
    92  Run `cd ${GITSSH_BASE_PATH} && make help` to see the list of available targets.
    93  
    94  > The Makefile uses Docker Compose, see the prerequisite in "How to run the
    95  > container with Docker Compose (on the host)" in the [Run section](#run).
    96  
    97  ## Build
    98  
    99  **How to** build the Docker image (on the host):
   100  
   101  ```sh
   102  $ cd ${GITSSH_BASE_PATH}
   103  $ sudo docker build -t git-ssh:${VERSION} .
   104  $ sudo docker image tag git-ssh:${VERSION} git-ssh:latest
   105  ```
   106  
   107  ## Arguments
   108  
   109  * Exposed port: `22`
   110  * Volumes:
   111      * `/git/keys-host`: Volume to store the SSHD host keys
   112      * `/git/keys`: Volume to store the users’ public keys
   113      * `/git/repos`: Volume to store the Git repositories
   114  * Environment variables:
   115      * `PUID`: UID that is assigned to the `git` user inside the Docker container
   116      * `PGID`: GID that is assigned to the `git` user inside the Docker container
   117  
   118  ## Run
   119  
   120  **How to** run the Docker container (on the host):
   121  
   122  ```sh
   123  $ cd ${GITSSH_BASE_PATH}
   124  $ mkdir -p ./git-ssh/keys-host/ ./git-ssh/keys/ ./git-ssh/repos/
   125  $ sudo docker run \
   126    -d \
   127    -p ${GITSSH_PORT}:22 \
   128    -v ${GITSSH_BASE_PATH}/git-ssh/keys-host/:/git/keys-host/ \
   129    -v ${GITSSH_BASE_PATH}/git-ssh/keys/:/git/keys/ \
   130    -v ${GITSSH_BASE_PATH}/git-ssh/repos/:/git/repos/ \
   131    -e PUID=${GITSSH_UID} \
   132    -e PGID=${GITSSH_GID} \
   133    --name="git-ssh" \
   134    git-ssh:latest
   135  ```
   136  
   137  **How to** run the container with Docker Compose (on the host):
   138  
   139  Prerequisite:
   140  Copy `docker-compose.yml.template` to `docker-compose.yml` and adjust it.
   141  
   142  > Instead of modifying `docker-compose.yml` after copying it, one can create an
   143  > `.env` file that provides the necessary variables:
   144  >
   145  > ```sh
   146  > GITSSH_PORT=
   147  > GITSSH_BASE_PATH=
   148  > GITSSH_UID=
   149  > GITSSH_GID=
   150  > ```
   151  
   152  ```sh
   153  $ cd ${GITSSH_BASE_PATH}
   154  $ mkdir -p ./git-ssh/keys-host/ ./git-ssh/keys/ ./git-ssh/repos/
   155  $ sudo docker-compose up -d
   156  ```
   157  
   158  ## SSH keys
   159  
   160  > Based on [this reference](https://www.ssh.com/ssh/keygen/).
   161  
   162  **How to** generate an SSH private/public key pair (on the client):
   163  
   164  > This generates stronger keys than the default, RSA.
   165  
   166  ```sh
   167  $ ssh-keygen -t ecdsa -b 521
   168  ```
   169  
   170  > Or if supported by the client:
   171  > `ssh-keygen -t ed25519`
   172  
   173  **How to** add a client’s SSH public key to the Git-SSH server:
   174  
   175  Upload the key to the host’s volume mount point (on the client):
   176  
   177  ```sh
   178  $ scp ~/.ssh/id_ecdsa.pub ${USER}@${SERVER}:${GITSSH_BASE_PATH}/git-ssh/keys/
   179  ```
   180  
   181  Restart the Docker container (on the host):
   182  
   183  ```sh
   184  $ sudo docker restart git-ssh
   185  ```
   186  
   187  > Or with Docker Compose:
   188  > `sudo docker-compose down -t 1 && sudo docker-compose up -d`
   189  
   190  ## Basic usage
   191  
   192  **How to**
   193  * check that the Docker container works and
   194  * list all repositories
   195  (on the client):
   196  
   197  > The client’s SSH public key must have been uploaded to the host already.
   198  
   199  ```sh
   200  $ ssh -p ${GITSSH_PORT} git@${SERVER}
   201  
   202  ~~~ Welcome to Git-SSH server! ~~~
   203  [...]
   204  You have successfully authenticated but
   205  interactive shell access is not provided.
   206  [...]
   207  ```
   208  
   209  **How to** create a new (bare) repository (on the host):
   210  
   211  ```sh
   212  $ sudo docker exec -u git git-ssh git init --bare ./repos/${REPO_NAME}.git
   213  ```
   214  
   215  > Or with Docker Compose:
   216  > `sudo docker-compose exec -u git git-ssh git init --bare ./repos/${REPO_NAME}.git`
   217  
   218  **How to** clone a repository (on the client):
   219  
   220  ```sh
   221  $ git clone ssh://git@${SERVER}:${GITSSH_PORT}/git/repos/${REPO_NAME}.git
   222  ```
   223  
   224  **How to** push a (non-bare) repository that (yet) only exists locally (on the
   225  client):
   226  
   227  Prerequisite: Create a new (bare) repository (on the host).
   228  
   229  > See "How to create a new (bare) repository (on the host)".
   230  
   231  ```sh
   232  $ git remote add origin \
   233    ssh://git@${SERVER}:${GITSSH_PORT}/git/repos/${REPO_NAME}.git
   234  $ git push -u origin master
   235  ```
   236  
   237  > Replace `git remote add [...]` with `git remote set-url [...]` if `origin`
   238  > already exists.
   239  
   240  > Repeat the `git push [...]` command for all tracking branches ...
   241  
   242  **How to** upload an existing bare repository (on the client):
   243  
   244  ```sh
   245  $ scp -r /path/to/${REPO_NAME}.git \
   246    ${USER}@${SERVER}:${GITSSH_BASE_PATH}/git-ssh/repos/
   247  ```
   248  
   249  > Make sure that uploaded bare repositories have the correct access permissions
   250  > set (see "How to fix Git repository access permission issues (on the host)"
   251  > in the [Troubleshooting section](#troubleschooting)).
   252  
   253  ## Troubleshooting
   254  
   255  **How to** fix Git repository access permission issues (on the host):
   256  
   257  ```sh
   258  $ sudo docker exec git-ssh sh ./fix-repos.sh
   259  ```
   260  
   261  > Or with Docker Compose:
   262  > `sudo docker-compose exec git-ssh sh ./fix-repos.sh`