diff options
| author | Achilleas Pipinellis <axil@gitlab.com> | 2019-08-20 20:22:43 +0200 |
|---|---|---|
| committer | Achilleas Pipinellis <axil@gitlab.com> | 2019-08-20 20:22:43 +0200 |
| commit | e61308ce1d82e12e5087371469baea4a452875d1 (patch) | |
| tree | 62551a3ae4eab75e5af7e3b35358c07a51b2132f /doc/install | |
| parent | 4f323bb62fbe71a4352de25cab141f361a3fe1a6 (diff) | |
| parent | 2989ed078c1d45b0959dcecb1bc3c8f4740a3c0d (diff) | |
| download | gitlab-ce-docs-patch-71.tar.gz | |
Merge branch 'master' into docs-patch-71docs-patch-71
Diffstat (limited to 'doc/install')
22 files changed, 341 insertions, 690 deletions
diff --git a/doc/install/README.md b/doc/install/README.md index 9cc21412898..af98791c8e9 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -4,7 +4,7 @@ description: Read through the GitLab installation methods. type: index --- -# Installation **[CORE ONLY]** +# Installation **(CORE ONLY)** GitLab can be installed in most GNU/Linux distributions and in a number of cloud providers. To get the best experience from GitLab you need to balance diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 73eaf758923..358ba971049 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -59,10 +59,11 @@ Here's a list of the AWS services we will use, with links to pricing information - **ElastiCache**: An in-memory cache environment will be used to provide a High Availability 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. ## Creating an IAM EC2 instance role and profile + To minimize the permissions of the user, we'll create a new [IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) role with limited access: @@ -90,7 +91,7 @@ We'll now create a VPC, a virtual networking environment that you'll control: `10.0.0.0/16`. If you don't require dedicated hardware, you can leave "Tenancy" as default. Click **Yes, Create** when ready. -  +  ### Subnets @@ -107,16 +108,16 @@ RDS instances as well: for example `gitlab-public-10.0.0.0`, select the VPC we created previously, and at the IPv4 CIDR block let's give it a 24 subnet `10.0.0.0/24`: -  +  1. Follow the same steps to create all subnets: - | Name tag | Type |Availability Zone | CIDR block | - | -------- | ---- | ---------------- | ---------- | - | gitlab-public-10.0.0.0 | public | us-west-2a | 10.0.0.0 | - | gitlab-private-10.0.1.0 | private | us-west-2a | 10.0.1.0 | - | gitlab-public-10.0.2.0 | public | us-west-2b | 10.0.2.0 | - | gitlab-private-10.0.3.0 | private | us-west-2b | 10.0.3.0 | + | Name tag | Type |Availability Zone | CIDR block | + | -------- | ---- | ---------------- | ---------- | + | gitlab-public-10.0.0.0 | public | us-west-2a | 10.0.0.0 | + | gitlab-private-10.0.1.0 | private | us-west-2a | 10.0.1.0 | + | gitlab-public-10.0.2.0 | public | us-west-2b | 10.0.2.0 | + | gitlab-private-10.0.3.0 | private | us-west-2b | 10.0.3.0 | ### Route Table @@ -139,7 +140,7 @@ create a new one: 1. Select it from the table, and then under the **Actions** dropdown choose "Attach to VPC". -  +  1. Choose `gitlab-vpc` from the list and hit **Attach**. @@ -154,14 +155,14 @@ it receive traffic from any destination. as destination. In the target, select the `gitlab-gateway` we created previously. Hit **Save** once done. -  +  Next, we must associate the **public** subnets to the route table: 1. Select the **Subnet Associations** tab and hit **Edit**. 1. Check only the public subnet and hit **Save**. -  +  --- @@ -178,12 +179,12 @@ The security group is basically the firewall: Inbound Rules tab. You will need to open the SSH, HTTP, and HTTPS ports. Set the source to `0.0.0.0/0`. -  +  - TIP: **Tip:** - Based on best practices, you should allow SSH traffic from only a known - host or CIDR block. In that case, change the SSH source to be custom and give - it the IP you want to SSH from. + TIP: **Tip:** + Based on best practices, you should allow SSH traffic from only a known + host or CIDR block. In that case, change the SSH source to be custom and give + it the IP you want to SSH from. 1. When done, click **Save**. @@ -204,7 +205,7 @@ create the actual RDS instance. we defined them in the [subnets section](#subnets)). Click **Create** when ready. -  +  ### Creating the database @@ -214,27 +215,27 @@ Now, it's time to create the database: 1. Select PostgreSQL and click **Next**. 1. Since this is a production server, let's choose "Production". Click **Next**. 1. Let's see the instance specifications: - 1. Leave the license model as is (`postgresql-license`). - 1. For the version, select the latest of the 9.6 series (check the - [database requirements](../../install/requirements.md#postgresql-requirements)) - if there are any updates on this). - 1. For the size, let's select a `t2.medium` instance. - 1. Multi-AZ-deployment is recommended as redundancy, so choose "Create - replica in different zone". Read more at - [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html). - 1. A Provisioned IOPS (SSD) storage type is best suited for HA (though you can - choose a General Purpose (SSD) to reduce the costs). Read more about it at - [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). - -1. The rest of the settings on this page request a DB isntance identifier, username + 1. Leave the license model as is (`postgresql-license`). + 1. For the version, select the latest of the 9.6 series (check the + [database requirements](../../install/requirements.md#postgresql-requirements)) + if there are any updates on this). + 1. For the size, let's select a `t2.medium` instance. + 1. Multi-AZ-deployment is recommended as redundancy, so choose "Create + replica in different zone". Read more at + [High Availability (Multi-AZ)](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.MultiAZ.html). + 1. A Provisioned IOPS (SSD) storage type is best suited for HA (though you can + choose a General Purpose (SSD) to reduce the costs). Read more about it at + [Storage for Amazon RDS](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_Storage.html). + +1. The rest of the settings on this page request a DB instance identifier, username and a master password. We've chosen to use `gitlab-db-ha`, `gitlab` and a very secure password respectively. Keep these in hand for later. 1. Click **Next** to proceed to the advanced settings. 1. Make sure to choose our gitlab VPC, our subnet group, set public accessibility to **No**, and to leave it to create a new security group. The only additional - change which will be helpful is the database name for which we can use - `gitlabhq_production`. At the very bottom, there's an option to enable - auto updates to minor versions. You may want to turn it off. + change which will be helpful is the database name for which we can use + `gitlabhq_production`. At the very bottom, there's an option to enable + auto updates to minor versions. You may want to turn it off. 1. When done, click **Create database**. ### Installing the `pg_trgm` extension for PostgreSQL @@ -276,7 +277,7 @@ To set up Redis: Make sure to select our VPC and its [private subnets](#subnets). Click **Create** when ready. -  +  1. Select **Redis** on the left menu and click **Create** to create a new Redis cluster. Depending on your load, you can choose whether to enable @@ -284,16 +285,16 @@ To set up Redis: chance to deploy Redis in multi availability zones. In this guide, we chose not to enable it. 1. In the settings section: - 1. Give the cluster a name (`gitlab-redis`) and a description. - 1. For the version, select the latest of `3.2` series (e.g., `3.2.10`). - 1. Select the node type and the number of replicas. + 1. Give the cluster a name (`gitlab-redis`) and a description. + 1. For the version, select the latest of `3.2` series (e.g., `3.2.10`). + 1. Select the node type and the number of replicas. 1. In the advanced settings section: 1. Select the multi-AZ auto-failover option. 1. Select the subnet group we created previously. 1. Manually select the preferred availability zones, and under "Replica 2" choose a different zone than the other two. -  +  1. In the security settings, edit the security groups and choose the `gitlab-security-group` we had previously created. @@ -316,11 +317,11 @@ and add a custom TCP rule for port `6379` accessible within itself. On the EC2 dashboard, look for Load Balancer on the left column: 1. Click the **Create Load Balancer** button. - 1. Choose the Application Load Balancer. - 1. Give it a name (`gitlab-loadbalancer`) and set the scheme to "internet-facing". - 1. In the "Listeners" section, make sure it has HTTP and HTTPS. - 1. In the "Availability Zones" section, select the `gitlab-vpc` we have created - and associate the **public subnets**. + 1. Choose the Application Load Balancer. + 1. Give it a name (`gitlab-loadbalancer`) and set the scheme to "internet-facing". + 1. In the "Listeners" section, make sure it has HTTP and HTTPS. + 1. In the "Availability Zones" section, select the `gitlab-vpc` we have created + and associate the **public subnets**. 1. Click **Configure Security Settings** to go to the next section to select the TLS certificate. When done, go to the next step. 1. In the "Security Groups" section, create a new one by giving it a name @@ -355,7 +356,7 @@ Choose the AMI: where `<version>` the latest version as seen on the [releases page](https://about.gitlab.com/releases/). -  +  ### Choose an instance type @@ -504,19 +505,19 @@ The EBS volume will host the Git repositories data: 1. Tell GitLab to store its data in the new directory by editing `/etc/gitlab/gitlab.rb` with your editor: - ```ruby - git_data_dirs({ - "default" => { "path" => "/mnt/gitlab-data" } - }) - ``` + ```ruby + git_data_dirs({ + "default" => { "path" => "/mnt/gitlab-data" } + }) + ``` - where `/mnt/gitlab-data` the location where you will store the Git data. + where `/mnt/gitlab-data` the location where you will store the Git data. 1. Save the file and reconfigure GitLab: - ```sh - sudo gitlab-ctl reconfigure - ``` + ```sh + sudo gitlab-ctl reconfigure + ``` TIP: **Tip:** If you wish to add more than one data volumes to store the Git repositories, @@ -549,15 +550,15 @@ After you SSH into the instance, configure the domain name: 1. Open `/etc/gitlab/gitlab.rb` with your preferred editor. 1. Edit the `external_url` value: - ```ruby - external_url 'http://example.com' - ``` + ```ruby + external_url 'http://example.com' + ``` 1. Reconfigure GitLab: - ```sh - sudo gitlab-ctl reconfigure - ``` + ```sh + sudo gitlab-ctl reconfigure + ``` You should now be able to reach GitLab at the URL you defined. To use HTTPS (recommended), see the [HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https). @@ -608,9 +609,9 @@ To back up GitLab: 1. SSH into your instance. 1. Take a backup: - ```sh - sudo gitlab-rake gitlab:backup:create - ``` + ```sh + sudo gitlab-backup create + ``` ### Restoring GitLab from a backup @@ -626,16 +627,16 @@ released, you can update your GitLab instance: 1. SSH into your instance 1. Take a backup: - ```sh - sudo gitlab-rake gitlab:backup:create - ``` + ```sh + sudo gitlab-backup create + ``` 1. Update the repositories and install GitLab: - ```sh - sudo apt update - sudo apt install gitlab-ee - ``` + ```sh + sudo apt update + sudo apt install gitlab-ee + ``` After a few minutes, the new version should be up and running. diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index b1f79893baf..543a222bd25 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -67,18 +67,19 @@ The first items we need to configure are the basic settings of the underlying vi 1. Enter a `User name` - e.g. **"gitlab-admin"** 1. Select an `Authentication type`, either **SSH public key** or **Password**: - > **Note:** if you're unsure which authentication type to use, select **Password** + > **Note:** if you're unsure which authentication type to use, select **Password** + + 1. If you chose **SSH public key** - enter your `SSH public key` into the field provided + _(read the [SSH documentation](../../ssh/README.md) to learn more about how to set up SSH + public keys)_ + 1. If you chose **Password** - enter the password you wish to use _(this is the password that you + will use later in this tutorial to [SSH] into the VM, so make sure it's a strong password/passphrase)_ - 1. If you chose **SSH public key** - enter your `SSH public key` into the field provided - _(read the [SSH documentation][GitLab-Docs-SSH] to learn more about how to set up SSH - public keys)_ - 1. If you chose **Password** - enter the password you wish to use _(this is the password that you - will use later in this tutorial to [SSH] into the VM, so make sure it's a strong password/passphrase)_ 1. Choose the appropriate `Subscription` tier for your Azure account 1. Choose an existing `Resource Group` or create a new one - e.g. **"GitLab-CE-Azure"** - > **Note:** a "Resource group" is a way to group related resources together for easier administration. - > We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM. + > **Note:** a "Resource group" is a way to group related resources together for easier administration. + > We chose "GitLab-CE-Azure", but your resource group can have the same name as your VM. 1. Choose a `Location` - if you're unsure, select the default location @@ -248,6 +249,7 @@ rules in the list:  ## Connecting to GitLab + Use the domain name you set up earlier (or the public IP address) to visit your new GitLab instance in your browser. If everything has gone according to plan you should be presented with the following page, asking you to set a _new_ password for the administrator account automatically @@ -348,6 +350,7 @@ your VM, you can use the IP address in its place in the following command: ```bash ssh username@your-azure-domain-name.com ``` + Provide your password at the prompt to authenticate. #### SSH from Windows (PuTTY) @@ -404,25 +407,22 @@ on any cloud service you choose. ## Where to next? -Check out our other [Technical Articles][GitLab-Technical-Articles] or browse the [GitLab Documentation][GitLab-Docs] to learn more about GitLab. +Check out our other [Technical Articles](../../articles/index.md) or browse the [GitLab Documentation][GitLab-Docs](../../README.md) to learn more about GitLab. ### Useful links - [GitLab Community Edition][CE] - [GitLab Enterprise Edition][EE] - [Microsoft Azure][Azure] - - [Azure - Free Account FAQ][Azure-Free-Account-FAQ] - - [Azure - Marketplace][Azure-Marketplace] - - [Azure Portal][Azure-Portal] - - [Azure - Pricing Calculator][Azure-Pricing-Calculator] - - [Azure - Troubleshoot SSH Connections to an Azure Linux VM][Azure-Troubleshoot-SSH-Connection] - - [Azure - Properly Shutdown an Azure VM][Azure-Properly-Shutdown-VM] + - [Azure - Free Account FAQ][Azure-Free-Account-FAQ] + - [Azure - Marketplace][Azure-Marketplace] + - [Azure Portal][Azure-Portal] + - [Azure - Pricing Calculator][Azure-Pricing-Calculator] + - [Azure - Troubleshoot SSH Connections to an Azure Linux VM][Azure-Troubleshoot-SSH-Connection] + - [Azure - Properly Shutdown an Azure VM][Azure-Properly-Shutdown-VM] - [SSH], [PuTTY] and [Using SSH in PuTTY][Using-SSH-In-Putty] [Original-Blog-Post]: https://about.gitlab.com/2016/07/13/how-to-setup-a-gitlab-instance-on-microsoft-azure/ "How to Set up a GitLab Instance on Microsoft Azure" -[GitLab-Docs]: https://docs.gitlab.com/ce/README.html "GitLab Documentation" -[GitLab-Technical-Articles]: https://docs.gitlab.com/ce/articles/index.html "GitLab Technical Articles" -[GitLab-Docs-SSH]: https://docs.gitlab.com/ce/ssh/README.html "GitLab Documentation: SSH" [CE]: https://about.gitlab.com/features/ [EE]: https://about.gitlab.com/features/#ee-starter diff --git a/doc/install/database_mysql.md b/doc/install/database_mysql.md deleted file mode 100644 index cbb3b766b4e..00000000000 --- a/doc/install/database_mysql.md +++ /dev/null @@ -1,319 +0,0 @@ ---- -type: reference ---- - -# Database MySQL - -NOTE: **Note:** -We do not recommend using MySQL due to various issues. -For example, there have been bugs with case -[(in)sensitivity](https://dev.mysql.com/doc/refman/5.7/en/case-sensitivity.html). - -Bugs relating to case sensitivity: - -- <https://bugs.mysql.com/bug.php?id=65830> -- <https://bugs.mysql.com/bug.php?id=50909> -- <https://bugs.mysql.com/bug.php?id=65830> -- <https://bugs.mysql.com/bug.php?id=63164> - -## Initial database setup - -```sh -# Install the database packages -sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev - -# Ensure you have MySQL version 5.6 or later -mysql --version - -# Pick a MySQL root password (can be anything), type it and press enter -# Retype the MySQL root password and press enter - -# Secure your installation -sudo mysql_secure_installation - -# Login to MySQL -mysql -u root -p - -# Type the MySQL root password - -# Create a user for GitLab -# do not type the 'mysql>', this is part of the prompt -# change $password in the command below to a real password you pick -mysql> CREATE USER 'git'@'localhost' IDENTIFIED BY '$password'; - -# Ensure you can use the InnoDB engine which is necessary to support long indexes -# If this fails, check your MySQL config files (e.g. `/etc/mysql/*.cnf`, `/etc/mysql/conf.d/*`) for the setting "innodb = off" -mysql> SET storage_engine=INNODB; - -# If you have MySQL < 5.7.7 and want to enable utf8mb4 character set support with your GitLab install, you must set the following NOW: -mysql> SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda, innodb_large_prefix=1; - -# If you use MySQL with replication, or just have MySQL configured with binary logging, you need to run the following to allow the use of `TRIGGER`: -mysql> SET GLOBAL log_bin_trust_function_creators = 1; - -# Create the GitLab production database -mysql> CREATE DATABASE IF NOT EXISTS `gitlabhq_production` DEFAULT CHARACTER SET `utf8` COLLATE `utf8_general_ci`; - -# Grant the GitLab user necessary permissions on the database -mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, CREATE TEMPORARY TABLES, DROP, INDEX, ALTER, LOCK TABLES, REFERENCES, TRIGGER ON `gitlabhq_production`.* TO 'git'@'localhost'; - -# Quit the database session -mysql> \q - -# Try connecting to the new database with the new user -sudo -u git -H mysql -u git -p -D gitlabhq_production - -# Type the password you replaced $password with earlier - -# You should now see a 'mysql>' prompt - -# Quit the database session -mysql> \q -``` - -You are done installing the database for now and can go back to the rest of the installation. -Please proceed to the rest of the installation **before** running through the steps below. - -### `log_bin_trust_function_creators` - -If you use MySQL with replication, or just have MySQL configured with binary logging, all of your MySQL servers will need to have `log_bin_trust_function_creators` enabled to allow the use of `TRIGGER` in migrations. You have already set this global variable in the steps above, but to make it persistent, add the following to your `my.cnf` file: - -``` -log_bin_trust_function_creators=1 -``` - -### MySQL utf8mb4 support - -After installation or upgrade, remember to [convert any new tables](#tables-and-data-conversion-to-utf8mb4) to `utf8mb4`/`utf8mb4_general_ci`. - ---- - -GitLab 8.14 has introduced [a feature](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7420) requiring `utf8mb4` encoding to be supported in your GitLab MySQL Database, which is not the case if you have set up your database before GitLab 8.16. - -Follow the below instructions to ensure you use the most up to date requirements for your GitLab MySQL Database. - -**We are about to do the following:** - -- Ensure you can enable `utf8mb4` encoding and `utf8mb4_general_ci` collation for your GitLab DB, tables and data. -- Convert your GitLab tables and data from `utf8`/`utf8_general_ci` to `utf8mb4`/`utf8mb4_general_ci`. - -### Check for utf8mb4 support - -#### Check for InnoDB File-Per-Table Tablespaces - -We need to check, enable and maybe convert your existing GitLab DB tables to the [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) as a prerequisite for supporting **utfb8mb4 with long indexes** required by recent GitLab databases. - - # Login to MySQL - mysql -u root -p - - # Type the MySQL root password - mysql > use gitlabhq_production; - - # Check your MySQL version is >= 5.5.3 (GitLab requires 5.5.14+) - mysql > SHOW VARIABLES LIKE 'version'; - +---------------+-----------------+ - | Variable_name | Value | - +---------------+-----------------+ - | version | 5.5.53-0+deb8u1 | - +---------------+-----------------+ - - # Note where is your MySQL data dir for later: - mysql > select @@datadir; - +----------------+ - | @@datadir | - +----------------+ - | /var/lib/mysql | - +----------------+ - - # Note whether your MySQL server runs with innodb_file_per_table ON or OFF: - mysql> SELECT @@innodb_file_per_table; - +-------------------------+ - | @@innodb_file_per_table | - +-------------------------+ - | 1 | - +-------------------------+ - - # You can now quit the database session - mysql> \q - -> You need **MySQL 5.5.3 or later** to perform this update. - -Whatever the results of your checks above, we now need to check if your GitLab database has been created using [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) (i.e. `innodb_file_per_table` was set to **1** at initial setup time). - -NOTE: **Note:** -This setting is [enabled by default](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_file_per_table) since MySQL 5.6.6. - - # Run this command with root privileges, replace the data dir if different: - sudo ls -lh /var/lib/mysql/gitlabhq_production/*.ibd | wc -l - - # Run this command with root privileges, replace the data dir if different: - sudo ls -lh /var/lib/mysql/gitlabhq_production/*.frm | wc -l - -- **Case 1: a result > 0 for both commands** - -Congratulations, your GitLab database uses the right InnoDB tablespace format. - -However, you must still ensure that any **future tables** created by GitLab will still use the right format: - -- If `SELECT @@innodb_file_per_table` returned **1** previously, your server is running correctly. - - > It's however a requirement to check *now* that this setting is indeed persisted in your [`my.cnf`](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) file! - -- If `SELECT @@innodb_file_per_table` returned **0** previously, your server is not running correctly. - - > [Enable innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) by running in a MySQL session as root the command `SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda;` and persist the two settings in your [`my.cnf`](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) file. - -Now, if you have a **different result** returned by the 2 commands above, it means you have a **mix of tables format** uses in your GitLab database. This can happen if your MySQL server had different values for `innodb_file_per_table` in its life and you updated GitLab at different moments with those inconsistent values. So keep reading. - -- **Case 2: a result equals to "0" OR not the same result for both commands** - -Unfortunately, none or only some of your GitLab database tables use the GitLab requirement of [InnoDB File-Per-Table Tablespaces](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html). - -Let's enable what we need on the running server: - - # Login to MySQL - mysql -u root -p - - # Type the MySQL root password - - # Enable innodb_file_per_table and set innodb_file_format on the running server: - mysql > SET GLOBAL innodb_file_per_table=1, innodb_file_format=Barracuda; - - # You can now quit the database session - mysql> \q - -> Now, **persist** [innodb_file_per_table](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) and [innodb_file_format](https://dev.mysql.com/doc/refman/5.7/en/innodb-file-format-enabling.html) in your `my.cnf` file. - -Ensure at this stage that your GitLab instance is indeed **stopped**. - -Now, let's convert all the GitLab database tables to the new tablespace format: - - # Login to MySQL - mysql -u root -p - - # Type the MySQL root password - mysql > use gitlabhq_production; - - # Safety check: you should still have those values set as follows: - mysql> SELECT @@innodb_file_per_table, @@innodb_file_format; - +-------------------------+----------------------+ - | @@innodb_file_per_table | @@innodb_file_format | - +-------------------------+----------------------+ - | 1 | Barracuda | - +-------------------------+----------------------+ - - mysql > SELECT CONCAT('ALTER TABLE `', TABLE_NAME,'` ENGINE=InnoDB;') AS 'Copy & run these SQL statements:' FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA="gitlabhq_production" AND TABLE_TYPE="BASE TABLE"; - - # If previous query returned results, copy & run all shown SQL statements - - # You can now quit the database session - mysql> \q - ---- - -#### Check for proper InnoDB File Format, Row Format, Large Prefix and tables conversion - -We need to check, enable and probably convert your existing GitLab DB tables to use the [Barracuda InnoDB file format](https://dev.mysql.com/doc/refman/5.7/en/innodb-file-format.html), the [DYNAMIC row format](https://dev.mysql.com/doc/refman/5.7/en/glossary.html#glos_dynamic_row_format) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) as a second prerequisite for supporting **utfb8mb4 with long indexes** used by recent GitLab databases. - - # Login to MySQL - mysql -u root -p - - # Type the MySQL root password - mysql > use gitlabhq_production; - - # Set innodb_file_format and innodb_large_prefix on the running server: - # Note: These are the default settings only for MySQL 5.7.7 and later. - - mysql > SET GLOBAL innodb_file_format=Barracuda, innodb_large_prefix=1; - - # Your DB must be (still) using utf8/utf8_general_ci as default encoding and collation. - # We will NOT change the default encoding and collation on the DB in order to support future GitLab migrations creating tables - # that require "long indexes support" on installations using MySQL <= 5.7.9. - # However, when such migrations occur, you will have to follow this guide again to convert the newly created tables to the proper encoding/collation. - - # This should return the following: - mysql> SELECT @@character_set_database, @@collation_database; - +--------------------------+----------------------+ - | @@character_set_database | @@collation_database | - +--------------------------+----------------------+ - | utf8 | utf8_general_ci | - +--------------------------+----------------------+ - -> Now, ensure that [innodb_file_format](https://dev.mysql.com/doc/refman/5.7/en/innodb-multiple-tablespaces.html) and [innodb_large_prefix](http://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix) are **persisted** in your `my.cnf` file. - -#### Tables and data conversion to utf8mb4 - -Now that you have a persistent MySQL setup, you can safely upgrade tables after setup or upgrade time: - - # Convert tables not using ROW_FORMAT DYNAMIC: - - mysql> SELECT CONCAT('ALTER TABLE `', TABLE_NAME,'` ROW_FORMAT=DYNAMIC;') AS 'Copy & run these SQL statements:' FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA="gitlabhq_production" AND TABLE_TYPE="BASE TABLE" AND ROW_FORMAT!="Dynamic"; - - # !! If previous query returned results, copy & run all shown SQL statements - - # Convert tables/columns not using utf8mb4/utf8mb4_general_ci as encoding/collation: - - mysql > SET foreign_key_checks = 0; - - mysql > SELECT CONCAT('ALTER TABLE `', TABLE_NAME,'` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;') AS 'Copy & run these SQL statements:' FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_SCHEMA="gitlabhq_production" AND TABLE_COLLATION != "utf8mb4_general_ci" AND TABLE_TYPE="BASE TABLE"; - - # !! If previous query returned results, copy & run all shown SQL statements - - # Turn foreign key checks back on - mysql > SET foreign_key_checks = 1; - - # You can now quit the database session - mysql> \q - -Ensure your GitLab database configuration file uses a proper connection encoding and collation: - -`sudo -u git -H editor config/database.yml` - - production: - adapter: mysql2 - encoding: utf8mb4 - collation: utf8mb4_general_ci - -[Restart your GitLab instance](../administration/restart_gitlab.md). - -## MySQL strings limits - -After installation or upgrade, remember to run the `add_limits_mysql` Rake task: - -**Omnibus GitLab installations** - -```sh -sudo gitlab-rake add_limits_mysql -``` - -**Installations from source** - -```sh -bundle exec rake add_limits_mysql RAILS_ENV=production -``` - -The `text` type in MySQL has a different size limit than the `text` type in -PostgreSQL. In MySQL `text` columns are limited to ~65kB, whereas in PostgreSQL -`text` columns are limited up to ~1GB! - -The `add_limits_mysql` Rake task converts some important `text` columns in the -GitLab database to `longtext` columns, which can persist values of up to 4GB -(sometimes less if the value contains multibyte characters). - -Details can be found in the [PostgreSQL][postgres-text-type] and -[MySQL](https://dev.mysql.com/doc/refman/5.7/en/string-type-overview.html) manuals. - -[postgres-text-type]: http://www.postgresql.org/docs/9.2/static/datatype-character.html -[ce-38152]: https://gitlab.com/gitlab-org/gitlab-ce/issues/38152 - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 63bb941ad47..b6bf7c95527 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -36,30 +36,30 @@ The rest of the steps are identical for macOS and Linux. 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. + NOTE: **Note:** + 4GB is the minimum requirement for a Docker host that will run more than one GitLab instance. - - RAM: 4GB - - Name: `gitlab-test-env-do` - - Driver: `digitalocean` + - RAM: 4GB + - Name: `gitlab-test-env-do` + - Driver: `digitalocean` 1. Set the DO token: - ```sh - export DOTOKEN=<your generated token> - ``` + ```sh + export DOTOKEN=<your generated token> + ``` 1. Create the machine: - ```sh - docker-machine create \ - --driver digitalocean \ - --digitalocean-access-token=$DOTOKEN \ - --digitalocean-size "4gb" \ - gitlab-test-env-do - ``` + ```sh + docker-machine create \ + --driver digitalocean \ + --digitalocean-access-token=$DOTOKEN \ + --digitalocean-size "4gb" \ + gitlab-test-env-do + ``` Resource: <https://docs.docker.com/machine/drivers/digital-ocean/>. diff --git a/doc/install/docker.md b/doc/install/docker.md index 06da65189ba..e0cef71a4d8 100644 --- a/doc/install/docker.md +++ b/doc/install/docker.md @@ -10,7 +10,7 @@ GitLab provides official Docker images allowing you to easily take advantage of ## Omnibus GitLab based images -GitLab maintains a set of [official Docker images](https://hub.docker.com/r/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include: +GitLab maintains a set of [official Docker images](https://hub.docker.com/u/gitlab) based on our [Omnibus GitLab package](https://docs.gitlab.com/omnibus/README.html). These images include: - [GitLab Community Edition](https://hub.docker.com/r/gitlab/gitlab-ce/) - [GitLab Enterprise Edition](https://hub.docker.com/r/gitlab/gitlab-ee/) diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index 77c61acbfd4..be29bcc7cd7 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -30,16 +30,16 @@ To deploy GitLab on GCP you first need to create a virtual machine: 1. Go to <https://console.cloud.google.com/compute/instances> and log in with your Google credentials. 1. Click on **Create** -  +  -1. On the next page, you can select the type of VM as well as the +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. -  +  1. Click **Change** under Boot disk to select the size, type, and desired operating system. GitLab supports a [variety of linux operating systems][req], including Ubuntu and Debian. 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. @@ -53,13 +53,13 @@ After a few seconds, the instance will be created and available to log in. The n 1. Click on the SSH button to connect to the instance. 1. A new window will appear, with you logged into the instance. -  +  -1. Next, follow the instructions for installing GitLab for the operating system you choose, at <https://about.gitlab.com/installation/>. 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 IP address from the step above, 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`. -  +  ## Next steps @@ -83,31 +83,31 @@ here's how you configure GitLab to be aware of the change: 1. SSH into the VM. You can easily use the **SSH** button in the Google console and a new window will pop up. -  +  - In the future you might want to set up [connecting with an SSH key][ssh] - instead. + In the future you might want to set up [connecting with an SSH key][ssh] + instead. 1. Edit the config file of Omnibus GitLab using your favorite text editor: - ``` - sudo vim /etc/gitlab/gitlab.rb - ``` + ``` + sudo vim /etc/gitlab/gitlab.rb + ``` 1. Set the `external_url` value to the domain name you wish GitLab to have **without** `https`: - ``` - external_url 'http://gitlab.example.com' - ``` + ``` + external_url 'http://gitlab.example.com' + ``` - We will set up HTTPS in the next step, no need to do this now. + We will set up HTTPS in the next step, no need to do this now. 1. Reconfigure GitLab for the changes to take effect: - ``` - sudo gitlab-ctl reconfigure - ``` + ``` + sudo gitlab-ctl reconfigure + ``` 1. You can now visit GitLab using the domain name. @@ -128,9 +128,9 @@ GitLab can be configured to authenticate with other OAuth providers, LDAP, SAML, Kerberos, etc. Here are some documents you might be interested in reading: - [Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/) -- [Integration documentation](https://docs.gitlab.com/ce/integration/) -- [GitLab Pages configuration](https://docs.gitlab.com/ce/administration/pages/index.html) -- [GitLab Container Registry configuration](https://docs.gitlab.com/ce/administration/container_registry.html) +- [Integration documentation](../../integration/README.md) +- [GitLab Pages configuration](../../administration/pages/index.md) +- [GitLab Container Registry configuration](../../administration/container_registry.md) [freetrial]: https://console.cloud.google.com/freetrial "GCP free trial" [ip]: https://cloud.google.com/compute/docs/configure-instance-ip-addresses#promote_ephemeral_ip "Configuring an Instance's IP Addresses" diff --git a/doc/install/installation.md b/doc/install/installation.md index eb484dde545..295d9804497 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -6,7 +6,7 @@ type: howto This is the official installation guide to set up a production GitLab server using the source files. To set up a **development installation** or for many -other installation options, see the [main installation page](index.md). +other installation options, see the [main installation page](README.md). It was created for and tested on **Debian/Ubuntu** operating systems. Read [requirements.md](requirements.md) for hardware and operating system requirements. If you want to install on RHEL/CentOS, we recommend using the @@ -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.21.0 or higher +# Make sure Git is version 2.22.0 or higher git --version ``` @@ -167,13 +167,13 @@ cd pcre2-10.33 chmod +x configure ./configure --prefix=/usr --enable-jit make -make install +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.21.0.tar.gz -echo '85eca51c7404da75e353eba587f87fea9481ba41e162206a6f70ad8118147bee git-2.21.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.21.0.tar.gz -cd git-2.21.0/ +curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.22.0.tar.gz +echo 'a4b7e4365bee43caa12a38d646d2c93743d755d1cea5eab448ffb40906c9da0b git-2.22.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.22.0.tar.gz +cd git-2.22.0/ ./configure --with-libpcre make prefix=/usr/local all @@ -202,8 +202,8 @@ Then select 'Internet Site' and press enter to confirm the hostname. The Ruby interpreter is required to run GitLab. -**Note:** The current supported Ruby (MRI) version is 2.5.x. GitLab 11.6 - dropped support for Ruby 2.4.x. +**Note:** The current supported Ruby (MRI) version is 2.6.x. GitLab 12.2 + dropped support for Ruby 2.5.x. The use of Ruby version managers such as [RVM], [rbenv] or [chruby] with GitLab in production, frequently leads to hard to diagnose problems. For example, @@ -263,7 +263,7 @@ Since GitLab 8.17, GitLab requires the use of Node to compile JavaScript assets, and Yarn to manage JavaScript dependencies. The current minimum requirements for these are: -- `node` >= v8.10.0. +- `node` >= v8.10.0. (We recommend node 12.x as it is faster) - `yarn` >= v1.10.0. In many distros, @@ -271,8 +271,8 @@ the versions provided by the official package repositories are out of date, so we'll need to install through the following commands: ```sh -# install node v8.x -curl --location https://deb.nodesource.com/setup_8.x | sudo bash - +# install node v12.x +curl --location https://deb.nodesource.com/setup_12.x | sudo bash - sudo apt-get install -y nodejs curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - @@ -293,64 +293,63 @@ sudo adduser --disabled-login --gecos 'GitLab' git ## 6. Database -We recommend using a PostgreSQL database. For MySQL, see the [MySQL setup guide](database_mysql.md). - NOTE: **Note:** -Because we need to make use of extensions and concurrent index removal, you need at least PostgreSQL 9.2. +Starting from GitLab 12.1, only PostgreSQL is supported. Because we need to make +use of extensions and concurrent index removal, you need at least PostgreSQL 9.2. 1. Install the database packages: - ```sh - sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib - ``` + ```sh + sudo apt-get install -y postgresql postgresql-client libpq-dev postgresql-contrib + ``` 1. Create a database user for GitLab: - ```sh - sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;" - ``` + ```sh + sudo -u postgres psql -d template1 -c "CREATE USER git CREATEDB;" + ``` 1. Create the `pg_trgm` extension (required for GitLab 8.6+): - ```sh - sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" - ``` + ```sh + sudo -u postgres psql -d template1 -c "CREATE EXTENSION IF NOT EXISTS pg_trgm;" + ``` 1. Create the GitLab production database and grant all privileges on database: - ```sh - sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;" - ``` + ```sh + sudo -u postgres psql -d template1 -c "CREATE DATABASE gitlabhq_production OWNER git;" + ``` 1. Try connecting to the new database with the new user: - ```sh - sudo -u git -H psql -d gitlabhq_production - ``` + ```sh + sudo -u git -H psql -d gitlabhq_production + ``` 1. Check if the `pg_trgm` extension is enabled: - ```sh - SELECT true AS enabled - FROM pg_available_extensions - WHERE name = 'pg_trgm' - AND installed_version IS NOT NULL; - ``` + ```sh + SELECT true AS enabled + FROM pg_available_extensions + WHERE name = 'pg_trgm' + AND installed_version IS NOT NULL; + ``` - If the extension is enabled this will produce the following output: + If the extension is enabled this will produce the following output: - ``` - enabled - --------- - t - (1 row) - ``` + ``` + enabled + --------- + t + (1 row) + ``` 1. Quit the database session: - ```sh - gitlabhq_production> \q - ``` + ```sh + gitlabhq_production> \q + ``` ## 7. Redis @@ -493,7 +492,7 @@ sudo -u git -H editor config/resque.yml ``` CAUTION: **Caution:** -Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. +Make sure to edit both `gitlab.yml` and `unicorn.rb` to match your setup. If you want to use Puma web server, see [Using Puma](#using-puma) for the additional steps. NOTE: **Note:** @@ -502,13 +501,8 @@ If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional ste ### Configure GitLab DB Settings ```sh -# PostgreSQL only: sudo -u git cp config/database.yml.postgresql config/database.yml -# MySQL only: -sudo -u git cp config/database.yml.mysql config/database.yml - -# PostgreSQL only: # Remove host, username, and password lines from config/database.yml. # Once modified, the `production` settings will be as follows: # @@ -520,7 +514,7 @@ sudo -u git cp config/database.yml.mysql config/database.yml # sudo -u git -H editor config/database.yml -# MySQL and remote PostgreSQL only: +# Remote PostgreSQL only: # Update username/password in config/database.yml. # You only need to adapt the production settings (first part). # If you followed the database guide then please do as follows: @@ -528,7 +522,6 @@ sudo -u git -H editor config/database.yml # You can keep the double quotes around the password sudo -u git -H editor config/database.yml -# PostgreSQL and MySQL: # Make config/database.yml readable to git only sudo -u git -H chmod o-rwx config/database.yml ``` @@ -544,11 +537,7 @@ Make sure you have `bundle` (run `bundle -v`): - `< 2.x`. ```sh -# For PostgreSQL (note, the option says "without ... mysql") sudo -u git -H bundle install --deployment --without development test mysql aws kerberos - -# Or if you use MySQL (note, the option says "without ... postgres") -sudo -u git -H bundle install --deployment --without development test postgres aws kerberos ``` NOTE: **Note:** @@ -571,7 +560,7 @@ NOTE: **Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. 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)". +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: @@ -645,8 +634,8 @@ Gitaly must be running for the next section. gitlab_path=/home/git/gitlab gitaly_path=/home/git/gitaly -sudo -u git -H $gitlab_path/bin/daemon_with_pidfile $gitlab_path/tmp/pids/gitaly.pid \ - $gitaly_path/gitaly $gitaly_path/config.toml >> $gitlab_path/log/gitaly.log 2>&1 & +sudo -u git -H sh -c "$gitlab_path/bin/daemon_with_pidfile $gitlab_path/tmp/pids/gitaly.pid \ + $gitaly_path/gitaly $gitaly_path/config.toml >> $gitlab_path/log/gitaly.log 2>&1 &" ``` ### Initialize Database and Activate Advanced Features @@ -842,26 +831,27 @@ how to configure GitLab with a relative URL. To use GitLab with HTTPS: 1. In `gitlab.yml`: - 1. Set the `port` option in section 1 to `443`. - 1. Set the `https` option in section 1 to `true`. + 1. Set the `port` option in section 1 to `443`. + 1. Set the `https` option in section 1 to `true`. 1. In the `config.yml` of gitlab-shell: - 1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`). - 1. Set the certificates using either the `ca_file` or `ca_path` option. + 1. Set `gitlab_url` option to the HTTPS endpoint of GitLab (e.g. `https://git.example.com`). + 1. Set the certificates using either the `ca_file` or `ca_path` option. 1. Use the `gitlab-ssl` Nginx example config instead of the `gitlab` config. - 1. Update `YOUR_SERVER_FQDN`. - 1. Update `ssl_certificate` and `ssl_certificate_key`. - 1. Review the configuration file and consider applying other security and performance enhancing features. + 1. Update `YOUR_SERVER_FQDN`. + 1. Update `ssl_certificate` and `ssl_certificate_key`. + 1. Review the configuration file and consider applying other security and performance enhancing features. Using a self-signed certificate is discouraged but if you must use it, follow the normal directions. Then: 1. Generate a self-signed SSL certificate: - ```sh - mkdir -p /etc/nginx/ssl/ - cd /etc/nginx/ssl/ - sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key - sudo chmod o-r gitlab.key - ``` + ```sh + mkdir -p /etc/nginx/ssl/ + cd /etc/nginx/ssl/ + sudo openssl req -newkey rsa:2048 -x509 -nodes -days 3560 -out gitlab.crt -keyout gitlab.key + sudo chmod o-r gitlab.key + ``` + 1. In the `config.yml` of gitlab-shell set `self_signed_cert` to `true`. ### Enable Reply by email @@ -948,7 +938,7 @@ To use GitLab with Puma: cd /home/git/gitlab # Copy config file for the web server - sudo -u git -H config/puma.rb.example config/puma.rb + sudo -u git -H cp config/puma.rb.example config/puma.rb ``` 1. Edit the system `init.d` script to use `EXPERIMENTAL_PUMA=1` flag. If you have `/etc/default/gitlab`, then you should edit it instead. diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 43655767002..d067c341be8 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/ +redirect_to: 'https://docs.gitlab.com/charts/' --- This document was moved to [another location](https://docs.gitlab.com/charts/). diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md index 43655767002..d067c341be8 100644 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ b/doc/install/kubernetes/gitlab_omnibus.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/ +redirect_to: 'https://docs.gitlab.com/charts/' --- This document was moved to [another location](https://docs.gitlab.com/charts/). diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md index 08ccf2cf9ad..be58c957166 100644 --- a/doc/install/kubernetes/gitlab_runner_chart.md +++ b/doc/install/kubernetes/gitlab_runner_chart.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/runner/install/kubernetes.html +redirect_to: 'https://docs.gitlab.com/runner/install/kubernetes.html' --- This document was moved to [another location](https://docs.gitlab.com/runner/install/kubernetes.html). diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md index 43655767002..d067c341be8 100644 --- a/doc/install/kubernetes/index.md +++ b/doc/install/kubernetes/index.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/ +redirect_to: 'https://docs.gitlab.com/charts/' --- This document was moved to [another location](https://docs.gitlab.com/charts/). diff --git a/doc/install/kubernetes/preparation/connect.md b/doc/install/kubernetes/preparation/connect.md index db55e03d3d4..839461c982c 100644 --- a/doc/install/kubernetes/preparation/connect.md +++ b/doc/install/kubernetes/preparation/connect.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/installation/cloud/ +redirect_to: 'https://docs.gitlab.com/charts/installation/cloud/' --- This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/). diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md index 975d35c11c6..c3f53c2f580 100644 --- a/doc/install/kubernetes/preparation/eks.md +++ b/doc/install/kubernetes/preparation/eks.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/installation/cloud/eks.html +redirect_to: 'https://docs.gitlab.com/charts/installation/cloud/eks.html' --- This document was moved to [another location](https://docs.gitlab.com/charts/installation/cloud/eks.html). diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md index 2af16a752dc..7e88bbd3cd1 100644 --- a/doc/install/kubernetes/preparation/networking.md +++ b/doc/install/kubernetes/preparation/networking.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns +redirect_to: 'https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns' --- This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#networking-and-dns). diff --git a/doc/install/kubernetes/preparation/rbac.md b/doc/install/kubernetes/preparation/rbac.md index f94e7c24cdc..fc18b91641c 100644 --- a/doc/install/kubernetes/preparation/rbac.md +++ b/doc/install/kubernetes/preparation/rbac.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/installation/deployment.html#rbac +redirect_to: 'https://docs.gitlab.com/charts/installation/deployment.html#rbac' --- This document was moved to [another location](https://docs.gitlab.com/charts/installation/deployment.html#rbac). diff --git a/doc/install/kubernetes/preparation/tiller.md b/doc/install/kubernetes/preparation/tiller.md index 66d6c8faece..c1c7910703e 100644 --- a/doc/install/kubernetes/preparation/tiller.md +++ b/doc/install/kubernetes/preparation/tiller.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/installation/tools.html +redirect_to: 'https://docs.gitlab.com/charts/installation/tools.html' --- This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html). diff --git a/doc/install/kubernetes/preparation/tools_installation.md b/doc/install/kubernetes/preparation/tools_installation.md index 66d6c8faece..c1c7910703e 100644 --- a/doc/install/kubernetes/preparation/tools_installation.md +++ b/doc/install/kubernetes/preparation/tools_installation.md @@ -1,5 +1,5 @@ --- -redirect_to: https://docs.gitlab.com/charts/installation/tools.html +redirect_to: 'https://docs.gitlab.com/charts/installation/tools.html' --- This document was moved to [another location](https://docs.gitlab.com/charts/installation/tools.html). diff --git a/doc/install/openshift_and_gitlab/index.md b/doc/install/openshift_and_gitlab/index.md index 18981c43464..fbbe2a34952 100644 --- a/doc/install/openshift_and_gitlab/index.md +++ b/doc/install/openshift_and_gitlab/index.md @@ -13,8 +13,8 @@ for details. ## Introduction -[OpenShift Origin][openshift] is an open source container application -platform created by [RedHat], based on [kubernetes] and [Docker]. That means +[OpenShift Origin](https://www.okd.io/) (**Note:** renamed to OKD in Aug 2018) is an open source container application +platform created by [RedHat], based on [kubernetes](https://kubernetes.io/) and [Docker]. That means you can host your own PaaS for free and almost with no hassle. In this tutorial, we will see how to deploy GitLab in OpenShift using GitLab's @@ -27,8 +27,11 @@ For a video demonstration on installing GitLab on OpenShift, check the article [ ## Prerequisites -OpenShift 3 is not yet deployed on RedHat's offered Online platform ([openshift.com]), -so in order to test it, we will use an [all-in-one Virtualbox image][vm] that is +CAUTION: **Caution:** This information is no longer up to date, as the current versions +have changed and products have been renamed. + +OpenShift 3 is not yet deployed on RedHat's offered Online platform, [openshift.com](https://www.openshift.com/), +so in order to test it, we will use an [all-in-one Virtualbox image](https://www.okd.io/minishift/) that is offered by the OpenShift developers and managed by Vagrant. If you haven't done already, go ahead and install the following components as they are essential to test OpenShift easily: @@ -67,17 +70,17 @@ In short: 1. Open a terminal and in a new directory run: - ```sh - vagrant init openshift/origin-all-in-one - ``` + ```sh + vagrant init openshift/origin-all-in-one + ``` 1. This will generate a Vagrantfile based on the all-in-one VM image 1. In the same directory where you generated the Vagrantfile enter: - ```sh - vagrant up - ``` + ```sh + vagrant up + ``` This will download the VirtualBox image and fire up the VM with some preconfigured values as you can see in the Vagrantfile. As you may have noticed, you need @@ -145,12 +148,12 @@ Login successful. You have access to the following projects and can switch between them with 'oc project <projectname>': - * cockpit - * default (current) - * delete - * openshift - * openshift-infra - * sample +- cockpit +- default (current) +- delete +- openshift +- openshift-infra +- sample Using project "default". ``` @@ -192,22 +195,22 @@ In that case, the OpenShift service might not be running, so in order to fix it: 1. SSH into the VM by going to the directory where the Vagrantfile is and then run: - ```sh - vagrant ssh - ``` + ```sh + vagrant ssh + ``` 1. Run `systemctl` and verify by the output that the `openshift` service is not running (it will be in red color). If that's the case start the service with: - ```sh - sudo systemctl start openshift - ``` + ```sh + sudo systemctl start openshift + ``` 1. Verify the service is up with: - ```sh - systemctl status openshift -l - ``` + ```sh + systemctl status openshift -l + ``` Now you will be able to login using `oc` (like we did before) and visit the web console. @@ -390,55 +393,55 @@ Let's see how to do that using the following steps. 1. Make sure you are in the `gitlab` project: - ```sh - oc project gitlab - ``` + ```sh + oc project gitlab + ``` 1. See what services are used for this project: - ```sh - oc get svc - ``` + ```sh + oc get svc + ``` - The output will be similar to: + The output will be similar to: - ``` - NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE - gitlab-ce 172.30.243.177 <none> 22/TCP,80/TCP 5d - gitlab-ce-postgresql 172.30.116.75 <none> 5432/TCP 5d - gitlab-ce-redis 172.30.105.88 <none> 6379/TCP 5d - ``` + ``` + NAME CLUSTER-IP EXTERNAL-IP PORT(S) AGE + gitlab-ce 172.30.243.177 <none> 22/TCP,80/TCP 5d + gitlab-ce-postgresql 172.30.116.75 <none> 5432/TCP 5d + gitlab-ce-redis 172.30.105.88 <none> 6379/TCP 5d + ``` 1. We need to see the replication controllers of the `gitlab-ce` service. Get a detailed view of the current ones: - ```sh - oc describe rc gitlab-ce - ``` + ```sh + oc describe rc gitlab-ce + ``` - This will return a large detailed list of the current replication controllers. - Search for the name of the GitLab controller, usually `gitlab-ce-1` or if - that failed at some point and you spawned another one, it will be named - `gitlab-ce-2`. + This will return a large detailed list of the current replication controllers. + Search for the name of the GitLab controller, usually `gitlab-ce-1` or if + that failed at some point and you spawned another one, it will be named + `gitlab-ce-2`. 1. Scale GitLab using the previous information: - ```sh - oc scale --replicas=2 replicationcontrollers gitlab-ce-2 - ``` + ```sh + oc scale --replicas=2 replicationcontrollers gitlab-ce-2 + ``` 1. Get the new replicas number to make sure scaling worked: - ```sh - oc get rc gitlab-ce-2 - ``` + ```sh + oc get rc gitlab-ce-2 + ``` - which will return something like: + which will return something like: - ``` - NAME DESIRED CURRENT AGE - gitlab-ce-2 2 2 5d - ``` + ``` + NAME DESIRED CURRENT AGE + gitlab-ce-2 2 2 5d + ``` And that's it! We successfully scaled the replicas to 2 using the CLI. @@ -458,7 +461,7 @@ OpenShift's website about [autoscaling]. ## Current limitations -As stated in the [all-in-one VM][vm] page: +As stated in the [all-in-one VM](https://www.okd.io/minishift/) page: > By default, OpenShift will not allow a container to run as root or even a non-random container assigned userid. Most Docker images in the Dockerhub do not @@ -475,13 +478,13 @@ For OpenShift v3.0, you will need to do this manually: 1. Edit the Security Context: - ```sh - oc edit scc anyuid - ``` + ```sh + oc edit scc anyuid + ``` 1. Add `system:serviceaccount:<project>:gitlab-ce-user` to the `users` section. If you changed the Application Name from the default the user will - will be `<app-name>-user` instead of `gitlab-ce-user` + will be `<app-name>-user` instead of `gitlab-ce-user` 1. Save and exit the editor @@ -506,12 +509,8 @@ is capable of. As always, you can refer to the detailed PaaS and managing your applications with the ease of containers. [RedHat]: https://www.redhat.com/en "RedHat website" -[openshift]: https://www.openshift.org "OpenShift Origin website" -[vm]: https://www.openshift.org/vm/ "OpenShift All-in-one VM" [vm-new]: https://app.vagrantup.com/openshift/boxes/origin-all-in-one "Official OpenShift Vagrant box on Vagrant Cloud" [template]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/docker/openshift-template.json "OpenShift template for GitLab" -[openshift.com]: https://openshift.com "OpenShift Online" -[kubernetes]: http://kubernetes.io/ "Kubernetes website" [Docker]: https://www.docker.com "Docker website" [oc]: https://docs.openshift.org/latest/cli_reference/get_started_cli.html "Documentation - oc CLI documentation" [VirtualBox]: https://www.virtualbox.org/wiki/Downloads "VirtualBox downloads" diff --git a/doc/install/pivotal/index.md b/doc/install/pivotal/index.md index f068572f1e9..6a4b361c842 100644 --- a/doc/install/pivotal/index.md +++ b/doc/install/pivotal/index.md @@ -1,4 +1,4 @@ -# GitLab Pivotal Tile **[PREMIUM ONLY]** +# GitLab Pivotal Tile **(PREMIUM ONLY)** CAUTION: **Discontinued:** As of September 13, 2017, the GitLab Enterprise Plus for Pivotal Cloud Foundry diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index 96b7d0f3648..bc6364f57f7 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -58,59 +58,59 @@ assumptions are made: Make sure to follow all steps below: -1. (Optional) If you run short on resources, you can temporarily free up some - memory by shutting down the GitLab service with the following command: +1. (Optional) If you run short on resources, you can temporarily free up some + memory by shutting down the GitLab service with the following command: - ```shell - sudo service gitlab stop - ``` + ```shell + sudo service gitlab stop + ``` -1. Create `/home/git/gitlab/config/initializers/relative_url.rb` +1. Create `/home/git/gitlab/config/initializers/relative_url.rb` - ```shell - cp /home/git/gitlab/config/initializers/relative_url.rb.sample \ - /home/git/gitlab/config/initializers/relative_url.rb - ``` + ```shell + cp /home/git/gitlab/config/initializers/relative_url.rb.sample \ + /home/git/gitlab/config/initializers/relative_url.rb + ``` - and change the following line: + and change the following line: - ```ruby - config.relative_url_root = "/gitlab" - ``` + ```ruby + config.relative_url_root = "/gitlab" + ``` -1. Edit `/home/git/gitlab/config/gitlab.yml` and uncomment/change the - following line: +1. Edit `/home/git/gitlab/config/gitlab.yml` and uncomment/change the + following line: - ```yaml - relative_url_root: /gitlab - ``` + ```yaml + relative_url_root: /gitlab + ``` -1. Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the - following line: +1. Edit `/home/git/gitlab/config/unicorn.rb` and uncomment/change the + following line: - ```ruby - ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab" - ``` + ```ruby + ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab" + ``` -1. Edit `/home/git/gitlab-shell/config.yml` and append the relative path to - the following line: +1. Edit `/home/git/gitlab-shell/config.yml` and append the relative path to + the following line: - ```yaml - gitlab_url: http://127.0.0.1/gitlab - ``` + ```yaml + gitlab_url: http://127.0.0.1/gitlab + ``` -1. Make sure you have copied the supplied init script and the defaults file - as stated in the [installation guide](installation.md#install-init-script). - Then, edit `/etc/default/gitlab` and set in `gitlab_workhorse_options` the - `-authBackend` setting to read like: +1. Make sure you have copied the supplied init script and the defaults file + as stated in the [installation guide](installation.md#install-init-script). + Then, edit `/etc/default/gitlab` and set in `gitlab_workhorse_options` the + `-authBackend` setting to read like: - ```shell - -authBackend http://127.0.0.1:8080/gitlab - ``` + ```shell + -authBackend http://127.0.0.1:8080/gitlab + ``` - **Note:** - If you are using a custom init script, make sure to edit the above - gitlab-workhorse setting as needed. + **Note:** + If you are using a custom init script, make sure to edit the above + gitlab-workhorse setting as needed. 1. [Restart GitLab][] for the changes to take effect. @@ -118,12 +118,12 @@ Make sure to follow all steps below: To disable the relative URL: -1. Remove `/home/git/gitlab/config/initializers/relative_url.rb` +1. Remove `/home/git/gitlab/config/initializers/relative_url.rb` -1. Follow the same as above starting from 2. and set up the +1. Follow the same as above starting from 2. and set up the GitLab URL to one that doesn't contain a relative path. -[omnibus-rel]: http://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab" +[omnibus-rel]: https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-a-relative-url-for-gitlab "How to set up relative URL in Omnibus GitLab" [restart gitlab]: ../administration/restart_gitlab.md#installations-from-source "How to restart GitLab" <!-- ## Troubleshooting diff --git a/doc/install/requirements.md b/doc/install/requirements.md index ee3d17704a2..234e5acb394 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -9,7 +9,7 @@ as the hardware requirements that are needed to install and use GitLab. ## Operating Systems -### Supported Unix distributions +### Supported Linux distributions - Ubuntu - Debian @@ -21,7 +21,7 @@ as the hardware requirements that are needed to install and use GitLab. For the installations options, see [the main installation page](README.md). -### Unsupported Unix distributions +### Unsupported Linux distributions and Unix-like operating systems - Arch Linux - Fedora @@ -29,18 +29,18 @@ For the installations options, see [the main installation page](README.md). - Gentoo - macOS -On the above unsupported distributions is still possible to install GitLab yourself. -Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/installation/) for more information. +Installation of GitLab on these operating systems is possible, but not supported. +Please see the [installation from source guide](installation.md) and the [installation guides](https://about.gitlab.com/install/) for more information. -### Non-Unix operating systems such as Windows +### Microsoft Windows -GitLab is developed for Unix operating systems. -It does **not** run on 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-ce/issues/46567). +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-ce/issues/46567). Please consider using a virtual machine to run GitLab. ## Ruby versions -GitLab requires Ruby (MRI) 2.5. Support for Ruby versions below 2.5 (2.3, 2.4) will stop with GitLab 11.6. +GitLab requires Ruby (MRI) 2.6. Support for Ruby versions below 2.6 (2.4, 2.5) will stop with GitLab 12.2. You will have to use the standard MRI implementation of Ruby. We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab @@ -62,17 +62,19 @@ NOTE: **Note:** Since file system performance may affect GitLab's overall perfor ### 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. + - 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** number of cores and supports up to 500 users -- 4 cores supports up to 2,000 users -- 8 cores supports up to 5,000 users -- 16 cores supports up to 10,000 users -- 32 cores supports up to 20,000 users -- 64 cores supports up to 40,000 users -- More users? Run it on [multiple application servers](https://about.gitlab.com/high-availability/) +- **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 +- More users? Run it high-availability on [multiple application servers](https://about.gitlab.com/high-availability/) ### 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. + 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 @@ -80,13 +82,11 @@ less memory GitLab will give strange errors during the reconfigure run and 500 errors during usage. - 4GB RAM + 4GB swap supports up to 100 users but it will be very slow -- **8GB RAM** is the **recommended** memory size for all installations and supports up to 100 users -- 16GB RAM supports up to 2,000 users -- 32GB RAM supports up to 4,000 users -- 64GB RAM supports up to 8,000 users -- 128GB RAM supports up to 16,000 users -- 256GB RAM supports up to 32,000 users -- More users? Run it on [multiple application servers](https://about.gitlab.com/high-availability/) +- **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 +- More users? Run it high-availability on [multiple application servers](https://about.gitlab.com/high-availability/) 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 @@ -94,6 +94,8 @@ if your available memory changes. We also recommend [configuring the kernel's sw 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 of those. ## Database @@ -104,32 +106,10 @@ installation (e.g. the number of users, projects, etc). We currently support the following databases: -- PostgreSQL (highly recommended) -- MySQL/MariaDB (strongly discouraged, not all GitLab features are supported, no support for [MySQL/MariaDB GTID](https://mariadb.com/kb/en/mariadb/gtid/)) - -We highly recommend the use of PostgreSQL instead of MySQL/MariaDB as not all -features of GitLab work with MySQL/MariaDB: - -1. MySQL support for subgroups was [dropped with GitLab 9.3][post]. - See [issue #30472][30472] for more information. -1. Geo does [not support MySQL](../administration/geo/replication/database.md). This means no supported Disaster Recovery solution if using MySQL. **[PREMIUM ONLY]** -1. [Zero downtime migrations](../update/README.md#upgrading-without-downtime) do not work with MySQL. -1. [Database load balancing](../administration/database_load_balancing.md) is - supported only for PostgreSQL. **[PREMIUM ONLY]** -1. GitLab [optimizes the loading of dashboard events](https://gitlab.com/gitlab-org/gitlab-ce/issues/31806) using [PostgreSQL LATERAL JOINs](https://blog.heapanalytics.com/postgresqls-powerful-new-join-type-lateral/). -1. In general, SQL optimized for PostgreSQL may run much slower in MySQL due to - differences in query planners. For example, subqueries that work well in PostgreSQL - may not be [performant in MySQL](https://dev.mysql.com/doc/refman/5.7/en/optimizing-subqueries.html). -1. Binary column index length is limited to 20 bytes. This is accomplished with [a hack](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/mysql_set_length_for_binary_indexes.rb). -1. MySQL requires a variety of hacks to increase limits on various columns, [for example](https://gitlab.com/gitlab-org/gitlab-ce/issues/49583). -1. [The milestone filter runs slower queries on MySQL](https://gitlab.com/gitlab-org/gitlab-ce/issues/51173#note_99391731). -1. We expect this list to grow over time. - -Existing users using GitLab with MySQL/MariaDB are advised to -[migrate to PostgreSQL](../update/mysql_to_postgresql.md) instead. - -[30472]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472 -[post]: https://about.gitlab.com/2017/06/22/gitlab-9-3-released/#dropping-support-for-subgroups-in-mysql +- PostgreSQL + +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 @@ -168,8 +148,8 @@ CREATE EXTENSION postgres_fdw; ## Unicorn Workers -For most instances we recommend using: CPU cores + 1 = unicorn workers. -So for a machine with 2 cores, 3 unicorn workers is ideal. +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. |