diff --git a/docs/container_registry.md b/docs/container_registry.md index b536dac6..66c6f587 100644 --- a/docs/container_registry.md +++ b/docs/container_registry.md @@ -1,24 +1,32 @@ -GitLab Container Registry -========================= +# GitLab Container Registry + Since `8.8.0` GitLab introduces a container registry. GitLab is helping to authenticate the user against the registry and proxy it via Nginx. By [Registry](https://docs.docker.com/registry) we mean the registry from docker whereas *Container Registry* is the feature in GitLab. -- [Prerequisites](#prerequisites) -- [Installation](#installation) -- [Configuration](#configuration) -- [Maintenance](#maintenance) +- [GitLab Container Registry](#gitlab-container-registry) + - [Prerequisites](#prerequisites) + - [Installation](#installation) + - [Setup with Nginx as Reverse Proxy](#setup-with-nginx-as-reverse-proxy) + - [Create auth tokens](#create-auth-tokens) + - [Update docker-compose.yml](#update-docker-composeyml) + - [Nginx Site Configuration](#nginx-site-configuration) + - [Configuration](#configuration) + - [Available Parameters](#available-parameters) + - [Container Registry storage driver](#container-registry-storage-driver) + - [Example for Amazon Simple Storage Service (s3)](#example-for-amazon-simple-storage-service-s3) + - [Storage limitations](#storage-limitations) + - [Maintenance](#maintenance) - [Creating Backups](#creating-backups) - [Restoring Backups](#restoring-backups) -- [Upgrading from an existing GitLab instance](#Upgrading-from-an-existing-GitLab-instance) + - [Upgrading from an existing GitLab installation](#upgrading-from-an-existing-gitlab-installation) -# Prerequisites +## Prerequisites - - [Docker Distribution](https://github.com/docker/distribution) >= 2.4 - - [Docker GitLab](https://github.com/sameersbn/docker-gitlab) >= 8.8.5-1 +- [Docker Distribution](https://github.com/docker/distribution) >= 2.4 +- [Docker GitLab](https://github.com/sameersbn/docker-gitlab) >= 8.8.5-1 +## Installation -# Installation - -## Setup with Nginx as Reverse Proxy +### Setup with Nginx as Reverse Proxy We assume that you already have Nginx installed on your host system and that you use a reverse proxy configuration to connect to your GitLab container. @@ -26,13 +34,13 @@ you use a reverse proxy configuration to connect to your GitLab container. In this example we use a dedicated domain for the registry. The URLs for the GitLab installation and the registry are: -* git.example.com -* registry.example.com +- git.example.com +- registry.example.com > Note: You could also run everything on the same domain and use different ports > instead. The required configuration changes below should be straightforward. -### Create auth tokens +#### Create auth tokens GitLab needs a certificate ("auth token") to talk to the registry API. The tokens must be provided in the `/certs` directory of your container. You could @@ -55,8 +63,7 @@ openssl x509 -in registry.csr -out registry.crt -req -signkey registry.key -days It doesn't matter which details (domain name, etc.) you enter during key creation. This information is not used at all. - -### Update docker-compose.yml +#### Update docker-compose.yml First add the configuration for the registry container to your `docker-compose.yml`. @@ -108,7 +115,7 @@ Then update the `volumes` and `environment` sections of your `gitlab` container: - ./certs:/certs ``` -### Nginx Site Configuration +#### Nginx Site Configuration ```nginx server { @@ -150,9 +157,9 @@ server { } ``` -# Configuration +## Configuration -## Available Parameters +### Available Parameters Here is an example of all configuration parameters that can be used in the GitLab container. @@ -174,15 +181,15 @@ where: | Parameter | Description | | --------- | ----------- | -| `GITLAB_REGISTRY_ENABLED ` | `true` or `false`. Enables the Registry in GitLab. By default this is `false`. | -| `GITLAB_REGISTRY_HOST ` | The host URL under which the Registry will run and the users will be able to use. | -| `GITLAB_REGISTRY_PORT ` | The port under which the external Registry domain will listen on. | -| `GITLAB_REGISTRY_API_URL ` | The internal API URL under which the Registry is exposed to. | -| `GITLAB_REGISTRY_KEY_PATH `| The private key location that is a pair of Registry's `rootcertbundle`. Read the [token auth configuration documentation][token-config]. | -| `GITLAB_REGISTRY_PATH ` | This should be the same directory like specified in Registry's `rootdirectory`. Read the [storage configuration documentation][storage-config]. This path needs to be readable by the GitLab user, the web-server user and the Registry user *if you use filesystem as storage configuration*. Read more in [#container-registry-storage-path](#container-registry-storage-path). | +| `GITLAB_REGISTRY_ENABLED` | `true` or `false`. Enables the Registry in GitLab. By default this is `false`. | +| `GITLAB_REGISTRY_HOST` | The host URL under which the Registry will run and the users will be able to use. | +| `GITLAB_REGISTRY_PORT` | The port under which the external Registry domain will listen on. | +| `GITLAB_REGISTRY_API_URL` | The internal API URL under which the Registry is exposed to. | +| `GITLAB_REGISTRY_KEY_PATH`| The private key location that is a pair of Registry's `rootcertbundle`. Read the [token auth configuration documentation][token-config]. | +| `GITLAB_REGISTRY_PATH` | This should be the same directory like specified in Registry's `rootdirectory`. Read the [storage configuration documentation][storage-config]. This path needs to be readable by the GitLab user, the web-server user and the Registry user *if you use filesystem as storage configuration*. Read more in [#container-registry-storage-path](#container-registry-storage-path). | | `GITLAB_REGISTRY_ISSUER` | This should be the same value as configured in Registry's `issuer`. Otherwise the authentication will not work. For more info read the [token auth configuration documentation][token-config]. | -| `SSL_REGISTRY_KEY_PATH ` | The private key of the `SSL_REGISTRY_CERT_PATH`. This will be later used in nginx to proxy your registry via https. | -| `SSL_REGISTRY_CERT_PATH ` | The certificate for the private key of `SSL_REGISTRY_KEY_PATH`. This will be later used in nginx to proxy your registry via https. | +| `SSL_REGISTRY_KEY_PATH` | The private key of the `SSL_REGISTRY_CERT_PATH`. This will be later used in nginx to proxy your registry via https. | +| `SSL_REGISTRY_CERT_PATH` | The certificate for the private key of `SSL_REGISTRY_KEY_PATH`. This will be later used in nginx to proxy your registry via https. | For more info look at [Available Configuration Parameters](https://github.com/sameersbn/docker-gitlab#available-configuration-parameters). @@ -200,12 +207,9 @@ gitlab: ... ``` -## Container Registry storage driver +### Container Registry storage driver -You can configure the Container Registry to use a different storage backend by -configuring a different storage driver. By default the GitLab Container Registry -is configured to use the filesystem driver, which makes use of [storage path](#container-registry-storage-path) -configuration. These configurations will all be done in the registry container. +You can configure the Container Registry to use a different storage backend by configuring a different storage driver. By default the GitLab Container Registry is configured to use the filesystem driver, which makes use of [storage path](#container-registry-storage-path) configuration. These configurations will all be done in the registry container. The different supported drivers are: @@ -227,7 +231,7 @@ Read more about the individual driver's config options in the > If you don't change `GITLAB_REGISTRY_DIR` you will find your registry data in the mounted volume from the GitLab Container under `./gitlab/shared/registry`. This don't need to be separated mounted because `./gitlab` is already mounted in the GitLab Container. If it will be mounted separated the whole restoring process of GitLab backup won't work because gitlab try to create an folder under `./gitlab/shared/registry` /`GITLAB_REGISTRY_DIR` and GitLab can't delete/remove the mount point inside the container so the restoring process of the backup will fail. > An example how it works is in the `docker-compose`. -### Example for Amazon Simple Storage Service (s3) +#### Example for Amazon Simple Storage Service (s3) If you want to configure your registry via `/etc/docker/registry/config.yml` your storage part should like this snippet below. @@ -243,8 +247,6 @@ storage: enabled: true ``` - - ```yaml ... registry: @@ -267,18 +269,17 @@ storage: Generally for more information about the configuration of the registry container you can find it under [registry configuration](https://docs.docker.com/registry/configuration). - -## Storage limitations +### Storage limitations Currently, there is no storage limitation, which means a user can upload an infinite amount of Docker images with arbitrary sizes. This setting will be configurable in future releases. +## Maintenance -# Maintenance If you use another storage configuration than filesystem it will have no impact on your Maintenance workflow. -## Creating Backups +### Creating Backups Creating Backups is the same like without a container registry. I would recommend to stop your registry container. @@ -287,11 +288,13 @@ docker stop registry gitlab && docker rm registry gitlab ``` Execute the rake task with a removeable container. + ```bash docker run --name gitlab -it --rm [OPTIONS] \ sameersbn/gitlab:18.0.0 app:rake gitlab:backup:create ``` -## Restoring Backups + +### Restoring Backups GitLab also defines a rake task to restore a backup. @@ -317,8 +320,7 @@ docker run --name gitlab -it --rm [OPTIONS] \ sameersbn/gitlab:18.0.0 app:rake gitlab:backup:restore BACKUP=1417624827 ``` -# Upgrading from an existing GitLab installation - +## Upgrading from an existing GitLab installation If you want enable this feature for an existing instance of GitLab you need to do the following steps. @@ -365,6 +367,7 @@ docker run --name registry -d \ --env 'REGISTRY_STORAGE_DELETE_ENABLED=true' \ registry:2.4.1 ``` + - **Step 6**: Start the image ```bash @@ -381,11 +384,5 @@ docker run --name gitlab -d [PREVIOUS_OPTIONS] \ sameersbn/gitlab:18.0.0 ``` - -[wildcard certificate]: https://en.wikipedia.org/wiki/Wildcard_certificate -[ce-4040]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/4040 -[docker-insecure]: https://docs.docker.com/registry/insecure/ -[registry-deploy]: https://docs.docker.com/registry/deploying/ [storage-config]: https://docs.docker.com/registry/configuration/#storage [token-config]: https://docs.docker.com/registry/configuration/#token -[8-8-docs]: https://gitlab.com/gitlab-org/gitlab-foss/blob/8-8-stable/doc/administration/container_registry.md diff --git a/docs/exposing-ssh-port.md b/docs/exposing-ssh-port.md index 9c37baee..a2dbca10 100644 --- a/docs/exposing-ssh-port.md +++ b/docs/exposing-ssh-port.md @@ -3,6 +3,5 @@ This is how to expose this internal ssh port without affecting the existing ssh port on the host server: * use this configuration script: [`../contrib/expose-gitlab-ssh-port.sh`](../contrib/expose-gitlab-ssh-port.sh) -* see implementation example in Vagrant: [harobed/docker-gitlab-vagrant-test -](https://github.com/harobed/docker-gitlab-vagrant-test) +* see implementation example in Vagrant: [harobed/docker-gitlab-vagrant-test](https://github.com/harobed/docker-gitlab-vagrant-test) * more information, see [« Exposing ssh port in dockerized gitlab-ce »](https://blog.xiaket.org/2017/exposing.ssh.port.in.dockerized.gitlab-ce.html) post diff --git a/docs/keycloak-idp.md b/docs/keycloak-idp.md index 61f76ce6..04bc3c73 100644 --- a/docs/keycloak-idp.md +++ b/docs/keycloak-idp.md @@ -37,7 +37,7 @@ Set the following in the docker-compose file: - OAUTH2_GENERIC_CLIENT_END_SESSION_ENDPOINT=http://:10081/auth/realms/master/protocol/openid-connect/logout ``` -`` is the IP address of your keycloak. For this example this would be your IP address, but if your Keycloak existed elsewhere for your deployment `` would be different as would the port and the realm. +`` is the IP address of your keycloak. For this example this would be your IP address, but if your Keycloak existed elsewhere for your deployment `` would be different as would the port and the realm. The following must also be configured: @@ -47,7 +47,7 @@ The following must also be configured: - OAUTH2_GENERIC_USER_EMAIL='email' ``` -The values will be different for your deployment. Navigate Keycloak's UI, select `Clients`, click `[your client]`, then open the `Client Scopes` tab, then open `Evaluate` sub-tab, enter a username you know in the `User` field, select the match, then `Generate Access Token` to see the values you need to configure. +The values will be different for your deployment. Navigate Keycloak's UI, select `Clients`, click `[your client]`, then open the `Client Scopes` tab, then open `Evaluate` sub-tab, enter a username you know in the `User` field, select the match, then `Generate Access Token` to see the values you need to configure. Also, make sure the following variables are filled in the docker-compose file: diff --git a/docs/s3_compatible_storage.md b/docs/s3_compatible_storage.md index 35a15a0d..4fb7d0fb 100644 --- a/docs/s3_compatible_storage.md +++ b/docs/s3_compatible_storage.md @@ -1,23 +1,22 @@ -GitLab Backup to s3 compatible storage -================================================= +# GitLab Backup to s3 compatible storage -Enables automatic backups to self-hosted s3 compatible storage like minio (https://minio.io/) and others. +Enables automatic backups to self-hosted s3 compatible storage like minio () and others. This is an extend of AWS Remote Backups. As explained in [doc.gitlab.com](https://docs.gitlab.com/ce/raketasks/backup_restore.html#upload-backups-to-remote-cloud-storage), it uses [Fog library](http://fog.io) and the module fog-aws. More details on [s3 supported parameters](https://github.com/fog/fog-aws/blob/master/lib/fog/aws/storage.rb) - [GitLab Backup to s3 compatible storage](#gitlab-backup-to-s3-compatible-storage) -- [Available Parameters](#available-parameters) -- [Installation](#installation) - - [Docker Compose](#docker-compose) - - [Creating Backups](#creating-backups) - - [Restoring Backups](#restoring-backups) + - [Available Parameters](#available-parameters) + - [Installation](#installation) + - [Docker Compose](#docker-compose) + - [Creating Backups](#creating-backups) + - [Restoring Backups](#restoring-backups) -# Available Parameters +## Available Parameters Here is an example of all configuration parameters that can be used in the GitLab container. -``` +```yaml ... gitlab: ... @@ -28,7 +27,6 @@ gitlab: - AWS_BACKUP_SECRET_ACCESS_KEY=minio123 - AWS_BACKUP_BUCKET=docker - AWS_BACKUP_MULTIPART_CHUNK_SIZE=104857600 - ``` where: @@ -46,7 +44,7 @@ For more info look at [Available Configuration Parameters](https://github.com/sa A minimum set of these parameters are required to use the s3 compatible storage: -```yml +```yaml ... gitlab: environment: @@ -57,11 +55,12 @@ gitlab: - AWS_BACKUP_BUCKET=docker ... ``` -# Installation + +## Installation Starting a fresh installation with GitLab would be like the `docker-compose` file. -## Docker Compose +### Docker Compose This is an example with minio. @@ -214,15 +213,16 @@ services: command: server /export ``` - -## Creating Backups +### Creating Backups Execute the rake task with a removeable container. + ```bash docker run --name gitlab -it --rm [OPTIONS] \ sameersbn/gitlab:8.16.4 app:rake gitlab:backup:create ``` -## Restoring Backups + +### Restoring Backups Execute the rake task to restore a backup. Make sure you run the container in interactive mode `-it`.