summaryrefslogtreecommitdiff
path: root/doc/install
diff options
context:
space:
mode:
authorGitLab Bot <gitlab-bot@gitlab.com>2021-06-16 18:25:58 +0000
committerGitLab Bot <gitlab-bot@gitlab.com>2021-06-16 18:25:58 +0000
commita5f4bba440d7f9ea47046a0a561d49adf0a1e6d4 (patch)
treefb69158581673816a8cd895f9d352dcb3c678b1e /doc/install
parentd16b2e8639e99961de6ddc93909f3bb5c1445ba1 (diff)
downloadgitlab-ce-a5f4bba440d7f9ea47046a0a561d49adf0a1e6d4.tar.gz
Add latest changes from gitlab-org/gitlab@14-0-stable-eev14.0.0-rc42
Diffstat (limited to 'doc/install')
-rw-r--r--doc/install/README.md1
-rw-r--r--doc/install/azure/index.md3
-rw-r--r--doc/install/google_cloud_platform/index.md4
-rw-r--r--doc/install/installation.md38
-rw-r--r--doc/install/next_steps.md46
-rw-r--r--doc/install/postgresql_extensions.md22
-rw-r--r--doc/install/relative_url.md4
-rw-r--r--doc/install/requirements.md104
8 files changed, 99 insertions, 123 deletions
diff --git a/doc/install/README.md b/doc/install/README.md
index c815842480c..488d86f129d 100644
--- a/doc/install/README.md
+++ b/doc/install/README.md
@@ -1,5 +1,6 @@
---
redirect_to: 'index.md'
+remove_date: '2021-05-11'
---
This document was moved to [another location](index.md).
diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md
index 2fca70fd07a..0d62e4d1215 100644
--- a/doc/install/azure/index.md
+++ b/doc/install/azure/index.md
@@ -315,7 +315,8 @@ To fix this, fetch the new GPG key:
```shell
sudo apt install gpg-agent
-curl "https://gitlab-org.gitlab.io/omnibus-gitlab/gitlab_new_gpg.key" --output /tmp/omnibus_gitlab_gpg.key
+curl "https://gitlab-org.gitlab.io/omnibus-gitlab/gitlab_new_gpg.key" \
+ --output /tmp/omnibus_gitlab_gpg.key
sudo apt-key add /tmp/omnibus_gitlab_gpg.key
```
diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md
index 1b232c361ee..958f3e18c62 100644
--- a/doc/install/google_cloud_platform/index.md
+++ b/doc/install/google_cloud_platform/index.md
@@ -52,13 +52,13 @@ After a few seconds, the instance is created and available to log in. The next s
![Deploy settings](img/vm_created.png)
-1. Make a note of the IP address of the instance, as you will need that in a later step. <!-- using future tense is okay here -->
+1. Make a note of the external IP address of the instance, as you will need that in a later step. <!-- using future tense is okay here -->
1. Click on the SSH button to connect to the instance.
1. A new window appears, with you logged into the instance.
![GitLab first sign in](img/ssh_terminal.png)
-1. Next, follow the instructions for installing GitLab for the operating system you choose, at <https://about.gitlab.com/install/>. You can use the IP address from the step above, as the hostname.
+1. Next, follow the instructions for installing GitLab for the operating system you choose, at <https://about.gitlab.com/install/>. You can use the external IP address you noted before as the hostname.
1. Congratulations! GitLab is now installed and you can access it via your browser. To finish installation, open the URL in your browser and provide the initial administrator password. The username for this account is `root`.
diff --git a/doc/install/installation.md b/doc/install/installation.md
index d6f8c9cedd3..572c6de18d0 100644
--- a/doc/install/installation.md
+++ b/doc/install/installation.md
@@ -24,7 +24,7 @@ they changed the location of directories or run services as the wrong user.
If you find a bug/error in this guide, **submit a merge request**
following the
-[contributing guide](https://gitlab.com/gitlab-org/gitlab/blob/master/CONTRIBUTING.md).
+[contributing guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/CONTRIBUTING.md).
## Consider the Omnibus package installation
@@ -40,11 +40,20 @@ can't be terminated and its memory usage grows over time.
## Select a version to install
-Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (e.g., `11-7-stable`).
+Make sure you view [this installation guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/install/installation.md) from the branch (version) of GitLab you would like to install (e.g., `11-7-stable`).
You can select the branch in the version dropdown in the top left corner of GitLab (below the menu bar).
If the highest number stable branch is unclear, check the [GitLab blog](https://about.gitlab.com/blog/) for installation guide links by version.
+## Software requirements
+
+| Software | Minimum version | Notes |
+| -------- | --------------- | ----- |
+| [Ruby](#2-ruby) | `2.7` | From GitLab 13.6, Ruby 2.7 is required. Ruby 3.0 is not supported yet (see [the relevant epic](https://gitlab.com/groups/gitlab-org/-/epics/5149) for the current status). You must use the standard MRI implementation of Ruby. 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](#3-go) | `1.15` | |
+| [Git](#git) | `2.31.x` | From GitLab 13.11, Git 2.31.x and later is required. It's highly recommended that you use the [Git version provided by Gitaly](#git). |
+| [Node.js](#4-node) | `12.22.1` | GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets. Node.js 14.x is recommended, as it's faster. You can check which version you're running with `node -v`. You need to update it to a newer version if needed. |
+
## GitLab directory structure
This is the main directory structure you end up with following the instructions
@@ -207,7 +216,7 @@ sudo apt-get install -y libimage-exiftool-perl
## 2. Ruby
The Ruby interpreter is required to run GitLab.
-See the [requirements page](requirements.md#ruby-versions) for the minimum
+See the [requirements section of this page](#software-requirements) for the minimum
Ruby requirements.
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
@@ -283,7 +292,7 @@ sudo adduser --disabled-login --gecos 'GitLab' git
## 6. Database
NOTE:
-In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 13.0 and later, we [require PostgreSQL 11+](requirements.md#postgresql-requirements).
+In GitLab 12.1 and later, only PostgreSQL is supported. In GitLab 14.0 and later, we [require PostgreSQL 12+](requirements.md#postgresql-requirements).
1. Install the database packages.
@@ -536,7 +545,6 @@ sudo -u git -H editor config/resque.yml
```
Make sure to edit both `gitlab.yml` and `puma.rb` to match your setup.
-If you want to use the Unicorn web server, see [Using Unicorn](#using-unicorn) for the additional steps.
If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps.
@@ -640,7 +648,7 @@ You then need to update `gitlab.yml`'s `production -> elasticsearch -> indexer_p
### Install GitLab Pages
-GitLab Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is optional and only needed if you wish to host static sites from within GitLab. The following commands install GitLab Pages in `/home/git/gitlab-pages`. For additional setup steps, consult the [administration guide](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/administration/pages/source.md) for your version of GitLab as the GitLab Pages daemon can be run several different ways.
+GitLab Pages uses [GNU Make](https://www.gnu.org/software/make/). This step is optional and only needed if you wish to host static sites from within GitLab. The following commands install GitLab Pages in `/home/git/gitlab-pages`. For additional setup steps, consult the [administration guide](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/administration/pages/source.md) for your version of GitLab as the GitLab Pages daemon can be run several different ways.
```shell
cd /home/git
@@ -987,24 +995,6 @@ You also need to change the corresponding options (e.g. `ssh_user`, `ssh_host`,
Apart from the always supported Markdown style, there are other rich text files that GitLab can display. But you might have to install a dependency to do so. See the [`github-markup` gem README](https://github.com/gitlabhq/markup#markups) for more information.
-### Using Unicorn
-
-As of GitLab 12.9, [Puma](https://github.com/puma/puma) has replaced Unicorn as the default web server for installations from source.
-If you want to switch back to Unicorn, follow these steps:
-
-1. Finish the GitLab setup so you have it up and running.
-1. Copy the supplied example Unicorn configuration file into place:
-
- ```shell
- cd /home/git/gitlab
-
- # Copy config file for the web server
- sudo -u git -H cp config/unicorn.rb.example config/unicorn.rb
- ```
-
-1. Edit the system `init.d` script and set `USE_WEB_SERVER="unicorn"`. If you have `/etc/default/gitlab`, then you should edit it instead.
-1. Restart GitLab.
-
### Using Sidekiq instead of Sidekiq Cluster
As of GitLab 12.10, Source installations are using `bin/sidekiq-cluster` for managing Sidekiq processes.
diff --git a/doc/install/next_steps.md b/doc/install/next_steps.md
index 3e73da123fb..4e4f1f01a08 100644
--- a/doc/install/next_steps.md
+++ b/doc/install/next_steps.md
@@ -9,26 +9,32 @@ info: To determine the technical writer assigned to the Stage/Group associated w
Here are a few resources you might want to check out after completing the
installation.
-## License
+## Email and notifications
-- [Upload a license](../user/admin_area/license.md) or [start a free trial](https://about.gitlab.com/free-trial/):
- Activate all GitLab Enterprise Edition functionality with a license.
-- [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers.
+- [SMTP](https://docs.gitlab.com/omnibus/settings/smtp.html): Configure SMTP
+ for proper email notifications support.
+
+## CI/CD
+
+- [Set up runners](https://docs.gitlab.com/runner/): Set up one or more GitLab
+ Runners, the agents that are responsible for all of the GitLab CI/CD features.
+- [GitLab Pages](../administration/pages/index.md): Configure GitLab Pages to
+ allow hosting of static sites.
+- [GitLab Registry](../administration/packages/container_registry.md): With the
+ GitLab Container Registry, every project can have its own space to store Docker
+ images.
## Security
- [Secure GitLab](../security/README.md#securing-your-gitlab-installation):
Recommended practices to secure your GitLab instance.
+- Sign up for the GitLab [Security Newsletter](https://about.gitlab.com/company/preference-center/) to get notified for security updates upon release.
## Authentication
- [LDAP](../administration/auth/ldap/index.md): Configure LDAP to be used as
an authentication mechanism for GitLab.
-
-## Email and notifications
-
-- [SMTP](https://docs.gitlab.com/omnibus/settings/smtp.html): Configure SMTP
- for proper email notifications support.
+- [SAML and OAuth](../integration/omniauth.md): Authenticate via online services like Okta, Google, Azure AD, and more.
## Backup and upgrade
@@ -40,15 +46,16 @@ installation.
policies governing version naming, as well as release pace for major, minor, patch,
and security releases.
-## CI/CD
+## License
-- [Set up runners](https://docs.gitlab.com/runner/): Set up one or more GitLab
- Runners, the agents that are responsible for all of the GitLab CI/CD features.
-- [GitLab Pages](../administration/pages/index.md): Configure GitLab Pages to
- allow hosting of static sites.
-- [GitLab Registry](../administration/packages/container_registry.md): With the
- GitLab Container Registry, every project can have its own space to store Docker
- images.
+- [Upload a license](../user/admin_area/license.md) or [start a free trial](https://about.gitlab.com/free-trial/):
+ Activate all GitLab Enterprise Edition functionality with a license.
+- [Pricing](https://about.gitlab.com/pricing/): Pricing for the different tiers.
+
+## Cross-repo Code Search
+
+- [Advanced Search](../integration/elasticsearch.md): Leverage Elasticsearch for
+ faster, more advanced code search across your entire GitLab instance.
## Scaling and replication
@@ -56,8 +63,3 @@ installation.
GitLab supports several different types of clustering.
- [Geo replication](../administration/geo/index.md):
Geo is the solution for widely distributed development teams.
-
-## Search
-
-- [Advanced Search](../integration/elasticsearch.md): Leverage Elasticsearch for
- faster, more advanced code search across your entire GitLab instance.
diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md
index 663ec547733..80bbb0671b9 100644
--- a/doc/install/postgresql_extensions.md
+++ b/doc/install/postgresql_extensions.md
@@ -54,7 +54,19 @@ In order to install a PostgreSQL extension, this procedure should be followed:
On some systems you may need to install an additional package (for example,
`postgresql-contrib`) for certain extensions to become available.
-## A typical migration failure scenario
+## Typical failure scenarios
+
+The following is an example of a new GitLab installation failing because the extension hasn't been
+installed first.
+
+```shell
+---- Begin output of "bash" "/tmp/chef-script20210513-52940-d9b1gs" ----
+STDOUT: psql:/opt/gitlab/embedded/service/gitlab-rails/db/structure.sql:9: ERROR: permission denied to create extension "btree_gist"
+HINT: Must be superuser to create this extension.
+rake aborted!
+failed to execute:
+psql -v ON_ERROR_STOP=1 -q -X -f /opt/gitlab/embedded/service/gitlab-rails/db/structure.sql --single-transaction gitlabhq_production
+```
The following is an example of a situation when the extension hasn't been installed before running migrations.
In this scenario, the database migration fails to create the extension `btree_gist` because of insufficient
@@ -79,5 +91,9 @@ This query will grant the user superuser permissions, ensuring any database exte
can be installed through migrations.
```
-In order to recover from this situation, the extension needs to be installed manually using a superuser, and
-the database migration (or GitLab upgrade) can be retried afterwards.
+To recover from failed migrations, the extension must be installed manually by a superuser, and the
+GitLab upgrade completed by [re-running the database migrations](../administration/raketasks/maintenance.md#run-incomplete-database-migrations):
+
+```shell
+sudo gitlab-rake db:migrate
+```
diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md
index d04f55c43a3..8b629e9084e 100644
--- a/doc/install/relative_url.md
+++ b/doc/install/relative_url.md
@@ -29,7 +29,7 @@ relative URL is:
- `/home/git/gitlab/config/initializers/relative_url.rb`
- `/home/git/gitlab/config/gitlab.yml`
-- `/home/git/gitlab/config/unicorn.rb`
+- `/home/git/gitlab/config/puma.rb`
- `/home/git/gitlab-shell/config.yml`
- `/etc/default/gitlab`
@@ -88,7 +88,7 @@ Make sure to follow all steps below:
relative_url_root: /gitlab
```
-1. Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the
+1. Edit `/home/git/gitlab/config/puma.rb` and uncomment/change the
following line:
```ruby
diff --git a/doc/install/requirements.md b/doc/install/requirements.md
index 926af1795b9..3a8b7bf1004 100644
--- a/doc/install/requirements.md
+++ b/doc/install/requirements.md
@@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
type: reference
---
-# Requirements **(FREE SELF)**
+# Installation requirements **(FREE SELF)**
This page includes useful information on the supported Operating Systems as well
as the hardware requirements that are needed to install and use GitLab.
@@ -17,7 +17,7 @@ as the hardware requirements that are needed to install and use GitLab.
- Ubuntu (16.04/18.04/20.04)
- Debian (9/10)
- CentOS (7/8)
-- openSUSE Leap (15.1/15.2)
+- openSUSE Leap (15.2)
- SUSE Linux Enterprise Server (12 SP2/12 SP5)
- Red Hat Enterprise Linux (please use the CentOS packages and instructions)
- Scientific Linux (please use the CentOS packages and instructions)
@@ -47,55 +47,6 @@ Please consider using a virtual machine to run GitLab.
## Software requirements
-### Ruby versions
-
-From GitLab 13.6:
-
-- Ruby 2.7 and later is required.
-
-From GitLab 12.2:
-
-- Ruby 2.6 and later is required.
-
-You must use the standard MRI implementation of Ruby.
-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.13.
-
-### Git versions
-
-From GitLab 13.11:
-
-- Git 2.31.x and later is required. We recommend you use the
- [Git version provided by Gitaly](installation.md#git).
-
-From GitLab 13.6:
-
-- Git 2.29.x and later is required.
-
-From GitLab 13.1:
-
-- Git 2.24.x and later is required.
-- Git 2.28.x and later [is recommended](https://gitlab.com/gitlab-org/gitaly/-/issues/2959).
-
-### 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 14.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'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/).
-
### Redis versions
GitLab 13.0 and later requires Redis version 4.0 or higher.
@@ -165,14 +116,16 @@ the following table) as these were used for development and testing:
|----------------|----------------------------|
| 10.0 | 9.6 |
| 13.0 | 11 |
+| 14.0 | 12 |
-You must also ensure the following extensions are [loaded into every
-GitLab database](postgresql_extensions.html):
+You must also ensure the following extensions are loaded into every
+GitLab database. [Read more about this requirement, and troubleshooting](postgresql_extensions.md).
| Extension | Minimum GitLab version |
| ------------ | ---------------------- |
| `pg_trgm` | 8.6 |
| `btree_gist` | 13.1 |
+| `plpgsql` | 11.7 |
NOTE:
Support for [PostgreSQL 9.6 and 10 was 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).
@@ -185,6 +138,35 @@ test based on those. We try to be compatible with most external (not managed by
Omnibus GitLab) databases (for example, [AWS Relational Database Service (RDS)](https://aws.amazon.com/rds/)),
but we can't guarantee compatibility.
+#### Gitaly Cluster database requirements
+
+[Read more in the Gitaly Cluster documentation](../administration/gitaly/praefect.md).
+
+#### Exclusive use of GitLab databases
+
+Databases created or used for GitLab, Geo, Gitaly Cluster, or other components should be for the
+exclusive use of GitLab. Do not make direct changes to the database, schemas, users, or other
+properties except when following procedures in the GitLab documentation or following the directions
+of GitLab Support or other GitLab engineers.
+
+- The main GitLab application currently uses three schemas:
+
+ - The default `public` schema
+ - `gitlab_partitions_static` (automatically created)
+ - `gitlab_partitions_dynamic` (automatically created)
+
+ No other schemas should be manually created.
+
+- GitLab may create new schemas as part of Rails database migrations. This happens when performing
+ a GitLab upgrade. The GitLab database account requires access to do this.
+
+- GitLab creates and modifies tables during the upgrade process, and also as part of normal
+ operations to manage partitioned tables.
+
+- You should not modify the GitLab schema (for example, adding triggers or modifying tables).
+ Database migrations are tested against the schema definition in the GitLab code base. GitLab
+ version upgrades may fail if the schema is modified.
+
## Puma settings
The recommended settings for Puma are determined by the infrastructure on which it's running.
@@ -220,22 +202,6 @@ of [legacy Rugged code](../administration/gitaly/index.md#direct-access-to-git-i
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 usually helps 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.