diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2020-06-18 14:18:50 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2020-06-18 14:18:50 +0300 |
commit | 8c7f4e9d5f36cff46365a7f8c4b9c21578c1e781 (patch) | |
tree | a77e7fe7a93de11213032ed4ab1f33a3db51b738 /doc/install | |
parent | 00b35af3db1abfe813a778f643dad221aad51fca (diff) |
Add latest changes from gitlab-org/gitlab@13-1-stable-ee
Diffstat (limited to 'doc/install')
-rw-r--r-- | doc/install/aws/img/aws_ha_architecture_diagram.png | bin | 42452 -> 144735 bytes | |||
-rw-r--r-- | doc/install/aws/img/rds_subnet_group.png | bin | 30107 -> 0 bytes | |||
-rw-r--r-- | doc/install/aws/index.md | 49 | ||||
-rw-r--r-- | doc/install/azure/index.md | 2 | ||||
-rw-r--r-- | doc/install/digitaloceandocker.md | 12 | ||||
-rw-r--r-- | doc/install/google_cloud_platform/img/boot_disk.png | bin | 37786 -> 0 bytes | |||
-rw-r--r-- | doc/install/google_cloud_platform/img/vm_details.png | bin | 50191 -> 77743 bytes | |||
-rw-r--r-- | doc/install/google_cloud_platform/index.md | 8 | ||||
-rw-r--r-- | doc/install/installation.md | 45 | ||||
-rw-r--r-- | doc/install/ldap.md | 4 | ||||
-rw-r--r-- | doc/install/openshift_and_gitlab/index.md | 4 | ||||
-rw-r--r-- | doc/install/requirements.md | 160 |
12 files changed, 133 insertions, 151 deletions
diff --git a/doc/install/aws/img/aws_ha_architecture_diagram.png b/doc/install/aws/img/aws_ha_architecture_diagram.png Binary files differindex e019ed61abf..dc63d36e0b3 100644 --- a/doc/install/aws/img/aws_ha_architecture_diagram.png +++ b/doc/install/aws/img/aws_ha_architecture_diagram.png diff --git a/doc/install/aws/img/rds_subnet_group.png b/doc/install/aws/img/rds_subnet_group.png Binary files differdeleted file mode 100644 index 7c6157e38e0..00000000000 --- a/doc/install/aws/img/rds_subnet_group.png +++ /dev/null diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 41f8d7babac..813e343f2cc 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -12,9 +12,7 @@ For organizations with 300 users or less, the recommended AWS installation metho ## Introduction -GitLab on AWS can leverage many of the services that are already -configurable. These services offer a great deal of -flexibility and can be adapted to the needs of most companies. +For the most part, we'll make use of Omnibus GitLab in our setup, but we'll also leverage native AWS services. Instead of using the Omnibus bundled PostgreSQL and Redis, we will use AWS RDS and ElastiCache. In this guide, we'll go through a multi-node setup where we'll start by configuring our Virtual Private Cloud and subnets to later integrate @@ -59,8 +57,6 @@ Here's a list of the AWS services we will use, with links to pricing information Redis configuration. See the [Amazon ElastiCache pricing](https://aws.amazon.com/elasticache/pricing/). -NOTE: **Note:** Please note that while we will be using EBS for storage, we do not recommend using EFS as it may negatively impact GitLab's performance. You can review the [relevant documentation](../../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. - ## Create an IAM EC2 instance role and profile As we'll be using [Amazon S3 object storage](#amazon-s3-object-storage), our EC2 instances need to have read, write, and list permissions for our S3 buckets. To avoid embedding AWS keys in our GitLab config, we'll make use of an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) to allow our GitLab instance with this access. We'll need to create an IAM policy to attach to our IAM role: @@ -227,17 +223,21 @@ We also need to create two private route tables so that instances in each privat ## Load Balancer +We'll create a load balancer to evenly distribute inbound traffic on ports `80` and `443` across our GitLab application servers. Based the on the [scaling policies](#create-an-auto-scaling-group) we'll create later, instances will be added to or removed from our load balancer as needed. Additionally, the load balance will perform health checks on our instances. + On the EC2 dashboard, look for Load Balancer in the left navigation bar: 1. Click the **Create Load Balancer** button. 1. Choose the **Classic Load Balancer**. 1. Give it a name (we'll use `gitlab-loadbalancer`) and for the **Create LB Inside** option, select `gitlab-vpc` from the dropdown menu. 1. In the **Listeners** section, set HTTP port 80, HTTPS port 443, and TCP port 22 for both load balancer and instance protocols and ports. - 1. In the **Select Subnets** section, select both public subnets from the list. -1. Click **Assign Security Groups** and select **Create a new security group**, give it a name + 1. In the **Select Subnets** section, select both public subnets from the list so that the load balancer can route traffic to both availability zones. +1. We'll add a security group for our load balancer to act as a firewall to control what traffic is allowed through. Click **Assign Security Groups** and select **Create a new security group**, give it a name (we'll use `gitlab-loadbalancer-sec-group`) and description, and allow both HTTP and HTTPS traffic - from anywhere (`0.0.0.0/0, ::/0`). Also allow SSH traffic from a single IP address or an IP address range in CIDR notation. -1. Click **Configure Security Settings** and select an SSL/TLS certificate from ACM or upload a certificate to IAM. + from anywhere (`0.0.0.0/0, ::/0`). Also allow SSH traffic, select a custom source, and add a single trusted IP address or an IP address range in CIDR notation. This will allow users to perform Git actions over SSH. +1. Click **Configure Security Settings** and set the following: + 1. Select an SSL/TLS certificate from ACM or upload a certificate to IAM. + 1. Under **Select a Cipher**, pick a predefined security policy from the dropdown. You can see a breakdown of [Predefined SSL Security Policies for Classic Load Balancers](https://docs.aws.amazon.com/elasticloadbalancing/latest/classic/elb-security-policy-table.html) in the AWS docs. Check the GitLab codebase for a list of [supported SSL ciphers and protocols](https://gitlab.com/gitlab-org/gitlab/-/blob/9ee7ad433269b37251e0dd5b5e00a0f00d8126b4/lib/support/nginx/gitlab-ssl#L97-99). 1. Click **Configure Health Check** and set up a health check for your EC2 instances. 1. For **Ping Protocol**, select HTTP. 1. For **Ping Port**, enter 80. @@ -261,11 +261,16 @@ On the Route 53 dashboard, click **Hosted zones** in the left navigation bar: 1. Click **Create Record Set** and provide the following values: 1. **Name:** Use the domain name (the default value) or enter a subdomain. 1. **Type:** Select **A - IPv4 address**. + 1. **Alias:** Defaults to **No**. Select **Yes**. 1. **Alias Target:** Find the **ELB Classic Load Balancers** section and select the classic load balancer we created earlier. 1. **Routing Policy:** We'll use **Simple** but you can choose a different policy based on your use case. 1. **Evaluate Target Health:** We'll set this to **No** but you can choose to have the load balancer route traffic based on target health. 1. Click **Create**. -1. Update your DNS records with your domain registrar. The steps for doing this vary depending on which registrar you use and is beyond the scope of this guide. +1. If you registered your domain through Route 53, you're done. If you used a different domain registrar, you need to update your DNS records with your domain registrar. You'll need to: + 1. Click on **Hosted zones** and select the domain you added above. + 1. You'll see a list of `NS` records. From your domain registrar's admin panel, add each of these as `NS` records to your domain's DNS records. These steps may vary between domain registrars. If you're stuck, Google **"name of your registrar" add dns records** and you should find a help article specific to your domain registrar. + +The steps for doing this vary depending on which registrar you use and is beyond the scope of this guide. ## PostgreSQL with RDS @@ -280,7 +285,10 @@ We need a security group for our database that will allow inbound traffic from t 1. From the EC2 dashboard, select **Security Groups** from the left menu bar. 1. Click **Create security group**. 1. Give it a name (we'll use `gitlab-rds-sec-group`), a description, and select the `gitlab-vpc` from the **VPC** dropdown. -1. In the **Inbound rules** section, click **Add rule** and add a **PostgreSQL** rule, and set the "Custom" source as the `gitlab-loadbalancer-sec-group` we created earlier. The default PostgreSQL port is `5432`, which we'll also use when creating our database below. +1. In the **Inbound rules** section, click **Add rule** and set the following: + 1. **Type:** search for and select the **PostgreSQL** rule. + 1. **Source type:** set as "Custom". + 1. **Source:** select the `gitlab-loadbalancer-sec-group` we created earlier. 1. When done, click **Create security group**. ### RDS Subnet Group @@ -288,11 +296,10 @@ We need a security group for our database that will allow inbound traffic from t 1. Navigate to the RDS dashboard and select **Subnet Groups** from the left menu. 1. Click on **Create DB Subnet Group**. 1. Under **Subnet group details**, enter a name (we'll use `gitlab-rds-group`), a description, and choose the `gitlab-vpc` from the VPC dropdown. -1. Under **Add subnets**, click **Add all the subnets related to this VPC** and remove the public ones, we only want the **private subnets**. In the end, you should see `10.0.1.0/24` and `10.0.3.0/24` (as we defined them in the [subnets section](#subnets)). +1. From the **Availability Zones** dropdown, select the Availability Zones that include the subnets you've configured. In our case, we'll add `eu-west-2a` and `eu-west-2b`. +1. From the **Subnets** dropdown, select the two private subnets (`10.0.1.0/24` and `10.0.3.0/24`) as we defined them in the [subnets section](#subnets). 1. Click **Create** when ready. - ![RDS Subnet Group](img/rds_subnet_group.png) - ### Create the database DANGER: **Danger:** Avoid using burstable instances (t class instances) for the database as this could lead to performance issues due to CPU credits running out during sustained periods of high load. @@ -301,7 +308,7 @@ Now, it's time to create the database: 1. Navigate to the RDS dashboard, select **Databases** from the left menu, and click **Create database**. 1. Select **Standard Create** for the database creation method. -1. Select **PostgreSQL** as the database engine and select **PostgreSQL 10.9-R1** from the version dropdown menu (check the [database requirements](../../install/requirements.md#postgresql-requirements) to see if there are any updates on this for your chosen version of GitLab). +1. Select **PostgreSQL** as the database engine and select the minimum PostgreSQL version as defined for your GitLab version in our [database requirements](../../install/requirements.md#postgresql-requirements). 1. Since this is a production server, let's choose **Production** from the **Templates** section. 1. Under **Settings**, set a DB instance identifier, a master username, and a master password. We'll use `gitlab-db-ha`, `gitlab`, and a very secure password respectively. Make a note of these as we'll need them later. 1. For the DB instance size, select **Standard classes** and select an instance size that meets your requirements from the dropdown menu. We'll use a `db.m4.large` instance. @@ -329,7 +336,7 @@ Now that the database is created, let's move on to setting up Redis with ElastiC ## Redis with ElastiCache ElastiCache is an in-memory hosted caching solution. Redis maintains its own -persistence and is used for certain types of the GitLab application. +persistence and is used to store session data, temporary cache information, and background job queues for the GitLab application. ### Create a Redis Security Group @@ -559,9 +566,9 @@ Let's create an EC2 instance where we'll install Gitaly: 1. Click **Review and launch** followed by **Launch** if you're happy with your settings. 1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. - > **Optional:** Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). +NOTE: **Optional:** Instead of storing configuration _and_ repository data on the root volume, you can also choose to add an additional EBS volume for repository storage. Follow the same guidance as above. See the [Amazon EBS pricing](https://aws.amazon.com/ebs/pricing/). We do not recommend using EFS as it may negatively impact GitLab’s performance. You can review the [relevant documentation](../../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. -Now that we have our EC2 instance ready, follow the [documentation to install GitLab and set up Gitaly on its own server](../../administration/gitaly/index.md#running-gitaly-on-its-own-server). Perform the client setup steps from that document on the [GitLab instance we created](#install-gitlab) above. +Now that we have our EC2 instance ready, follow the [documentation to install GitLab and set up Gitaly on its own server](../../administration/gitaly/index.md#run-gitaly-on-its-own-server). Perform the client setup steps from that document on the [GitLab instance we created](#install-gitlab) above. #### Add Support for Proxied SSL @@ -600,7 +607,7 @@ sudo cp -R /etc/ssh/* /etc/ssh_static In `/etc/ssh/sshd_config` update the following: -```bash +```shell # HostKeys for protocol version 2 HostKey /etc/ssh_static/ssh_host_rsa_key HostKey /etc/ssh_static/ssh_host_dsa_key @@ -620,7 +627,7 @@ Remember to run `sudo gitlab-ctl reconfigure` after saving the changes to the `g NOTE: **Note:** One current feature of GitLab that still requires a shared directory (NFS) is [GitLab Pages](../../user/project/pages/index.md). -There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/issues/196) +There is [work in progress](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/196) to eliminate the need for NFS to support GitLab Pages. --- @@ -774,7 +781,7 @@ And the more complex the solution, the more work is involved in setting up and maintaining it. Have a read through these other resources and feel free to -[open an issue](https://gitlab.com/gitlab-org/gitlab/issues/new) +[open an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/new) to request additional material: - [Scaling GitLab](../../administration/reference_architectures/index.md): diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index fbc81da20d4..3cf963bdf57 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -177,7 +177,7 @@ Click **"Save"** for the changes to take effect. domain registrar which points to the public IP address of your Azure VM. If you do this, you'll need to make sure your VM is configured to use a _static_ public IP address (i.e. not a _dynamic_ one) or you will have to reconfigure the DNS `A` record each time Azure reassigns your VM a new public IP -address. Read [IP address types and allocation methods in Azure](https://docs.microsoft.com/en-us/azure/virtual-network/virtual-network-ip-addresses-overview-arm) to learn more. +address. Read [Public IP addresses](https://docs.microsoft.com/en-us/azure/virtual-network/public-ip-addresses) to learn more. ## Let's open some ports diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index ccfb97afe28..fe32b37a9ed 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -31,12 +31,12 @@ locally on either macOS or Linux. NOTE: **Note:** The rest of the steps are identical for macOS and Linux. -## Create new docker host +## Create new Docker host 1. Login to Digital Ocean. 1. Generate a new API token at <https://cloud.digitalocean.com/settings/api/tokens>. - This command will create a new DO droplet called `gitlab-test-env-do` that will act as a docker host. + This command will create a new DO droplet called `gitlab-test-env-do` that will act as a Docker host. NOTE: **Note:** 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. @@ -69,20 +69,20 @@ Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. In this example we'll create a GitLab EE 8.10.8 instance. -First connect the docker client to the docker host you created previously. +First connect the Docker client to the Docker host you created previously. ```shell eval "$(docker-machine env gitlab-test-env-do)" ``` -You can add this to your `~/.bash_profile` file to ensure the `docker` client uses the `gitlab-test-env-do` docker host +You can add this to your `~/.bash_profile` file to ensure the `docker` client uses the `gitlab-test-env-do` Docker host ### Create new GitLab container - HTTP port: `8888` - SSH port: `2222` - Set `gitlab_shell_ssh_port` using `--env GITLAB_OMNIBUS_CONFIG` -- Hostname: IP of docker host +- Hostname: IP of Docker host - Container name: `gitlab-test-8.10` - GitLab version: **EE** `8.10.8-ee.0` @@ -108,7 +108,7 @@ gitlab/gitlab-ee:$VERSION ### Connect to the GitLab container -#### Retrieve the docker host IP +#### Retrieve the Docker host IP ```shell docker-machine ip gitlab-test-env-do diff --git a/doc/install/google_cloud_platform/img/boot_disk.png b/doc/install/google_cloud_platform/img/boot_disk.png Binary files differdeleted file mode 100644 index b9f7eed6601..00000000000 --- a/doc/install/google_cloud_platform/img/boot_disk.png +++ /dev/null diff --git a/doc/install/google_cloud_platform/img/vm_details.png b/doc/install/google_cloud_platform/img/vm_details.png Binary files differindex 85b9ca066c8..aab9a46fa11 100644 --- a/doc/install/google_cloud_platform/img/vm_details.png +++ b/doc/install/google_cloud_platform/img/vm_details.png diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index 433eeda00b1..8ca5c5c266a 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -33,13 +33,13 @@ To deploy GitLab on GCP you first need to create a virtual machine: ![Search for GitLab](img/launch_vm.png) 1. On the next page, you can select the type of VM as well as the - estimated costs. Provide the name of the instance, desired datacenter, and machine type. Note that GitLab recommends at least 2 vCPU's and 4GB of RAM. + estimated costs. Provide the name of the instance, desired datacenter, and machine type. + Note our [hardware requirements for different user base sizes](../requirements.md#hardware-requirements). ![Launch on Compute Engine](img/vm_details.png) -1. Click **Change** under Boot disk to select the size, type, and desired operating system. GitLab supports a [variety of linux operating systems](../requirements.md), including Ubuntu and Debian. Click **Select** when finished. - - ![Deploy in progress](img/boot_disk.png) +1. To select the size, type, and desired [operating system](../requirements.md#supported-linux-distributions), + click **Change** under `Boot disk`. Click **Select** when finished. 1. As a last step allow HTTP and HTTPS traffic, then click **Create**. The process will finish in a few seconds. diff --git a/doc/install/installation.md b/doc/install/installation.md index dd619e9e7b3..0997062006d 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -134,7 +134,7 @@ Make sure you have the right version of Git installed: # Install Git sudo apt-get install -y git-core -# Make sure Git is version 2.26.2 or higher (minimal supported version is 2.22.0) +# Make sure Git is version 2.27.0 or higher (minimal supported version is 2.25.0) git --version ``` @@ -142,7 +142,7 @@ Starting with GitLab 12.0, Git is required to be compiled with `libpcre2`. Find out if that's the case: ```shell -ldd $(which git) | grep pcre2 +ldd $(command -v git) | grep pcre2 ``` The output should contain `libpcre2-8.so.0`. @@ -181,9 +181,9 @@ sudo make install # Download and compile from source cd /tmp -curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.26.2.tar.gz -echo 'e1c17777528f55696815ef33587b1d20f5eec246669f3b839d15dbfffad9c121 git-2.26.2.tar.gz' | shasum -a256 -c - && tar -xzf git-2.26.2.tar.gz -cd git-2.26.2/ +curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.27.0.tar.gz +echo '77ded85cbe42b1ffdc2578b460a1ef5d23bcbc6683eabcafbb0d394dffe2e787 git-2.27.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.27.0.tar.gz +cd git-2.27.0/ ./configure --with-libpcre make prefix=/usr/local all @@ -200,7 +200,7 @@ needs to be installed. sudo apt-get install -y graphicsmagick ``` -**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://gitlab.com/gitlab-org/gitlab-foss/issues/12754) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: +**Note:** In order to receive mail notifications, make sure to install a mail server. By default, Debian is shipped with exim4 but this [has problems](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12754) while Ubuntu does not ship with one. The recommended mail server is postfix and you can install it with: ```shell sudo apt-get install -y postfix @@ -208,6 +208,13 @@ sudo apt-get install -y postfix Then select 'Internet Site' and press enter to confirm the hostname. +[GitLab Workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse#dependencies) +requires `exiftool` to remove EXIF data from uploaded images. + +```shell +sudo apt-get install -y libimage-exiftool-perl +``` + ## 2. Ruby The Ruby interpreter is required to run GitLab. @@ -216,10 +223,9 @@ The Ruby interpreter is required to run GitLab. dropped support for Ruby 2.5.x. The use of Ruby version managers such as [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv) or [chruby](https://github.com/postmodern/chruby) with GitLab -in production, frequently leads to hard to diagnose problems. For example, -GitLab Shell is called from OpenSSH, and having a version manager can prevent -pushing and pulling over SSH. Version managers are not supported and we strongly -advise everyone to follow the instructions below to use a system Ruby. +in production, frequently leads to hard to diagnose problems. Version managers +are not supported and we strongly advise everyone to follow the instructions +below to use a system Ruby. Linux distributions generally have older versions of Ruby available, so these instructions are designed to install Ruby from the official source code. @@ -234,9 +240,9 @@ Download Ruby and compile it: ```shell mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.5.tar.gz -echo '1416ce288fb8bfeae07a12b608540318c9cace71 ruby-2.6.5.tar.gz' | shasum -c - && tar xzf ruby-2.6.5.tar.gz -cd ruby-2.6.5 +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.6.tar.gz +echo '2d78048e293817f38d4ede4ebc7873013e97bb0b ruby-2.6.6.tar.gz' | shasum -c - && tar xzf ruby-2.6.6.tar.gz +cd ruby-2.6.6 ./configure --disable-install-rdoc make @@ -565,8 +571,8 @@ If you want to use Kerberos for user authentication, omit `kerberos` in the `--w GitLab Shell is an SSH access and repository management software developed specially for GitLab. ```shell -# Run the installation task for gitlab-shell (replace `REDIS_URL` if needed): -sudo -u git -H bundle exec rake gitlab:shell:install REDIS_URL=unix:/var/run/redis/redis.sock RAILS_ENV=production SKIP_STORAGE_VALIDATION=true +# Run the installation task for gitlab-shell: +sudo -u git -H bundle exec rake gitlab:shell:install RAILS_ENV=production # By default, the gitlab-shell config is generated from your main GitLab config. # You can review (and modify) the gitlab-shell config as follows: @@ -579,13 +585,6 @@ If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional ste NOTE: **Note:** Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with `Check GitLab API access: FAILED. code: 401` and pushing commits will be rejected with `[remote rejected] master -> master (hook declined)`. -NOTE: **Note:** -GitLab Shell application startup time can be greatly reduced by disabling RubyGems. This can be done in several ways: - -- Export `RUBYOPT=--disable-gems` environment variable for the processes. -- Compile Ruby with `configure --disable-rubygems` to disable RubyGems by default. Not recommended for system-wide Ruby. -- Omnibus GitLab [replaces the *shebang* line of the `gitlab-shell/bin/*` scripts](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1707). - ### Install GitLab Workhorse GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). The @@ -986,7 +985,7 @@ Using Sidekiq directly will still be supported until 14.0. So if you're experien 1. Edit the system `init.d` script to remove the `SIDEKIQ_WORKERS` flag. If you have `/etc/default/gitlab`, then you should edit it instead. 1. Restart GitLab. -1. [Create an issue](https://gitlab.com/gitlab-org/gitlab/issues/-/new) describing the problem. +1. [Create an issue](https://gitlab.com/gitlab-org/gitlab/-/issues/-/new) describing the problem. ## Troubleshooting diff --git a/doc/install/ldap.md b/doc/install/ldap.md index d8d54864586..164478f09f7 100644 --- a/doc/install/ldap.md +++ b/doc/install/ldap.md @@ -1,5 +1,5 @@ --- -redirect_to: '../administration/auth/ldap.md' +redirect_to: '../administration/auth/ldap/index.md' --- -This document was moved to [another location](../administration/auth/ldap.md). +This document was moved to [another location](../administration/auth/ldap/index.md). diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index fd81b7f6caf..7ae23d6831e 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -253,7 +253,7 @@ related object definitions to be created together, as well as a set of parameters for those objects. The template for GitLab resides in the Omnibus GitLab repository under the -docker directory. Let's download it locally with `wget`: +Docker directory. Let's download it locally with `wget`: ```shell wget https://gitlab.com/gitlab-org/omnibus-gitlab/raw/master/docker/openshift-template.json @@ -324,7 +324,7 @@ Now that we configured this, let's see how to manage and scale GitLab. Setting up GitLab for the first time might take a while depending on your internet connection and the resources you have attached to the all-in-one VM. -GitLab's docker image is quite big (~500MB), so you'll have to wait until +GitLab's Docker image is quite big (~500MB), so you'll have to wait until it's downloaded and configured before you use it. ### Watch while GitLab gets deployed diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 09ad5f9afd7..0673f3e7ea3 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -35,7 +35,7 @@ Please see the [installation from source guide](installation.md) and the [instal ### Microsoft Windows GitLab is developed for Linux-based operating systems. -It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab/issues/22337). +It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/22337). Please consider using a virtual machine to run GitLab. ## Software requirements @@ -45,29 +45,29 @@ Please consider using a virtual machine to run GitLab. GitLab requires Ruby (MRI) 2.6. Beginning in GitLab 12.2, we no longer support Ruby 2.5 and lower. You must use the standard MRI implementation of Ruby. -We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com), but GitLab +We love [JRuby](https://www.jruby.org/) and [Rubinius](https://github.com/rubinius/rubinius#the-rubinius-language-platform), but GitLab needs several Gems that have native extensions. ### Go versions -The minimum required Go version is 1.12. +The minimum required Go version is 1.13. ### Git versions -GitLab 11.11 and higher only supports Git 2.21.x and newer, and -[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-foss/issues/54255). +GitLab 11.11 and higher only supports Git 2.24.x and newer, and +[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54255). ### Node.js versions Beginning in GitLab 12.9, we only support node.js 10.13.0 or higher, and we have dropped support for node.js 8. (node.js 6 support was dropped in GitLab 11.8) -We recommend Node 12.x, as it is faster. +We recommend Node 12.x, as it's faster. GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets, which requires a minimum version of Node.js 10.13.0. -You can check which version you are running with `node -v`. If you are running +You can check which version you're running with `node -v`. If you're running a version older than `v10.13.0`, you need to update it to a newer version. You can find instructions to install from community maintained packages or compile from source at the [Node.js website](https://nodejs.org/en/download/). @@ -80,122 +80,82 @@ GitLab requires Redis 5.0+. Beginning in GitLab 13.0, lower versions are not sup ### Storage -The necessary hard drive space largely depends on the size of the repos you want to store in GitLab but as a *rule of thumb* you should have at least as much free space as all your repos combined take up. +The necessary hard drive space largely depends on the size of the repositories you want to store in GitLab but as a *rule of thumb* you should have at least as much free space as all your repositories combined take up. -If you want to be flexible about growing your hard drive space in the future consider mounting it using LVM so you can add more hard drives when you need them. +If you want to be flexible about growing your hard drive space in the future consider mounting it using [logical volume management (LVM)](https://en.wikipedia.org/wiki/Logical_volume_management) so you can add more hard drives when you need them. Apart from a local hard drive you can also mount a volume that supports the network file system (NFS) protocol. This volume might be located on a file server, a network attached storage (NAS) device, a storage area network (SAN) or on an Amazon Web Services (AWS) Elastic Block Store (EBS) volume. -If you have enough RAM memory and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) will improve the responsiveness of GitLab. +If you have enough RAM and a recent CPU the speed of GitLab is mainly limited by hard drive seek times. Having a fast drive (7200 RPM and up) or a solid state drive (SSD) will improve the responsiveness of GitLab. -NOTE: **Note:** Since file system performance may affect GitLab's overall performance, we do not recommend using EFS for storage. See the [relevant documentation](../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) for more details. +NOTE: **Note:** Since file system performance may affect GitLab's overall performance, [we don't recommend using AWS EFS for storage](../administration/high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs). ### CPU -This is the recommended minimum hardware for a handful of example GitLab user base sizes. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size. +CPU requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size. -- 1 core supports up to 100 users but the application can be a bit slower due to having all workers and background jobs running on the same core -- **2 cores** is the **recommended** minimum number of cores and supports up to 100 users -- 4 cores supports up to 500 users -- 8 cores supports up to 1,000 users -- 32 cores supports up to 5,000 users +The following is the recommended minimum CPU hardware guidance for a handful of example GitLab user base sizes. + +- **4 cores** is the **recommended** minimum number of cores and supports up to 500 users +- 8 cores supports up to 1000 users - More users? Consult the [reference architectures page](../administration/reference_architectures/index.md) ### Memory -This is the recommended minimum hardware for a handful of example GitLab user base sizes. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size. +Memory requirements are dependent on the number of users and expected workload. Your exact needs may be more, depending on your workload. Your workload is influenced by factors such as - but not limited to - how active your users are, how much automation you use, mirroring, and repo/change size. -You need at least 8GB of addressable memory (RAM + swap) to install and use GitLab! -The operating system and any other running applications will also be using memory -so keep in mind that you need at least 4GB available before running GitLab. With -less memory GitLab will give strange errors during the reconfigure run and 500 -errors during usage. +The following is the recommended minimum Memory hardware guidance for a handful of example GitLab user base sizes. -- 4GB RAM + 4GB swap supports up to 100 users but it will be very slow -- **8GB RAM** is the **recommended** minimum memory size for all installations and supports up to 100 users -- 16GB RAM supports up to 500 users -- 32GB RAM supports up to 1,000 users -- 128GB RAM supports up to 5,000 users +- **4GB RAM** is the **required** minimum memory size and supports up to 500 users + - Our [Memory Team](https://about.gitlab.com/handbook/engineering/development/enablement/memory/) is working to reduce the memory requirement. +- 8GB RAM supports up to 1000 users - More users? Consult the [reference architectures page](../administration/reference_architectures/index.md) -We recommend having at least [2GB of swap on your server](https://askubuntu.com/a/505344/310789), even if you currently have -enough available RAM. Having swap will help reduce the chance of errors occurring -if your available memory changes. We also recommend [configuring the kernel's swappiness setting](https://askubuntu.com/a/103916) +In addition to the above, we generally recommend having at least 2GB of swap on your server, +even if you currently have enough available RAM. Having swap will help reduce the chance of errors occurring +if your available memory changes. We also recommend configuring the kernel's swappiness setting to a low value like `10` to make the most of your RAM while still having the swap available when needed. -Our [Memory Team](https://about.gitlab.com/handbook/engineering/development/enablement/memory/) is actively working to reduce the memory requirement. - -NOTE: **Note:** The 25 workers of Sidekiq will show up as separate processes in your process overview (such as `top` or `htop`) but they share the same RAM allocation since Sidekiq is a multithreaded application. Please see the section below about Unicorn workers for information about how many you need for those. - ## Database -The server running the database should have _at least_ 5-10 GB of storage -available, though the exact requirements depend on the size of the GitLab -installation (e.g. the number of users, projects, etc). - -We currently support the following databases: - -- PostgreSQL - +PostgreSQL is the only supported database, which is bundled with the Omnibus GitLab package. +You can also use an [external PostgreSQL database](https://docs.gitlab.com/omnibus/settings/database.html#using-a-non-packaged-postgresql-database-management-server). Support for MySQL was removed in GitLab 12.1. Existing users using GitLab with MySQL/MariaDB are advised to [migrate to PostgreSQL](../update/mysql_to_postgresql.md) before upgrading. ### PostgreSQL Requirements +The server running PostgreSQL should have _at least_ 5-10 GB of storage +available, though the exact requirements [depend on the number of users](../administration/reference_architectures/index.md). + We highly recommend users to use the minimum PostgreSQL versions specified below as these are the versions used for development and testing. GitLab version | Minimum PostgreSQL version -|- 10.0 | 9.6 12.10 | 11 +13.0 | 11 -Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every -GitLab database. This extension can be enabled (using a PostgreSQL super user) -by running the following query for every database: - -```sql -CREATE EXTENSION pg_trgm; -``` +You must also ensure the `pg_trgm` extension is loaded into every +GitLab database. This extension [can be enabled](https://www.postgresql.org/docs/11/sql-createextension.html) using a PostgreSQL super user. -On some systems you may need to install an additional package (e.g. +On some systems you may need to install an additional package (for example, `postgresql-contrib`) for this extension to become available. -NOTE: **Note:** Support for PostgreSQL 9.6 and 10 will be removed in GitLab 13.0 so that GitLab can benefit from PostgreSQL 11 improvements, such as partitioning. For the schedule on adding support for PostgreSQL 11 and 12, see [the related epic](https://gitlab.com/groups/gitlab-org/-/epics/2184). For the release schedule for GitLab 13.0, see [GitLab's release and maintenance policy](../policy/maintenance.md). +NOTE: **Note:** Support for [PostgreSQL 9.6 and 10 has been removed in GitLab 13.0](https://about.gitlab.com/releases/2020/05/22/gitlab-13-0-released/#postgresql-11-is-now-the-minimum-required-version-to-install-gitlab) so that GitLab can benefit from PostgreSQL 11 improvements, such as partitioning. For the schedule of transitioning to PostgreSQL 12, see [the related epic](https://gitlab.com/groups/gitlab-org/-/epics/2184). #### Additional requirements for GitLab Geo -If you are using [GitLab Geo](../development/geo.md): +If you're using [GitLab Geo](../administration/geo/replication/index.md): - We strongly recommend running Omnibus-managed instances as they are actively developed and tested. We aim to be compatible with most external (not managed - by Omnibus) databases (for example, AWS RDS) but we do not guarantee - compatibility. -- The - [tracking database](../development/geo.md#using-the-tracking-database) - requires the - [postgres_fdw](https://www.postgresql.org/docs/11/postgres-fdw.html) - extension. - -```sql -CREATE EXTENSION postgres_fdw; -``` - -## Unicorn Workers - -For most instances we recommend using: (CPU cores * 1.5) + 1 = Unicorn workers. -For example a node with 4 cores would have 7 Unicorn workers. - -For all machines that have 2GB and up we recommend a minimum of three Unicorn workers. -If you have a 1GB machine we recommend to configure only two Unicorn workers to prevent excessive -swapping. - -As long as you have enough available CPU and memory capacity, it's okay to increase the number of -Unicorn workers and this will usually help to reduce the response time of the applications and -increase the ability to handle parallel requests. - -To change the Unicorn workers when you have the Omnibus package (which defaults to the -recommendation above) please see [the Unicorn settings in the Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/unicorn.html). + by Omnibus) databases (for example, [AWS Relational Database Service (RDS)](https://aws.amazon.com/rds/)) but we don't guarantee compatibility. +- You must also ensure the `postgres_fdw` extension is loaded into every + GitLab database. This extension + [can be enabled](https://www.postgresql.org/docs/11/sql-createextension.html) + using a PostgreSQL super user. ## Puma settings @@ -204,7 +164,7 @@ Omnibus GitLab defaults to the recommended Puma settings. Regardless of installa tune the Puma settings. If you're using Omnibus GitLab, see [Puma settings](https://docs.gitlab.com/omnibus/settings/puma.html) -for instructions on changing the Puma settings. +for instructions on changing the Puma settings. If you're using the GitLab Helm chart, see the [Webservice chart](https://docs.gitlab.com/charts/charts/gitlab/webservice/index.html). ### Puma workers @@ -228,10 +188,26 @@ of [legacy Rugged code](../development/gitaly.md#legacy-rugged-code). - If the operating system has a maximum 2 GB of memory, the recommended number of threads is `1`. A higher value will result in excess swapping, and decrease performance. - If legacy Rugged code is in use, the recommended number of threads is `1`. -- In all other cases, the recommended number of threads is `4`. We do not recommend setting this +- In all other cases, the recommended number of threads is `4`. We don't recommend setting this higher, due to how [Ruby MRI multi-threading](https://en.wikipedia.org/wiki/Global_interpreter_lock) works. +## Unicorn Workers + +For most instances we recommend using: (CPU cores * 1.5) + 1 = Unicorn workers. +For example a node with 4 cores would have 7 Unicorn workers. + +For all machines that have 2GB and up we recommend a minimum of three Unicorn workers. +If you have a 1GB machine we recommend to configure only two Unicorn workers to prevent excessive +swapping. + +As long as you have enough available CPU and memory capacity, it's okay to increase the number of +Unicorn workers and this will usually help to reduce the response time of the applications and +increase the ability to handle parallel requests. + +To change the Unicorn workers when you have the Omnibus package (which defaults to the +recommendation above) please see [the Unicorn settings in the Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/unicorn.html). + ## Redis and Sidekiq Redis stores all user sessions and the background task queue. @@ -257,11 +233,11 @@ to install GitLab on. Depending on how you decide to configure GitLab Runner and what tools you use to exercise your application in the CI environment, GitLab Runner can consume significant amount of available memory. -Memory consumption calculations, that are available above, will not be valid if +Memory consumption calculations, that are available above, won't be valid if you decide to run GitLab Runner and the GitLab Rails application on the same machine. -It is also not safe to install everything on a single machine, because of the +It's also not safe to install everything on a single machine, because of the [security reasons](https://docs.gitlab.com/runner/security/), especially when you plan to use shell executor with GitLab Runner. @@ -282,24 +258,24 @@ For reference, GitLab.com's [auto-scaling shared runner](../user/gitlab_com/inde ## Supported web browsers -CAUTION: **Caution:** With GitLab 13.0 (May 2020) we are removing official support for Internet Explorer 11. +CAUTION: **Caution:** With GitLab 13.0 (May 2020) we have removed official support for Internet Explorer 11. With the release of GitLab 13.4 (September 2020) we will remove all code that supports Internet Explorer 11. -You can provide feedback [on this issue](https://gitlab.com/gitlab-org/gitlab/issues/197987) or via your usual support channels. +You can provide feedback [on this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/197987) or via your usual support channels. GitLab supports the following web browsers: -- Firefox -- Chrome/Chromium -- Safari -- Microsoft Edge -- Internet Explorer 11 (until May 2020) +- [Mozilla Firefox](https://www.mozilla.org/en-US/firefox/new/) +- [Google Chrome](https://www.google.com/chrome/) +- [Chromium](https://www.chromium.org/getting-involved/dev-channel) +- [Apple Safari](https://www.apple.com/safari/) +- [Microsoft Edge](https://www.microsoft.com/en-us/edge) For the listed web browsers, GitLab supports: - The current and previous major versions of browsers except Internet Explorer. - The current minor version of a supported major version. -NOTE: **Note:** We do not support running GitLab with JavaScript disabled in the browser and have no plans of supporting that +NOTE: **Note:** We don't support running GitLab with JavaScript disabled in the browser and have no plans of supporting that in the future because we have features such as Issue Boards which require JavaScript extensively. <!-- ## Troubleshooting |