diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-04-20 23:50:22 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-04-20 23:50:22 +0000 |
| commit | 9dc93a4519d9d5d7be48ff274127136236a3adb3 (patch) | |
| tree | 70467ae3692a0e35e5ea56bcb803eb512a10bedb /doc/install | |
| parent | 4b0f34b6d759d6299322b3a54453e930c6121ff0 (diff) | |
| download | gitlab-ce-9dc93a4519d9d5d7be48ff274127136236a3adb3.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-11-stable-eev13.11.0-rc43
Diffstat (limited to 'doc/install')
34 files changed, 277 insertions, 377 deletions
diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index b18a537bf8b..7fde3915bf5 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -348,10 +348,6 @@ Now that the database is created, let's move on to setting up Redis with ElastiC ElastiCache is an in-memory hosted caching solution. Redis maintains its own persistence and is used to store session data, temporary cache information, and background job queues for the GitLab application. -WARNING: -GitLab recommends you use ElastiCache Redis version 5.0.x, because version 6.x contains -a bug that [prevents Sidekiq from processing jobs](https://gitlab.com/gitlab-org/gitlab/-/issues/281683). - ### Create a Redis Security Group 1. Navigate to the EC2 dashboard. @@ -413,7 +409,7 @@ If you do not want to maintain bastion hosts, you can set up [AWS Systems Manage 1. Leave everything else as default and click **Add Storage**. 1. For storage, we'll leave everything as default and only add an 8GB root volume. We won't store anything on this instance. 1. Click **Add Tags** and on the next screen click **Add Tag**. - 1. We’ll only set `Key: Name` and `Value: Bastion Host A`. + 1. We'll only set `Key: Name` and `Value: Bastion Host A`. 1. Click **Configure Security Group**. 1. Select **Create a new security group**, enter a **Security group name** (we'll use `bastion-sec-group`), and add a description. 1. We'll enable SSH access from anywhere (`0.0.0.0/0`). If you want stricter security, specify a single IP address or an IP address range in CIDR notation. @@ -432,7 +428,7 @@ Confirm that you can SSH into the instance: 1. Create an EC2 instance following the same steps as above with the following changes: 1. For the **Subnet**, select the second public subnet we created earlier (`gitlab-public-10.0.2.0`). - 1. Under the **Add Tags** section, we’ll set `Key: Name` and `Value: Bastion Host B` so that we can easily identify our two instances. + 1. Under the **Add Tags** section, we'll set `Key: Name` and `Value: Bastion Host B` so that we can easily identify our two instances. 1. For the security group, select the existing `bastion-sec-group` we created above. ### Use SSH Agent Forwarding @@ -456,10 +452,10 @@ From the EC2 dashboard: 1. In the **Subnet** dropdown, select `gitlab-private-10.0.1.0` from the list of subnets we created earlier. 1. Double check that **Auto-assign Public IP** is set to `Use subnet setting (Disable)`. 1. Click **Add Storage**. - 1. The root volume is 8GiB by default and should be enough given that we won’t store any data there. + 1. The root volume is 8GiB by default and should be enough given that we won't store any data there. 1. Click **Add Tags** and add any tags you may need. In our case, we'll only set `Key: Name` and `Value: GitLab`. 1. Click **Configure Security Group**. Check **Select an existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. -1. Click **Review and launch** followed by **Launch** if you’re happy with your settings. +1. Click **Review and launch** followed by **Launch** if you're happy with your settings. 1. Finally, acknowledge that you have access to the selected private key file or create a new one. Click **Launch Instances**. ### Add custom configuration @@ -654,8 +650,9 @@ That concludes the configuration changes for our GitLab instance. Next, we'll cr ### Log in for the first time -Using the domain name you used when setting up [DNS for the load balancer](#configure-dns-for-load-balancer), you should now be able to visit GitLab in your browser. You will be asked to set up a password -for the `root` user which has admin privileges on the GitLab instance. This password will be stored in the database. +Using the domain name you used when setting up [DNS for the load balancer](#configure-dns-for-load-balancer), you should now be able to visit GitLab in your browser. +If you didn't change the password by any other means, the default password will be the same as the instance ID. To change the default password, login as the `root` user +with the default password and [change it in the user profile](../../user/profile#change-your-password). When our [auto scaling group](#create-an-auto-scaling-group) spins up new instances, we'll be able to log in with username `root` and the newly created password. @@ -683,7 +680,7 @@ From the EC2 dashboard: 1. **Do not** check **Request Spot Instance**. 1. From the **IAM Role** dropdown, pick the `GitLabAdmin` instance role we [created earlier](#create-an-iam-ec2-instance-role-and-profile). 1. Leave the rest as defaults and click **Add Storage**. -1. The root volume is 8GiB by default and should be enough given that we won’t store any data there. Click **Configure Security Group**. +1. The root volume is 8GiB by default and should be enough given that we won't store any data there. Click **Configure Security Group**. 1. Check **Select and existing security group** and select the `gitlab-loadbalancer-sec-group` we created earlier. 1. Click **Review**, review your changes, and click **Create launch configuration**. 1. Acknowledge that you have access to the private key or create a new one. Click **Create launch configuration**. diff --git a/doc/install/azure/img/azure-add-inbound-sec-rule-http.png b/doc/install/azure/img/azure-add-inbound-sec-rule-http.png Binary files differdeleted file mode 100644 index abf500cb63a..00000000000 --- a/doc/install/azure/img/azure-add-inbound-sec-rule-http.png +++ /dev/null diff --git a/doc/install/azure/img/azure-add-inbound-sec-rule-ssh.png b/doc/install/azure/img/azure-add-inbound-sec-rule-ssh.png Binary files differdeleted file mode 100644 index f7a8a04dfa7..00000000000 --- a/doc/install/azure/img/azure-add-inbound-sec-rule-ssh.png +++ /dev/null diff --git a/doc/install/azure/img/azure-create-virtual-machine-basics-password.png b/doc/install/azure/img/azure-create-virtual-machine-basics-password.png Binary files differdeleted file mode 100644 index 80bf39ecb48..00000000000 --- a/doc/install/azure/img/azure-create-virtual-machine-basics-password.png +++ /dev/null diff --git a/doc/install/azure/img/azure-create-virtual-machine-basics.png b/doc/install/azure/img/azure-create-virtual-machine-basics.png Binary files differdeleted file mode 100644 index 229c073fe17..00000000000 --- a/doc/install/azure/img/azure-create-virtual-machine-basics.png +++ /dev/null diff --git a/doc/install/azure/img/azure-create-virtual-machine-deployment.png b/doc/install/azure/img/azure-create-virtual-machine-deployment.png Binary files differdeleted file mode 100644 index 5cfdd973a58..00000000000 --- a/doc/install/azure/img/azure-create-virtual-machine-deployment.png +++ /dev/null diff --git a/doc/install/azure/img/azure-create-virtual-machine-purchase.png b/doc/install/azure/img/azure-create-virtual-machine-purchase.png Binary files differdeleted file mode 100644 index f4de62299f1..00000000000 --- a/doc/install/azure/img/azure-create-virtual-machine-purchase.png +++ /dev/null diff --git a/doc/install/azure/img/azure-create-virtual-machine-settings.png b/doc/install/azure/img/azure-create-virtual-machine-settings.png Binary files differdeleted file mode 100644 index 20097921660..00000000000 --- a/doc/install/azure/img/azure-create-virtual-machine-settings.png +++ /dev/null diff --git a/doc/install/azure/img/azure-create-virtual-machine-size.png b/doc/install/azure/img/azure-create-virtual-machine-size.png Binary files differdeleted file mode 100644 index a408394151f..00000000000 --- a/doc/install/azure/img/azure-create-virtual-machine-size.png +++ /dev/null diff --git a/doc/install/azure/img/azure-dashboard-highlight-nsg.png b/doc/install/azure/img/azure-dashboard-highlight-nsg.png Binary files differdeleted file mode 100644 index 025efd33977..00000000000 --- a/doc/install/azure/img/azure-dashboard-highlight-nsg.png +++ /dev/null diff --git a/doc/install/azure/img/azure-dashboard-running-resources.png b/doc/install/azure/img/azure-dashboard-running-resources.png Binary files differdeleted file mode 100644 index 7e661a6aa65..00000000000 --- a/doc/install/azure/img/azure-dashboard-running-resources.png +++ /dev/null diff --git a/doc/install/azure/img/azure-dashboard.png b/doc/install/azure/img/azure-dashboard.png Binary files differdeleted file mode 100644 index 375ec8622b8..00000000000 --- a/doc/install/azure/img/azure-dashboard.png +++ /dev/null diff --git a/doc/install/azure/img/azure-inbound-sec-rules-list.png b/doc/install/azure/img/azure-inbound-sec-rules-list.png Binary files differdeleted file mode 100644 index 1667671b21d..00000000000 --- a/doc/install/azure/img/azure-inbound-sec-rules-list.png +++ /dev/null diff --git a/doc/install/azure/img/azure-new-gitlab-ce.png b/doc/install/azure/img/azure-new-gitlab-ce.png Binary files differdeleted file mode 100644 index 88949f69a94..00000000000 --- a/doc/install/azure/img/azure-new-gitlab-ce.png +++ /dev/null diff --git a/doc/install/azure/img/azure-new-search-gitlab.png b/doc/install/azure/img/azure-new-search-gitlab.png Binary files differdeleted file mode 100644 index f96ed577d62..00000000000 --- a/doc/install/azure/img/azure-new-search-gitlab.png +++ /dev/null diff --git a/doc/install/azure/img/azure-nsg-inbound-sec-rules-add-highlight.png b/doc/install/azure/img/azure-nsg-inbound-sec-rules-add-highlight.png Binary files differdeleted file mode 100644 index c9a08b87ce6..00000000000 --- a/doc/install/azure/img/azure-nsg-inbound-sec-rules-add-highlight.png +++ /dev/null diff --git a/doc/install/azure/img/azure-nsg-inbound-sec-rules-highlight.png b/doc/install/azure/img/azure-nsg-inbound-sec-rules-highlight.png Binary files differdeleted file mode 100644 index 6423625ca8b..00000000000 --- a/doc/install/azure/img/azure-nsg-inbound-sec-rules-highlight.png +++ /dev/null diff --git a/doc/install/azure/img/azure-vm-domain-name.png b/doc/install/azure/img/azure-vm-domain-name.png Binary files differdeleted file mode 100644 index 01c03004b24..00000000000 --- a/doc/install/azure/img/azure-vm-domain-name.png +++ /dev/null diff --git a/doc/install/azure/img/azure-vm-management-public-ip.png b/doc/install/azure/img/azure-vm-management-public-ip.png Binary files differdeleted file mode 100644 index ef313641db8..00000000000 --- a/doc/install/azure/img/azure-vm-management-public-ip.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-admin-area-9.4.0.png b/doc/install/azure/img/gitlab-admin-area-9.4.0.png Binary files differdeleted file mode 100644 index b7ee4598731..00000000000 --- a/doc/install/azure/img/gitlab-admin-area-9.4.0.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-admin-area.png b/doc/install/azure/img/gitlab-admin-area.png Binary files differdeleted file mode 100644 index 028f0b0a0eb..00000000000 --- a/doc/install/azure/img/gitlab-admin-area.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-change-password.png b/doc/install/azure/img/gitlab-change-password.png Binary files differdeleted file mode 100644 index 7350d604d56..00000000000 --- a/doc/install/azure/img/gitlab-change-password.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-home.png b/doc/install/azure/img/gitlab-home.png Binary files differdeleted file mode 100644 index 7c935805ea2..00000000000 --- a/doc/install/azure/img/gitlab-home.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-login.png b/doc/install/azure/img/gitlab-login.png Binary files differdeleted file mode 100644 index 95fe5aec1e0..00000000000 --- a/doc/install/azure/img/gitlab-login.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-new-project.png b/doc/install/azure/img/gitlab-new-project.png Binary files differdeleted file mode 100644 index 3b6b9a81682..00000000000 --- a/doc/install/azure/img/gitlab-new-project.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-project-home-empty.png b/doc/install/azure/img/gitlab-project-home-empty.png Binary files differdeleted file mode 100644 index 54d0b36a251..00000000000 --- a/doc/install/azure/img/gitlab-project-home-empty.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-project-home-instructions.png b/doc/install/azure/img/gitlab-project-home-instructions.png Binary files differdeleted file mode 100644 index fd040d33e95..00000000000 --- a/doc/install/azure/img/gitlab-project-home-instructions.png +++ /dev/null diff --git a/doc/install/azure/img/gitlab-ssh-update-in-progress.png b/doc/install/azure/img/gitlab-ssh-update-in-progress.png Binary files differdeleted file mode 100644 index 8a686ebde26..00000000000 --- a/doc/install/azure/img/gitlab-ssh-update-in-progress.png +++ /dev/null diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 0c0a4457413..8fb400c796e 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -8,443 +8,316 @@ type: howto # Install GitLab on Microsoft Azure **(FREE SELF)** -WARNING: -This guide is deprecated and pending an update. For the time being, use the GitLab -[image in the Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/gitlabinc1586447921813.gitlabee?tab=Overview). - -Azure is Microsoft's business cloud and GitLab is a pre-configured offering on -the Azure Marketplace. Hopefully, you aren't surprised to hear that Microsoft -and Azure have embraced open source software like Ubuntu, Red Hat Enterprise Linux, -and of course - GitLab! This means that you can spin up a pre-configured -GitLab VM and have your very own private GitLab up and running in around 30 -minutes. Let's get started. - -## Getting started - -First, you'll need an account on Azure. There are three ways to do this: - -- If your company (or you) already has an account, then you are ready to go! -- You can also open your own Azure account for free. _At time of writing_, you get $200 - of credit to spend on Azure services for 30 days. You can use this credit to try out paid Azure - services, exploring Microsoft's cloud for free. Even after the first 30 days, you never have to pay - anything unless you decide to transition to paid services with a Pay-As-You-Go Azure subscription. - This is a great way to try out Azure and cloud computing, and you can - [read more in their comprehensive FAQ](https://azure.microsoft.com/en-us/free/free-account-faq/). -- If you have an MSDN subscription, you can activate your Azure subscriber benefits. Your MSDN - subscription gives you recurring Azure credits every month, so why not put those credits to use and - try out GitLab right now? - -## Working with Azure - -Once you have an Azure account, you can get started. [Log in to Azure](https://portal.azure.com) -and the first thing you will see is the Dashboard: - - - -The Dashboard gives you a quick overview of Azure resources, and from here you can build VMs, -create SQL Databases, author websites, and perform lots of other cloud tasks. - -## Create New VM - -The [Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/) is an online store for pre-configured applications and -services which have been optimized for the cloud by software vendors like GitLab, -available on the Azure Marketplace as pre-configured solutions. In this tutorial -we will install GitLab Community Edition. - -To begin creating a new GitLab VM, click on the **+ New** icon, type "GitLab" into the search -box, and then click the **"GitLab Community Edition"** search result: - - - -A new "blade" window will pop-out, where you can read more about the **"GitLab Community Edition"** -offering which is freely available under the MIT Expat License: - - - -Click **"Create"** and you will be presented with the "Create virtual machine" blade: - - - -## Basics - -The first items we need to configure are the basic settings of the underlying virtual machine: - -1. Enter a `Name` for the VM - e.g. **"GitLab-CE"** -1. Select a `VM disk type` - either **HDD** _(slower, lower cost)_ or **SSD** _(faster, higher cost)_ -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** +For users of the Microsoft Azure business cloud, GitLab has a pre-configured offering in +the [Azure Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/). +This tutorial describes installing GitLab +Enterprise Edition in a single Virtual Machine (VM). - 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](https://en.wikipedia.org/wiki/Secure_Shell) into the VM, so make sure it's a strong password/passphrase)_ +## Prerequisite -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"** +You'll need an account on Azure. Use of the following methods to obtain an account: - 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 - -Here are the settings we've used: - - - -Check the settings you have entered, and then click **"OK"** when you're ready to proceed. - -## Size +- If you or your company already have an account with a subscription, use that account. + If not, you can [open your own Azure account for free](https://azure.microsoft.com/en-us/free/). + Azure's free trial gives you $200 credit to explore Azure for 30 days. + [Read more in Azure's comprehensive FAQ](https://azure.microsoft.com/en-us/free/free-account-faq/). +- If you have an MSDN subscription, you can activate your Azure subscriber benefits. Your MSDN + subscription gives you recurring Azure credits every month, so you can use + those credits and try out GitLab. -Next, you need to choose the size of your VM - selecting features such as the number of CPU cores, -the amount of RAM, the size of storage (and its speed), etc. +## Deploy and configure GitLab -NOTE: -In common with other cloud vendors, Azure operates a resource/usage pricing model, i.e. -the more resources your VM consumes the more it will cost you to run, so make your selection -carefully. You'll see that Azure provides an _estimated_ monthly cost beneath each VM Size to help -guide your selection. +Because GitLab is already installed in a pre-configured image, all you have to do is +create a new VM: -The default size - the lowest cost **"DS1_V2 Standard"** VM - meets the minimum system requirements -to run a small GitLab environment for testing and evaluation purposes, and so we're going to go -ahead and select this one, but please choose the size which best meets your own requirements: +1. [Visit the GitLab offering in the marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/gitlabinc1586447921813.gitlabee?tab=Overview) +1. Select **Get it now** and you will be presented with the **Create this app in Azure** window. + Select **Continue**. +1. Select one of the following options from the Azure portal: + - Select **Create** to create a VM from scratch. + - Select **Start with a pre-set configuration** to get started with some + pre-configured options. You can modify these configurations at any time. - +For the sake of this guide, we'll create the VM from scratch, so +select **Create**. NOTE: -Be aware that while your VM is active (known as "allocated"), it will incur -"compute charges" which, ultimately, you will be billed for. So, even if you're using the -free trial credits, you'll likely want to learn +Be aware that while your VM is active (known as "allocated"), it incurs +compute charges for which you'll be billed. Even if you're using the +free trial credits, you'll want to know [how to properly shutdown an Azure VM to save money](https://build5nines.com/properly-shutdown-azure-vm-to-save-money/). +See the [Azure pricing calculator](https://azure.microsoft.com/en-us/pricing/calculator/) +to learn how much resources can cost. -Go ahead and click your chosen size, then click **"Select"** when you're ready to proceed to the -next step. +After you create the virtual machine, use the information in the following +sections to configure it. -## Settings +### Configure the Basics tab -On the next blade, you're asked to configure the Storage, Network and Extension settings. -We've gone with the default settings as they're sufficient for test-driving GitLab, but please -choose the settings which best meet your own requirements: +The first items you need to configure are the basic settings of the underlying virtual machine: - +1. Select the subscription model and a resource group (create a new one if it + doesn't exist). +1. Enter a name for the VM, for example `GitLab`. +1. Select a region. +1. In **Availability options**, select **Availability zone** and set it to `1`. + Read more about the [availability zones](https://docs.microsoft.com/en-us/azure/virtual-machines/availability). +1. Ensure the selected image is set to **GitLab - Gen1**. +1. Select the VM size based on the [hardware requirements](../requirements.md#hardware-requirements). + Because the minimum system requirements to run a GitLab environment for up to 500 users + is covered by the `D4s_v3` size, select that option. +1. Set the authentication type to **SSH public key**. +1. Enter a user name or leave the one that is automatically created. This is + the user you'll use to connect to the VM through SSH. By default, the user + has root access. +1. Determine if you want to provide your own SSH key or let Azure create one for you. + Read the [SSH documentation](../../ssh/README.md) to learn more about how to set up SSH + public keys. -Review the settings and then click **"OK"** when you're ready to proceed to the last step. +Review your entered settings, and then proceed to the Disks tab. -## Purchase +### Configure the Disks tab -The Purchase page is the last step and here you will be presented with the price per hour for your -new VM. You'll be billed only for the VM itself (e.g. "Standard DS1 v2") because the -**"GitLab Community Edition"** marketplace solution is free to use at 0 USD/hr: +For the disks: - +1. For the OS disk type, select **Premium SSD**. +1. Select the default encryption. -NOTE: -At this stage, you can review and modify the any of the settings you have made during all -previous steps, just click on any of the four steps to re-open them. +[Read more about the types of disks](https://docs.microsoft.com/en-us/azure/virtual-machines/managed-disks-overview) that Azure provides. -When you have read and agreed to the terms of use and are ready to proceed, click **"Purchase"**. +Review your settings, and then proceed to the Networking tab. -## Deployment +### Configure the Networking tab -At this point, Azure will begin deploying your new VM. The deployment process will take a few -minutes to complete, with progress displayed on the **"Deployment"** blade: +Use this tab to define the network connectivity for your +virtual machine, by configuring network interface card (NIC) settings. +You can leave them at their default settings. - +Azure creates a security group by default and the VM is assigned to it. +The GitLab image in the marketplace has the following ports open by default: -Once the deployment process is complete, the new VM and its associated resources will be displayed -on the Azure Dashboard (you may need to refresh the page): +| Port | Description | +|------|-------------| +| 80 | Enable the VM to respond to HTTP requests, allowing public access. | +| 443 | Enable our VM to respond to HTTPS requests, allowing public access. | +| 22 | Enable our VM to respond to SSH connection requests, allowing public access (with authentication) to remote terminal sessions. | - +If you want to change the ports or add any rules, you can do it +after the VM is created by going to the Networking settings in the left sidebar, +while in the VM dashboard. -The new VM can also be accessed by clicking the `All resources` or `Virtual machines` icons in the -Azure Portal sidebar navigation menu. +### Configure the Management tab -## Set up a domain name +Use this tab to configure monitoring and management options +for your VM. You don't need to change the default settings. -The VM will have a public IP address (static by default), but Azure allows us to assign a friendly -DNS name to the VM, so let's go ahead and do that. +### Configure the Advanced tab -From the Dashboard, click on the **"GitLab-CE"** tile to open the management blade for the new VM. -The public IP address that the VM uses is shown in the 'Essentials' section: +Use this tab to add additional configuration, agents, scripts +or applications through virtual machine extensions or `cloud-init`. You don't +need to change the default settings. - +### Configure the Tags tab -Click on the public IP address - which should open the **"Public IP address - Configuration"** blade, -then click on **"Configuration"** (under "Settings"). Now enter a friendly DNS name for your instance -in the `DNS name label` field: +Use this tab to add name/value pairs that enable you to categorize +resources. You don't need to change the default settings. - +### Review and create the VM -In the screenshot above, you'll see that we've set the `DNS name label` to `gitlab-ce-test`. -This will make our VM accessible at `gitlab-ce-test.centralus.cloudapp.azure.com` -_(the full domain name of your own VM will be different, of course)_. +The final tab presents you with all of your selected options, +where you can review and modify your choices from the +previous steps. Azure will run validation tests in the background, +and if you provided all of the required settings, you can +create the VM. -Click **"Save"** for the changes to take effect. +After you select **Create**, if you had opted for Azure to create an SSH key pair +for you, you'll be asked to download the private SSH key. Download the key, as you'll +need it to SSH into the VM. -NOTE: -If you want to use your own domain name, you will need to add a DNS `A` record at your -domain registrar which points to the public IP address of your Azure VM. If you do this, you'll need -to make sure your VM is configured to use a _static_ public IP address (i.e. not a _dynamic_ one) -or you will have to reconfigure the DNS `A` record each time Azure reassigns your VM a new public IP -address. Read [Public IP addresses](https://docs.microsoft.com/en-us/azure/virtual-network/public-ip-addresses) to learn more. - -## Let's open some ports - -At this stage you should have a running and fully operational VM. However, none of the services on -your VM (e.g. GitLab) will be publicly accessible via the internet until you have opened up the -necessary ports to enable access to those services. - -Ports are opened by adding _security rules_ to the **"Network security group"** (NSG) which our VM -has been assigned to. If you followed the process above, then Azure will have automatically created -an NSG named `GitLab-CE-nsg` and assigned the `GitLab-CE` VM to it. +After you download the key, the deployment begins. -NOTE: -If you gave your VM a different name then the NSG automatically created by Azure will -also have a different name - the name you have your VM, with `-nsg` appended to it. +### Finish deployment -You can navigate to the NSG settings via many different routes in the Azure Portal, but one of the -simplest ways is to go to the Azure Dashboard, and then click on the Network Security Group listed -in the **"All resources"** tile: +At this point, Azure begins to deploy your new VM. The deployment process +takes a few minutes to complete. After it's complete, the new VM and its +associated resources are displayed on the Azure Dashboard. +Select **Go to resource** to visit the dashboard of the VM. - +GitLab is now deployed and ready to be used. Before doing so, however, +you need to set up the domain name and configure GitLab to use it. -With the **"Network security group"** blade open, click on **"Inbound security rules"** under -**"Settings"**: +### Set up a domain name - +The VM has a public IP address (static by default), but Azure allows you +to assign a descriptive DNS name to the VM: -Next, click **"Add"**: +1. From the VM dashboard, select **Configure** under **DNS name**. +1. Enter a descriptive DNS name for your instance in the **DNS name label** field, + for example `gitlab-prod`. This will make the VM accessible at + `gitlab-prod.eastus.cloudapp.azure.com`. +1. Select **Save** for the changes to take effect. - +Eventually, you'll want to use your own domain name. To do this, you need to add a DNS `A` record +with your domain registrar that points to the public IP address of your Azure VM. +You can use [Azure's DNS](https://docs.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns) +or some [other registrar](https://docs.gitlab.com/omnibus/settings/dns.html). -### Which ports to open? +### Change the GitLab external URL -Like all servers, our VM will be running many services. However, we want to open up the correct -ports to enable public internet access to two services in particular: +GitLab uses `external_url` in its configuration file to set up the domain name. +If you don't set this up, when you visit the Azure friendly name, you'll +instead be redirected to the public IP. -1. **HTTP** (port 80) - opening port 80 will enable our VM to respond to HTTP requests, allowing - public access to the instance of GitLab running on our VM. -1. **SSH** (port 22) - opening port 22 will enable our VM to respond to SSH connection requests, - allowing public access (with authentication) to remote terminal sessions - _(you'll see why we need [SSH](https://en.wikipedia.org/wiki/Secure_Shell) access to our VM [later on in this tutorial](#maintaining-your-gitlab-instance))_ +To set up the GitLab external URL: -### Open HTTP on Port 80 +1. Connect to GitLab through SSH by going to **Settings > Connect** from the VM + dashboard, and follow the instructions. Remember to sign in with the username + and SSH key you specified when you [created the VM](#configure-the-basics-tab). + The Azure VM domain name will be the one you + [set up previously](#set-up-a-domain-name). If you didn't set up a domain name for + your VM, you can use the IP address in its place. -In the **"Add inbound security rule"** blade, let's open port 80 so that our VM will accept HTTP -connections: + In the case of our example: - + ```shell + ssh -i <private key path> gitlab-azure@gitlab-prod.eastus.cloudapp.azure.com + ``` -1. Enter **"HTTP"** in the `Name` field -1. Select **HTTP** from the options in the `Service` dropdown list -1. Make sure the `Action` is set to **Allow** -1. Click **"OK"** + NOTE: + If you need to reset your credentials, read + [how to reset SSH credentials for a user on an Azure VM](https://docs.microsoft.com/en-us/troubleshoot/azure/virtual-machines/troubleshoot-ssh-connection#reset-ssh-credentials-for-a-user). -### Open SSH on Port 22 +1. Open `/etc/gitlab/gitlab.rb` with your editor. +1. Find `external_url` and replace it with your own domain name. For the sake + of this example, we'll use the friendly domain name that Azure set up. + If you use `https` in the URL, Let's Encrypt will be + [automatically enabled](https://docs.gitlab.com/omnibus/settings/ssl.html#lets-encrypt-integration), + and you'll have HTTPS by default: -Repeat the above process, adding a second Inbound security rule to open port 22, enabling our VM to -accept [SSH](https://en.wikipedia.org/wiki/Secure_Shell) connections: + ```ruby + external_url 'https://gitlab-prod.eastus.cloudapp.azure.com' + ``` - +1. Find the following settings and comment them out, so that GitLab doesn't + pick up the wrong certificates: -1. Enter **"SSH"** in the `Name` field -1. Select **SSH** from the options in the `Service` dropdown list -1. Make sure the `Action` is set to **Allow** -1. Click **"OK"** + ```ruby + # nginx['redirect_http_to_https'] = true + # nginx['ssl_certificate'] = "/etc/gitlab/ssl/server.crt" + # nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/server.key" + ``` -It will take a moment for Azure to add each new Inbound Security Rule (and you may need to click on -**"Inbound security rules"** to refresh the list), but once completed, you should see the two new -rules in the list: +1. Reconfigure GitLab for the changes to take effect. Run the + following command every time you make changes to `/etc/gitlab/gitlab.rb`: - + ```shell + sudo gitlab-ctl reconfigure + ``` -## Connecting to GitLab +You can now visit GitLab with your browser at the new external URL. -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 -created by GitLab: +### Visit GitLab for the first time - +Use the domain name you set up earlier to visit your new GitLab instance +in your browser. In this example, it's `https://gitlab-prod.eastus.cloudapp.azure.com`. -Enter your _new_ password into both form fields, and then click **"Change your password"**. +The first thing you'll see is the sign-in page. GitLab creates an admin user by default. +The credentials are: -Once you have changed the password you will be redirected to the GitLab login page. Use `root` as -the username, enter the new password you set in the previous step, and then click **"Sign in"**: +- Username: `root` +- Password: the password is automatically created, and there are [two ways to + find it](https://docs.bitnami.com/azure/faq/get-started/find-credentials). - +After signing in, be sure to immediately [change the password](../../user/profile/index.md#change-your-password). -### Success? +## Maintain your GitLab instance -After signing in successfully, you should see the GitLab Projects page displaying a -**"Welcome to GitLab!"** message: +It's important to keep your GitLab environment up-to-date. The GitLab team is constantly making +enhancements and occasionally you may need to update for security reasons. Use the information +in this section whenever you need to update GitLab. - +### Check the current version -If so, you now have a working GitLab instance on your own private Azure VM. **Congratulations!** +To determine the version of GitLab you're currently running, +go to the **{admin}** **Admin Area**, and you will find the version +under the **Components** table. -## Creating your first GitLab project +If there's a newer available version of GitLab that contains one or more +security fixes, GitLab displays an **Update asap** notification message that +encourages you to [update](#update-gitlab). -You can skip this section if you are familiar with Git and GitLab. Otherwise, let's create our first -project. From the Welcome page, click **"New Project"**. +### Update GitLab -Let's give our project a name and a description, and then accept the default values for everything -else: +To update GitLab to the latest version: -1. Enter **"demo"** into the `Project path` project name field -1. Enter a `description`, e.g. **"My awesome demo project!"** -1. Click **"Create project"** +1. Connect to the VM through SSH. +1. Update GitLab: - + ```shell + sudo apt update + sudo apt install gitlab-ee + ``` -Once the new project has been created (which should only take a moment), you'll be redirected to -homepage for the project: + This command updates GitLab and its associated components to the latest versions, + and can take time to complete. You'll see various update tasks being + completed in your terminal. - + NOTE: + If you get an error like + `E: The repository 'https://packages.gitlab.com/gitlab/gitlab-ee/debian buster InRelease' is not signed.`, + see the [troubleshooting section](#update-the-gpg-key-for-the-gitlab-repositories). -If you scroll further down the project's home page, you'll see some basic instructions on how to -set up a local clone of your new repository and push and pull from it: +1. After the update process is complete, you'll see a message like the + following: - + ```plaintext + Upgrade complete! If your GitLab server is misbehaving try running -**That's it! You now have your own private GitLab environment installed and running in the cloud!** + sudo gitlab-ctl restart -## Maintaining your GitLab instance + before anything else. + ``` -It's important to keep your GitLab environment up-to-date. The GitLab team is constantly making -enhancements and occasionally you may need to update for security reasons. So let's review how to -update GitLab. +Refresh your GitLab instance in the browser and go to the Admin Area. You should now have an +up-to-date GitLab instance. -### Checking our current version +## Next steps and further configuration -To check which version of GitLab we're currently running, click on the "Admin Area" link - it's the -the wrench icon displayed in the top-right, next to the search box. +Now that you have a functional GitLab instance, follow the +[next steps](../index.md#next-steps) to learn what more you can do with your +new installation. -In the following screenshot you can see an **"update asap"** notification message in the top-right. -This particular message indicates that there is a newer version of GitLab available which contains -one or more security fixes: +## Troubleshooting - +This section describes common errors you can encounter. -Under the **"Components"** section, we can see that our VM is currently running version `8.6.5` of -GitLab. This is the version of GitLab which was contained in the Azure Marketplace -**"GitLab Community Edition"** offering we used to build the VM when we wrote this tutorial. +### Update the GPG key for the GitLab repositories NOTE: -The version of GitLab in your own VM instance may well be different, but the update -process will still be the same. - -### Connect via SSH - -To perform an update, we need to connect directly to our Azure VM instance and run some commands -from the terminal. Our Azure VM is actually a server running Linux (Ubuntu), so we'll need to -connect to it using SSH ([Secure Shell](https://en.wikipedia.org/wiki/Secure_Shell)). - -If you're running Windows, you'll need to connect using [PuTTY](https://www.putty.org) or an equivalent Windows SSH client. -If you're running Linux or macOS, then you already have an SSH client installed. +This is a temporary fix until the GitLab image is updated with the new +GPG key. -Remember to sign in with the username and password you specified when you -[created your Azure VM](#basics). +The pre-configured GitLab image in Azure (provided by Bitnami) uses +a GPG key [deprecated in April 2020](https://about.gitlab.com/blog/2020/03/30/gpg-key-for-gitlab-package-repositories-metadata-changing/). -If you need to reset your VM password, read -[how to reset SSH credentials for a user on an Azure VM](https://docs.microsoft.com/en-us/troubleshoot/azure/virtual-machines/troubleshoot-ssh-connection). +If you try to update the repositories, you'll get the following error: -#### SSH from the command-line +<!-- vale gitlab.ReferenceLinks = NO --> -If you're running [SSH](https://en.wikipedia.org/wiki/Secure_Shell) from the command-line (terminal), then type in the following command to -connect to your VM, substituting `username` and `your-azure-domain-name.com` for the correct values. - -Again, remember that your Azure VM domain name will be the one you -[set up previously in the tutorial](#set-up-a-domain-name). If you didn't set up a domain name for -your VM, you can use the IP address in its place in the following command: - -```shell -ssh username@your-azure-domain-name.com +```plaintext +[ 21.023494] apt-setup[1198]: W: GPG error: https://packages.gitlab.com/gitlab/gitlab-ee/debian buster InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 3F01618A51312F3F +[ 21.024033] apt-setup[1198]: E: The repository 'https://packages.gitlab.com/gitlab/gitlab-ee/debian buster InRelease' is not signed. ``` -Provide your password at the prompt to authenticate. +<!-- vale gitlab.ReferenceLinks = YES --> -#### SSH from Windows (PuTTY) - -If you're using [PuTTY](https://www.putty.org) in Windows as your [SSH](https://en.wikipedia.org/wiki/Secure_Shell) client, then you might want to take a quick -read on [using PuTTY in Windows](https://mediatemple.net/community/products/dv/204404604/using-ssh-in-putty-). - -### Updating GitLab - -After signing in by using SSH, enter the following command to update GitLab to -the latest version: +To fix this, fetch the new GPG key: ```shell -sudo apt-get update && sudo apt-get install gitlab-ce -``` - -This command updates GitLab and its associated components to the latest versions, -so it will take a little time to complete. You'll see various update tasks being -completed in your SSH terminal window: - - - -After the update process is complete, you'll see a message like this: - -```plaintext -Upgrade complete! If your GitLab server is misbehaving try running - - sudo gitlab-ctl restart - -before anything else. +sudo apt install gpg-agent +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 ``` -#### Check out your updated GitLab - -Refresh your GitLab instance in the browser and navigate to the Admin Area. You should now have an -up-to-date GitLab instance. - -When we wrote this tutorial our Azure VM GitLab instance was updated to the latest version at time -of writing (`9.4.0`). You can see that the message which was previously displaying **"update asap"** -is now showing **"up-to-date"**: - - - -## Conclusion - -Naturally, we believe that GitLab is a great Git repository tool. However, GitLab is a whole lot -more than that too. GitLab unifies issues, code review, CI and CD into a single UI, helping you to -move faster from idea to production, and in this tutorial we showed you how quick and easy it is to -set up and run your own instance of GitLab on Azure, Microsoft's cloud service. - -Azure is a great way to experiment with GitLab, and if you decide (as we hope) that GitLab is for -you, you can continue to use Azure as your secure, scalable cloud provider or of course run GitLab -on any cloud service you choose. - -## Where to next? - -Check out our other [Technical Articles](../../topics/index.md) or browse the [GitLab Documentation](../../README.md) to learn more about GitLab. - -### Useful links - -- [GitLab Community Edition](https://about.gitlab.com/features/) -- [GitLab Enterprise Edition](https://about.gitlab.com/features/#ee) -- [Microsoft Azure](https://azure.microsoft.com/en-us/) - - [Azure - Free Account FAQ](https://azure.microsoft.com/en-us/free/free-account-faq/) - - [Azure - Marketplace](https://azuremarketplace.microsoft.com/en-us/marketplace/) - - [Azure Portal](https://portal.azure.com) - - [Azure - Pricing Calculator](https://azure.microsoft.com/en-us/pricing/calculator/) - - [Azure - Troubleshoot SSH Connections to an Azure Linux VM](https://docs.microsoft.com/en-us/troubleshoot/azure/virtual-machines/troubleshoot-ssh-connection) - - [Azure - Properly Shutdown an Azure VM](https://build5nines.com/properly-shutdown-azure-vm-to-save-money/) -- [SSH](https://en.wikipedia.org/wiki/Secure_Shell), [PuTTY](https://www.putty.org) and [Using SSH in PuTTY](https://mediatemple.net/community/products/dv/204404604/using-ssh-in-putty-) - -<!-- ## 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. --> +You can now [update GitLab](#update-gitlab). For more information, read about the +[packages signatures](https://docs.gitlab.com/omnibus/update/package_signatures.html). diff --git a/doc/install/installation.md b/doc/install/installation.md index 8497b2b5269..eb8c3784cfa 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -131,22 +131,45 @@ that: - Is always at the version required by GitLab. - May contain custom patches required for proper operation. -```shell -# Install dependencies -sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential +1. Install the needed dependencies: -# Clone the Gitaly repository -git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly + ```shell + sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev libpcre2-dev build-essential git-core + ``` -# Compile and install Git -cd /tmp/gitaly -sudo make git GIT_PREFIX=/usr/local -``` +1. Clone the Gitaly repository and compile Git. Replace `<X-Y-stable>` with the + stable branch that matches the GitLab version you want to install. For example, + if you want to install GitLab 13.6, use the branch name `13-6-stable`: + + ```shell + git clone https://gitlab.com/gitlab-org/gitaly.git -b <X-Y-stable> /tmp/gitaly + cd /tmp/gitaly + sudo make git GIT_PREFIX=/usr/local + ``` + +1. Optionally, you can remove the system Git and its dependencies: + + ```shell + sudo apt remove -y git-core + sudo apt autoremove + ``` + +When [editing `config/gitlab.yml` later](#configure-it), remember to change +the Git path: + +- From: + + ```yaml + git: + bin_path: /usr/bin/git + ``` -Replace `<X-Y-stable>` with the stable branch that matches the GitLab version you want to -install. For example, if you want to install GitLab 13.6, use the branch name `13-6-stable`. +- To: -When editing `config/gitlab.yml` later, change the `git -> bin_path` to `/usr/local/bin/git`. + ```yaml + git: + bin_path: /usr/local/bin/git + ``` ### GraphicsMagick @@ -212,7 +235,7 @@ curl --remote-name --progress-bar "https://cache.ruby-lang.org/pub/ruby/2.7/ruby echo 'cb9731a17487e0ad84037490a6baf8bfa31a09e8 ruby-2.7.2.tar.gz' | shasum -c - && tar xzf ruby-2.7.2.tar.gz cd ruby-2.7.2 -./configure --disable-install-rdoc +./configure --disable-install-rdoc --enable-shared make sudo make install ``` @@ -570,8 +593,8 @@ Install the gems (if you want to use Kerberos for user authentication, omit `kerberos` in the `--without` option below): ```shell -sudo -u git -H bundle config set deployment 'true' -sudo -u git -H bundle config set without 'development test mysql aws kerberos' +sudo -u git -H bundle config set --local deployment 'true' +sudo -u git -H bundle config set --local without 'development test mysql aws kerberos' sudo -u git -H bundle install ``` diff --git a/doc/install/pivotal/index.md b/doc/install/pivotal/index.md index eee70c2c578..ef6eb378346 100644 --- a/doc/install/pivotal/index.md +++ b/doc/install/pivotal/index.md @@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w WARNING: As of September 13, 2017, the GitLab Enterprise Plus for Pivotal Cloud Foundry -tile on Pivotal Network has reached its End of Availability (“EoA”) and is no +tile on Pivotal Network has reached its End of Availability ("EoA") and is no longer available for download or sale through Pivotal. Current customers with active subscriptions continue to receive support from GitLab through their subscription term. Pivotal and GitLab are collaborating on creating a new diff --git a/doc/install/postgresql_extensions.md b/doc/install/postgresql_extensions.md index 8d5a2a79b72..663ec547733 100644 --- a/doc/install/postgresql_extensions.md +++ b/doc/install/postgresql_extensions.md @@ -15,6 +15,7 @@ The following extensions must be loaded into the GitLab database: |--------------|------------------------| | `pg_trgm` | 8.6 | | `btree_gist` | 13.1 | +| `plpgsql` | 11.7 | In order to install extensions, PostgreSQL requires the user to have superuser privileges. Typically, the GitLab database user is not a superuser. Therefore, regular database migrations diff --git a/doc/install/relative_url.md b/doc/install/relative_url.md index e0971d7f354..d04f55c43a3 100644 --- a/doc/install/relative_url.md +++ b/doc/install/relative_url.md @@ -24,8 +24,8 @@ Note that by changing the URL on an existing GitLab installation, all remote URLs will change, so you'll have to manually edit them in any local repository that points to your GitLab instance. -The TL;DR list of configuration files that you need to change in order to -serve GitLab under a relative URL is: +The list of configuration files you must change to serve GitLab from a +relative URL is: - `/home/git/gitlab/config/initializers/relative_url.rb` - `/home/git/gitlab/config/gitlab.yml` diff --git a/doc/install/requirements.md b/doc/install/requirements.md index a1343dd5f98..70e95e284a3 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -17,7 +17,8 @@ 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/Enterprise Server 12.2) +- openSUSE Leap (15.1/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) - Oracle Linux (please use the CentOS packages and instructions) @@ -66,6 +67,11 @@ 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. @@ -94,8 +100,8 @@ from source at the [Node.js website](https://nodejs.org/en/download/). GitLab 13.0 and later requires Redis version 4.0 or higher. -Redis version 5.0 or higher is recommended, as this is what ships with -[Omnibus GitLab](https://docs.gitlab.com/omnibus/) packages starting with GitLab 12.7. +Redis version 6.0 or higher is recommended, as this is what ships with +[Omnibus GitLab](https://docs.gitlab.com/omnibus/) packages starting with GitLab 13.9. ## Hardware requirements |
