diff options
Diffstat (limited to 'doc')
267 files changed, 2589 insertions, 18434 deletions
diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 772e55cef07..94a8803fff1 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -50,7 +50,6 @@ Authentiq will generate a Client ID and the accompanying Client Secret for you t } ``` - 1. The `scope` is set to request the user's name, email (required and signed), and permission to send push notifications to sign in on subsequent visits. See [OmniAuth Authentiq strategy](https://github.com/AuthentiqID/omniauth-authentiq/wiki/Scopes,-callback-url-configuration-and-responses) for more information on scopes and modifiers. diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 0ac73c55580..37e596f198f 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -448,7 +448,6 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba port. - We are assuming the password for the bind_dn user is in bind_dn_password.txt. - ### Invalid credentials when logging in - Make sure the user you are binding with has enough permissions to read the user's diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index ae38094391b..3136923fa96 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -140,7 +140,6 @@ Now that the Okta app is configured, it's time to enable it in GitLab. } ``` - 1. [Reconfigure][reconf] or [restart] GitLab for Omnibus and installations from source respectively for the changes to take effect. diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md index db0b3e1270c..a1ac4a2a57c 100644 --- a/doc/administration/container_registry.md +++ b/doc/administration/container_registry.md @@ -542,7 +542,6 @@ Read more about the Container Registry notifications config options in the >**Note:** Multiple endpoints can be configured for the Container Registry. - **Omnibus GitLab installations** To configure a notification endpoint in Omnibus: @@ -587,7 +586,9 @@ notifications: backoff: 1000 ``` -## Using self-signed certificates with Container Registry +## Troubleshooting + +### Using self-signed certificates with Container Registry If you're using a self-signed certificate with your Container Registry, you might encounter issues during the CI jobs like the following: @@ -599,12 +600,18 @@ Error response from daemon: Get registry.example.com/v1/users/: x509: certificat The Docker daemon running the command expects a cert signed by a recognized CA, thus the error above. -While GitLab doesn't support using self-signed certificates with Container -Registry out of the box, it is possible to make it work if you follow -[Docker's documentation][docker-insecure-self-signed]. You may find some additional -information in [issue 18239][ce-18239]. +While GitLab doesn't support using self-signed certificates with Container Registry out of the box, it is possible to make it work by [instructing the docker-daemon to trust the self-signed certificates][docker-insecure-self-signed], mounting the docker-daemon and setting `privileged = false` in the runner's `config.toml`. Setting `privileged = true` takes precedence over the docker-daemon. -## Troubleshooting +``` + [runners.docker] + image = "ruby:2.1" + privileged = false + volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] +``` + +Additional information about this: [issue 18239][ce-18239]. + +### AWS S3 with the GitLab registry error when pushing large images When using AWS S3 with the GitLab registry, an error may occur when pushing large images. Look in the Registry log for the following error: diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index 2ca860bd763..e554c06532e 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -58,6 +58,7 @@ for each GitLab application server in your environment. # Disable components that will not be on the GitLab application server roles ['application_role'] + nginx['enable'] = true # PostgreSQL connection details gitlab_rails['db_adapter'] = 'postgresql' @@ -90,6 +91,8 @@ for each GitLab application server in your environment. certificates are not present, Nginx will fail to start. See [Nginx documentation](http://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) for more information. + > + > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure. ## First GitLab application server @@ -108,8 +111,9 @@ Additional GitLab servers (servers configured **after** the first GitLab server) need some extra configuration. 1. Configure shared secrets. These values can be obtained from the primary - GitLab server in `/etc/gitlab/gitlab-secrets.json`. Add these to - `/etc/gitlab/gitlab.rb` **prior to** running the first `reconfigure`. + GitLab server in `/etc/gitlab/gitlab-secrets.json`. Copy this file to the + secondary servers **prior to** running the first `reconfigure` in the steps + above. ```ruby gitlab_shell['secret_token'] = 'fbfb19c355066a9afb030992231c4a363357f77345edd0f2e772359e5be59b02538e1fa6cae8f93f7d23355341cea2b93600dab6d6c3edcdced558fc6d739860' diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md index 359de0efadb..28b226cacd5 100644 --- a/doc/administration/high_availability/load_balancer.md +++ b/doc/administration/high_availability/load_balancer.md @@ -8,7 +8,53 @@ choice already. Some examples including HAProxy (open-source), F5 Big-IP LTM, and Citrix Net Scaler. This documentation will outline what ports and protocols you need to use with GitLab. -## Basic ports +## SSL + +How will you handle SSL in your HA environment? There are several different +options: + +- Each application node terminates SSL +- The load balancer(s) terminate SSL and communication is not secure between + the load balancer(s) and the application nodes +- The load balancer(s) terminate SSL and communication is *secure* between the + load balancer(s) and the application nodes + +### Application nodes terminate SSL + +Configure your load balancer(s) to pass connections on port 443 as 'TCP' rather +than 'HTTP(S)' protocol. This will pass the connection to the application nodes +Nginx service untouched. Nginx will have the SSL certificate and listen on port 443. + +See [Nginx HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) +for details on managing SSL certificates and configuring Nginx. + +### Load Balancer(s) terminate SSL without backend SSL + +Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'. +The load balancer(s) will then be responsible for managing SSL certificates and +terminating SSL. + +Since communication between the load balancer(s) and GitLab will not be secure, +there is some additional configuration needed. See +[Nginx Proxied SSL documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) +for details. + +### Load Balancer(s) terminate SSL with backend SSL + +Configure your load balancer(s) to use the 'HTTP(S)' protocol rather than 'TCP'. +The load balancer(s) will be responsible for managing SSL certificates that +end users will see. + +Traffic will also be secure between the load balancer(s) and Nginx in this +scenario. There is no need to add configuration for proxied SSL since the +connection will be secure all the way. However, configuration will need to be +added to GitLab to configure SSL certificates. See +[Nginx HTTPS documentation](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https) +for details on managing SSL certificates and configuring Nginx. + +## Ports + +### Basic ports | LB Port | Backend Port | Protocol | | ------- | ------------ | --------------- | @@ -16,9 +62,9 @@ you need to use with GitLab. | 443 | 443 | TCP or HTTPS [^1] [^2] | | 22 | 22 | TCP | -## GitLab Pages Ports +### GitLab Pages Ports -If you're using GitLab Pages with custom domain support you will need some +If you're using GitLab Pages with custom domain support you will need some additional port configurations. GitLab Pages requires a separate virtual IP address. Configure DNS to point the `pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the @@ -29,7 +75,7 @@ GitLab Pages requires a separate virtual IP address. Configure DNS to point the | 80 | Varies [^3] | HTTP | | 443 | Varies [^3] | TCP [^4] | -## Alternate SSH Port +### Alternate SSH Port Some organizations have policies against opening SSH port 22. In this case, it may be helpful to configure an alternate SSH hostname that allows users diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index 987a0b9f350..bf5d064d79d 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -855,7 +855,6 @@ To make sure your configuration is correct: You should see a different port after a few seconds delay (the failover/reconnect time). - ## Changelog Changes to Redis HA over time. diff --git a/doc/administration/index.md b/doc/administration/index.md index 12fec2753bf..fff4538a7c9 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -4,24 +4,27 @@ description: 'Learn how to install, configure, update, and maintain your GitLab # Administrator documentation **[CORE ONLY]** -Learn how to administer your GitLab instance (Community Edition and -Enterprise Edition). -Regular users don't have access to GitLab administration tools and settings. +Learn how to administer your self-managed GitLab instance. -GitLab has two product distributions: the open source -[GitLab Community Edition (CE)](https://gitlab.com/gitlab-org/gitlab-ce), -and the open core [GitLab Enterprise Edition (EE)](https://gitlab.com/gitlab-org/gitlab-ee), -available through [different subscriptions](https://about.gitlab.com/pricing/). +GitLab has two product distributions available through [different subscriptions](https://about.gitlab.com/pricing/): -You can [install GitLab CE or GitLab EE](https://about.gitlab.com/installation/ce-or-ee/), -but the features you'll have access to depend on the subscription you choose -(Core, Starter, Premium, or Ultimate). GitLab Community Edition installations -only have access to Core features. +- The open source [GitLab Community Edition (CE)](https://gitlab.com/gitlab-org/gitlab-ce). +- The open core [GitLab Enterprise Edition (EE)](https://gitlab.com/gitlab-org/gitlab-ee). + +You can [install either GitLab CE or GitLab EE](https://about.gitlab.com/installation/ce-or-ee/). +However, the features you'll have access to depend on the subscription you choose +(Core, Starter, Premium, or Ultimate). + +NOTE: **Note:** +GitLab Community Edition installations only have access to Core features. GitLab.com is administered by GitLab, Inc., therefore, only GitLab team members have access to its admin configurations. If you're a GitLab.com user, please check the [user documentation](../user/index.html). +NOTE: **Note:** +Non-administrator users don’t have access to GitLab administration tools and settings. + ## Installing and maintaining GitLab Learn how to install, configure, update, and maintain your GitLab instance. @@ -127,7 +130,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Job traces](job_traces.md): Information about the job traces (logs). - [Register Shared and specific Runners](../ci/runners/README.md#registering-a-shared-runner): Learn how to register and configure Shared and specific Runners to your own instance. - [Shared Runners pipelines quota](../user/admin_area/settings/continuous_integration.md#shared-runners-pipeline-minutes-quota): Limit the usage of pipeline minutes for Shared Runners. -- [Enable/disable Auto DevOps](../topics/autodevops/index.md#enabling-auto-devops): Enable or disable Auto DevOps for your instance. +- [Enable/disable Auto DevOps](../topics/autodevops/index.md#enablingdisabling-auto-devops): Enable or disable Auto DevOps for your instance. ## Git configuration options diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index b61c5409a56..d383d1efe70 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -52,7 +52,6 @@ http://localhost:8080/plantuml you can change these defaults by editing the `/etc/tomcat7/server.xml` file. - ## GitLab You need to enable PlantUML integration from Settings under Admin Area. To do diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 40e03093743..25d85d1687b 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -64,8 +64,9 @@ narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` (although this may still have a few false positives). If you installed from source, or have made any configuration changes to your -Omnibus installation before upgrading to 8.15, you may need to make some -changes to your configuration. See the [8.14 to 8.15 upgrade](../../update/8.14-to-8.15.md#nginx-configuration) +Omnibus installation before upgrading to 8.15, you may need to make some changes +to your configuration. See the [Upgrading Community Edition and Enterprise +Edition from source](../../update/upgrading_from_source.md#nginx-configuration) document for more details. If you'd like to disable web terminal support in GitLab, just stop passing diff --git a/doc/administration/logs.md b/doc/administration/logs.md index 698f4caab3a..36dee75bd44 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -23,12 +23,13 @@ requests from the API are logged to a separate file in `api_json.log`. Each line contains a JSON line that can be ingested by Elasticsearch, Splunk, etc. For example: ```json -{"method":"GET","path":"/gitlab/gitlab-ce/issues/1234","format":"html","controller":"Projects::IssuesController","action":"show","status":200,"duration":229.03,"view":174.07,"db":13.24,"time":"2017-08-08T20:15:54.821Z","params":[{"key":"param_key","value":"param_value"}],"remote_ip":"18.245.0.1","user_id":1,"username":"admin","gitaly_calls":76} +{"method":"GET","path":"/gitlab/gitlab-ce/issues/1234","format":"html","controller":"Projects::IssuesController","action":"show","status":200,"duration":229.03,"view":174.07,"db":13.24,"time":"2017-08-08T20:15:54.821Z","params":[{"key":"param_key","value":"param_value"}],"remote_ip":"18.245.0.1","user_id":1,"username":"admin","gitaly_calls":76,"queue_duration": 112.47} ``` In this example, you can see this was a GET request for a specific issue. Notice each line also contains performance data: -1. `duration`: the total time taken to retrieve the request +1. `duration`: total time in milliseconds taken to retrieve the request +1. `queue_duration`: total time in milliseconds that the request was queued inside GitLab Workhorse 1. `view`: total time taken inside the Rails views 1. `db`: total time to retrieve data from the database 1. `gitaly_calls`: total number of calls made to Gitaly @@ -91,6 +92,8 @@ This entry above shows an access to an internal endpoint to check whether an associated SSH key can download the project in question via a `git fetch` or `git clone`. In this example, we see: +1. `duration`: total time in milliseconds taken to retrieve the request +1. `queue_duration`: total time in milliseconds that the request was queued inside GitLab Workhorse 1. `method`: The HTTP method used to make the request 1. `path`: The relative path of the query 1. `params`: Key-value pairs passed in a query string or HTTP body. Sensitive parameters (e.g. passwords, tokens, etc.) are filtered out. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 6ea0ac0d495..08cd23682d1 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -17,10 +17,7 @@ GitLab monitors its own internal service metrics, and makes them available at th `/-/metrics` endpoint. Unlike other [Prometheus] exporters, in order to access it, the client IP needs to be [included in a whitelist][whitelist]. -Currently the embedded Prometheus server is not automatically configured to -collect metrics from this endpoint. We recommend setting up another Prometheus -server, because the embedded server configuration is overwritten once every -[reconfigure of GitLab][reconfigure]. In the future this will not be required. +For Omnibus and Chart installations, these metrics are automatically enabled and collected as of [GitLab 9.4](https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/1702). For source installations or earlier verisons, these metrics will need to be enabled manually and collected by a Prometheus server. ## Unicorn Metrics available diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md index 3a35aff8366..b45ca99fd80 100644 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ b/doc/administration/operations/cleaning_up_redis_sessions.md @@ -20,7 +20,6 @@ configuration settings if you have used the advanced Redis settings outlined in [Configuration Files Documentation](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/README.md). - First we define a shell function with the proper Redis connection details. ``` diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 10ae8c7dedf..5c809f25fbd 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -11,7 +11,7 @@ description: 'Learn how to administer GitLab Pages.' > - This guide is for Omnibus GitLab installations. If you have installed > GitLab from source, follow the [Pages source installation document](source.md). > - To learn how to use GitLab Pages, read the [user documentation][pages-userguide]. -> - Does NOT support subgroups. See [this issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) for more information and status. +> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8. This document describes how to set up the _latest_ GitLab Pages feature. Make sure to read the [changelog](#changelog) if you are upgrading to a new GitLab diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 51e1518d73f..4934aaf39f7 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -41,7 +41,6 @@ Registry, etc. ## Hashed Storage - Hashed Storage is the new storage behavior we rolled out with 10.0. Instead of coupling project URL and the folder structure where the repository will be stored on disk, we are coupling a hash, based on the project's ID. This makes diff --git a/doc/administration/restart_gitlab.md b/doc/administration/restart_gitlab.md index b561c2f82aa..cbc3fbd9473 100644 --- a/doc/administration/restart_gitlab.md +++ b/doc/administration/restart_gitlab.md @@ -62,7 +62,8 @@ sudo gitlab-ctl status Notice that all services say `ok: run`. -Sometimes, components time out during the restart and sometimes they get stuck. +Sometimes, components time out (look for `timeout` in the logs) during the +restart and sometimes they get stuck. In that case, you can use `gitlab-ctl kill <service>` to send the `SIGKILL` signal to the service, for example `sidekiq`. After that, a restart should perform fine. @@ -136,7 +137,6 @@ If you are using other init systems, like systemd, you can check the [GitLab Recipes][gl-recipes] repository for some unofficial services. These are **not** officially supported so use them at your own risk. - [omnibus-dl]: https://about.gitlab.com/downloads/ "Download the Omnibus packages" [install]: ../install/installation.md "Documentation to install GitLab from source" [mailroom]: reply_by_email.md "Used for replying by email in GitLab issues and merge requests" diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 476ae8e8a76..9dfe085425f 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -149,7 +149,7 @@ _The uploads are stored by default in [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" -[eep]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition Premium" +[eep]: https://about.gitlab.com/gitlab-ee/ "GitLab Premium" [ce]: https://about.gitlab.com/gitlab-ce/ "GitLab Community Edition" [ee-3867]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3867 [ce-17358]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17358 diff --git a/doc/api/README.md b/doc/api/README.md index 3b43d195390..89069fe60e1 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -1,94 +1,133 @@ # GitLab API -Automate GitLab via a simple and powerful API. All definitions can be found -under [`/lib/api`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/api). +Automate GitLab via a simple and powerful API. The main GitLab API is a [REST](https://en.wikipedia.org/wiki/Representational_state_transfer) API. Therefore, documentation in this section assumes knowledge of REST concepts. -## API Resources - -The following API resources are available: - -- [Applications](applications.md) -- [Avatar](avatar.md) -- [Award emoji](award_emoji.md) -- [Branches](branches.md) -- [Broadcast messages](broadcast_messages.md) -- [Code snippets](snippets.md) -- [Commits](commits.md) -- [Container Registry](container_registry.md) -- [Custom attributes](custom_attributes.md) -- [Deploy keys](deploy_keys.md), and [deploy keys for multiple projects](deploy_key_multiple_projects.md) -- [Deployments](deployments.md) -- [Discussions](discussions.md) (threaded comments) -- [Environments](environments.md) -- [Events](events.md) -- [Feature flags](features.md) -- Group-related resources, including: - - [Groups](groups.md) - - [Group access requests](access_requests.md) - - [Group badges](group_badges.md) - - [Group issue boards](group_boards.md) - - [Group labels](group_labels.md) - - [Group-level variables](group_level_variables.md) - - [Group members](members.md) - - [Group milestones](group_milestones.md) -- [Issues](issues.md) -- [Issue boards](boards.md) -- [Jobs](jobs.md) -- [Keys](keys.md) -- [Labels](labels.md) -- [Markdown](markdown.md) -- [Merge requests](merge_requests.md) -- [Namespaces](namespaces.md) -- [Notes](notes.md) (comments) -- [Notification settings](notification_settings.md) -- [Pages domains](pages_domains.md) -- [Pipelines](pipelines.md) -- [Pipeline schedules](pipeline_schedules.md) -- [Pipeline triggers](pipeline_triggers.md) and [triggering pipelines](../ci/triggers/README.md) -- Project-related resources, including: - - [Projects](projects.md) including setting Webhooks - - [Project access requests](access_requests.md) - - [Project badges](project_badges.md) - - [Project clusters](project_clusters.md) - - [Project-level variables](project_level_variables.md) - - [Project import/export](project_import_export.md) - - [Project import from GitHub](import.md) - - [Project members](members.md) - - [Project milestones](milestones.md) - - [Project snippets](project_snippets.md) - - [Project templates](project_templates.md) (see also [Templates API Resources](#templates-api-resources)) -- [Protected branches](protected_branches.md) -- [Protected tags](protected_tags.md) -- [Repositories](repositories.md) -- [Repository files](repository_files.md) -- [Repository submodules](repository_submodules.md) -- [Resource label events](resource_label_events.md) -- [Runners](runners.md) -- [Search](search.md) -- [Services](services.md) -- [Settings](settings.md) -- [Sidekiq metrics](sidekiq_metrics.md) -- [System hooks](system_hooks.md) -- [Tags](tags.md) -- [Releases](releases/index.md) -- Release Assets - - [Links](releases/links.md) -- [Todos](todos.md) -- [Users](users.md) -- [Validate CI configuration](lint.md) (linting) -- [Version](version.md) -- [Wikis](wikis.md) - -See also [V3 to V4](v3_to_v4.md). - -### Templates API Resources +## API resources + +Available API resources can be grouped in the following contexts: + +- [Projects](#project-resources). +- [Groups](#group-resources). +- [Standalone](#standalone-resources). + +See also: + +- [V3 to V4](v3_to_v4.md). +- Adding [deploy keys for multiple projects](deploy_key_multiple_projects.md). + +### Project resources + +The following API resources are available in the project context: + +| Resource | Available endpoints | +|:------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | +| [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | +| [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | +| [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | +| [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` | +| [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) | +| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | +| [Deployments](deployments.md) | `/projects/:id/deployments` | +| [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` | +| [Environments](environments.md) | `/projects/:id/environments` | +| [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | +| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | +| [Issue boards](boards.md) | `/projects/:id/boards` | +| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | +| [Labels](labels.md) | `/projects/:id/labels` | +| [Members](members.md) | `/projects/:id/members` (also available for groups) | +| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | +| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` | +| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | +| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | +| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | +| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | +| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | +| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | +| [Project badges](project_badges.md) | `/projects/:id/badges` | +| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | +| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | +| [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` | +| [Project milestones](milestones.md) | `/projects/:id/milestones` | +| [Project snippets](project_snippets.md) | `/projects/:id/snippets` | +| [Project templates](project_templates.md) | `/projects/:id/templates` | +| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | +| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | +| [Releases](releases/index.md) | `/projects/:id/releases` | +| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | +| [Repositories](repositories.md) | `/projects/:id/repository` | +| [Repository files](repository_files.md) | `/projects/:id/repository/files` | +| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | +| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` | +| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | +| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | +| [Services](services.md) | `/projects/:id/services` | +| [Tags](tags.md) | `/projects/:id/repository/tags` | +| [Wikis](wikis.md) | `/projects/:id/wikis` | + +### Group resources + +The following API resources are available in the group context: + +| Resource | Available endpoints | +|:--------------------------------------------------|:---------------------------------------------------------------------------------| +| [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | +| [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | +| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | +| [Group badges](group_badges.md) | `/groups/:id/badges` | +| [Group issue boards](group_boards.md) | `/groups/:id/boards` | +| [Group labels](group_labels.md) | `/groups/:id/labels` | +| [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | +| [Group milestones](group_milestones.md) | `/groups/:id/milestones` | +| [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | +| [Members](members.md) | `/groups/:id/members` (also available for projects) | +| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | +| [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) | +| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | + +### Standalone resources + +The following API resources are available outside of project and group contexts (including `/users`): + +| Resource | Available endpoints | +|:--------------------------------------------------|:------------------------------------------------------------------------| +| [Applications](applications.md) | `/applications` | +| [Avatar](avatar.md) | `/avatar` | +| [Broadcast messages](broadcast_messages.md) | `/broadcast_messages` | +| [Code snippets](snippets.md) | `/snippets` | +| [Custom attributes](custom_attributes.md) | `/users/:id/custom_attributes` (also available for groups and projects) | +| [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | +| [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | +| [Feature flags](features.md) | `/features` | +| [Import repository from GitHub](import.md) | `/import/github` | +| [Issues](issues.md) | `/issues` (also available for groups and projects) | +| [Keys](keys.md) | `/keys` | +| [Markdown](markdown.md) | `/markdown` | +| [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | +| [Namespaces](namespaces.md) | `/namespaces` | +| [Notification settings](notification_settings.md) | `/notification_settings` (also available for groups and projects) | +| [Pages domains](pages_domains.md) | `/pages/domains` (also available for projects) | +| [Projects](projects.md) | `/users/:id/projects` (also available for projects) | +| [Runners](runners.md) | `/runners` (also available for projects) | +| [Search](search.md) | `/search` (also available for groups and projects) | +| [Settings](settings.md) | `/application/settings` | +| [Sidekiq metrics](sidekiq_metrics.md) | `/sidekiq` | +| [Suggestions](suggestions.md) | `/suggestions` | +| [System hooks](system_hooks.md) | `/hooks` | +| [Todos](todos.md) | `/todos` | +| [Users](users.md) | `/users` | +| [Validate `.gitlab-ci.yml` file](lint.md) | `/lint` | +| [Version](version.md) | `/version` | + +### Templates API resources Endpoints are available for: - [Dockerfile templates](templates/dockerfiles.md). -- [gitignore templates](templates/gitignores.md). +- [`.gitignore` templates](templates/gitignores.md). - [GitLab CI YAML templates](templates/gitlab_ci_ymls.md). - [Open source license templates](templates/licenses.md). @@ -110,7 +149,7 @@ have been resolved to our satisfaction by the relicensing of the reference implementations under MIT, and the use of the OWF license for the GraphQL specification. -## Compatibility Guidelines +## Compatibility guidelines The HTTP API is versioned using a single number, the current one being 4. This number symbolizes the same as the major version number as described by diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index 92936a277ac..1d0e39e6bbf 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -31,7 +31,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | Example request: @@ -93,7 +93,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of the award emoji. | Example request: @@ -138,7 +138,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `name` | string | yes | Name of the emoji without colons. | ```sh @@ -184,7 +184,7 @@ Parameters: | Attribute | Type | Required | Description | |:---------------|:---------------|:---------|:-----------------------------------------------------------------------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | -| `awardable_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | +| `issue_iid`/`merge_request_iid`/`snippet_id` | integer | yes | ID (`iid` for merge requests/issues, `id` for snippets) of an awardable. | | `award_id` | integer | yes | ID of an award emoji. | ```sh @@ -197,7 +197,8 @@ Comments (also known as notes) are a sub-resource of issues, merge requests, and NOTE: **Note:** The examples below describe working with award emoji on comments for an issue, but can be -easily adapted for comments on a merge request. +easily adapted for comments on a merge request or on a snippet. Therefore, you have to replace +`issue_iid` either with `merge_request_iid` or with the `snippet_id`. ### List a comment's award emoji diff --git a/doc/api/boards.md b/doc/api/boards.md index 2a2622736c3..28c73db6b98 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -37,7 +37,7 @@ Example response: "web_url": "http://example.com/diaspora/diaspora-project-site" }, "milestone": { - "id": 12 + "id": 12, "title": "10.0" }, "lists" : [ @@ -95,7 +95,7 @@ Example response: ```json { "id": 1, - "name:": "project issue board", + "name": "project issue board", "project": { "id": 5, "name": "Diaspora Project Site", @@ -106,7 +106,7 @@ Example response: "web_url": "http://example.com/diaspora/diaspora-project-site" }, "milestone": { - "id": 12 + "id": 12, "title": "10.0" }, "lists" : [ diff --git a/doc/api/branches.md b/doc/api/branches.md index 62468b6e917..31c8add300d 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -22,6 +22,7 @@ Parameters: |:----------|:---------------|:---------|:------------| | `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user.| | `search` | string | no | Return list of branches containing the search string. You can use `^term` and `term$` to find branches that begin and end with `term` respectively.| + Example request: ```sh diff --git a/doc/api/commits.md b/doc/api/commits.md index 14742f034e0..8d36ae7d559 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -18,7 +18,6 @@ GET /projects/:id/repository/commits | `all` | boolean | no | Retrieve every commit from the repository | | `with_stats` | boolean | no | Stats about each commit will be added to the response | - ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits" ``` @@ -81,7 +80,6 @@ POST /projects/:id/repository/commits | `author_name` | string | no | Specify the commit author's name | | `stats` | boolean | no | Include commit stats. Default is true | - | `actions[]` Attribute | Type | Required | Description | | --------------------- | ---- | -------- | ----------- | | `action` | string | yes | The action to perform, `create`, `delete`, `move`, `update`, `chmod`| @@ -601,7 +599,6 @@ GET /projects/:id/repository/commits/:sha/merge_requests | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA - ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests" ``` @@ -656,6 +653,46 @@ Example response: ] ``` +## Get GPG signature of a commit + +Get the [GPG signature from a commit](../user/project/repository/gpg_signed_commits/index.md), +if it is signed. For unsigned commits, it results in a 404 response. + +``` +GET /projects/:id/repository/commits/:sha/signature +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +| `sha` | string | yes | The commit hash or name of a repository branch or tag | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature" +``` + +Example response if commit is signed: + +```json +{ + "gpg_key_id": 1, + "gpg_key_primary_keyid": "8254AAB3FBD54AC9", + "gpg_key_user_name": "John Doe", + "gpg_key_user_email": "johndoe@example.com", + "verification_status": "verified", + "gpg_key_subkey_id": null +} +``` + +Example response if commit is unsigned: +```json +{ + "message": "404 GPG Signature Not Found" +} +``` + [ce-6096]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6096 "Multi-file commit" [ce-8047]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8047 [ce-15026]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15026 diff --git a/doc/api/container_registry.md b/doc/api/container_registry.md index c77ed39e4dc..1f17af1f1e9 100644 --- a/doc/api/container_registry.md +++ b/doc/api/container_registry.md @@ -16,7 +16,6 @@ GET /projects/:id/registry/repositories | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | - ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/registry/repositories" ``` diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 79090ea5254..7d68d0ae744 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -641,7 +641,6 @@ Parameters: curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/5/merge_requests/11/discussions/6a9c1750b37d513a43987b574953fceb50b03ce7?resolved=true ``` - ### Add note to existing merge request discussion Adds a new note to the discussion. diff --git a/doc/api/features.md b/doc/api/features.md index 47f104e1f20..6ecd4ec14b9 100644 --- a/doc/api/features.md +++ b/doc/api/features.md @@ -60,10 +60,11 @@ POST /features/:name | `value` | integer/string | yes | `true` or `false` to enable/disable, or an integer for percentage of time | | `feature_group` | string | no | A Feature group name | | `user` | string | no | A GitLab username | +| `group` | string | no | A GitLab group's path, for example 'gitlab-org' | | `project` | string | no | A projects path, for example 'gitlab-org/gitlab-ce' | Note that you can enable or disable a feature for a `feature_group`, a `user`, -and a `project` in a single API call. +a `group`, and a `project` in a single API call. ```bash curl --data "value=30" --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/features/new_library diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index c36d34b4af1..3d4b099b49e 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -1,6 +1,6 @@ -# Group Label API +# Group Labels API ->**Note:** This feature was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21368) in GitLab 11.8. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/21368) in GitLab 11.8. This API supports managing of [group labels](../user/project/labels.md#project-labels-and-group-labels). It allows to list, create, update, and delete group labels. Furthermore, users can subscribe and unsubscribe to and from group labels. @@ -14,7 +14,7 @@ GET /groups/:id/labels | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels @@ -28,6 +28,7 @@ Example response: "id": 7, "name": "bug", "color": "#FF0000", + "text_color" : "#FFFFFF", "description": null, "open_issues_count": 0, "closed_issues_count": 0, @@ -38,6 +39,7 @@ Example response: "id": 4, "name": "feature", "color": "#228B22", + "text_color" : "#FFFFFF", "description": null, "open_issues_count": 0, "closed_issues_count": 0, @@ -60,7 +62,7 @@ POST /groups/:id/labels | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | -| `description` | string | no | The description of the label | +| `description` | string | no | The description of the label, | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "color": "#FFA500", "description": "Describes new ideas" }' https://gitlab.example.com/api/v4/groups/5/labels @@ -73,6 +75,7 @@ Example response: "id": 9, "name": "Feature Proposal", "color": "#FFA500", + "text_color" : "#FFFFFF", "description": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, @@ -95,7 +98,7 @@ PUT /groups/:id/labels | `name` | string | yes | The name of the label | | `new_name` | string | no | The new name of the label | | `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | -| `description` | string | no | The description of the label | +| `description` | string | no | The description of the label. | ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "Feature Proposal", "new_name": "Feature Idea" }' https://gitlab.example.com/api/v4/groups/5/labels @@ -108,6 +111,7 @@ Example response: "id": 9, "name": "Feature Idea", "color": "#FFA500", + "text_color" : "#FFFFFF", "description": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, @@ -127,7 +131,7 @@ DELETE /groups/:id/labels | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the label | +| `name` | string | yes | The name of the label. | ```bash curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels?name=bug @@ -145,7 +149,7 @@ POST /groups/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `label_id` | integer or string | yes | The ID or title of a group's label | +| `label_id` | integer or string | yes | The ID or title of a group's label. | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/9/subscribe @@ -158,6 +162,7 @@ Example response: "id": 9, "name": "Feature Idea", "color": "#FFA500", + "text_color" : "#FFFFFF", "description": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, @@ -179,7 +184,7 @@ POST /groups/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `label_id` | integer or string | yes | The ID or title of a group's label | +| `label_id` | integer or string | yes | The ID or title of a group's label. | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/labels/9/unsubscribe @@ -192,6 +197,7 @@ Example response: "id": 9, "name": "Feature Idea", "color": "#FFA500", + "text_color" : "#FFFFFF", "description": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 7be01ce9c6d..eb974267084 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -48,7 +48,6 @@ Example Response: ] ``` - ## Get single milestone Gets a single group milestone. diff --git a/doc/api/import.md b/doc/api/import.md index 9f8e0d232c6..1deb26e8388 100644 --- a/doc/api/import.md +++ b/doc/api/import.md @@ -15,7 +15,6 @@ POST /import/github | `new_name` | string | no | New repo name | | `target_namespace` | string | yes | Namespace to import repo into | - ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --data "personal_access_token=abc123&repo_id=12345&target_namespace=root" https://gitlab.example.com/api/v4/import/github ``` @@ -30,4 +29,3 @@ Example response: "full_name": "Administrator / my-repo" } ``` - diff --git a/doc/api/issues.md b/doc/api/issues.md index ed3165d95df..0571f280d2a 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -110,6 +110,7 @@ Example response: "labels" : [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "user_notes_count": 1, "due_date": "2016-07-22", "web_url": "http://example.com/example/example/issues/6", @@ -168,7 +169,6 @@ GET /groups/:id/issues?my_reaction_emoji=star | `updated_after` | datetime | no | Return issues updated on or after the given time | | `updated_before` | datetime | no | Return issues updated on or before the given time | - ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4/issues ``` @@ -220,6 +220,7 @@ Example response: "labels" : [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "id" : 41, "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", @@ -335,6 +336,7 @@ Example response: "labels" : [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "id" : 41, "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", @@ -431,6 +433,7 @@ Example response: "labels" : [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "id" : 41, "title" : "Ut commodi ullam eos dolores perferendis nihil sunt.", "updated_at" : "2016-01-04T15:31:46.176Z", @@ -506,6 +509,7 @@ Example response: ], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "author" : { "name" : "Alexandra Bashirian", "avatar_url" : null, @@ -568,7 +572,6 @@ PUT /projects/:id/issues/:issue_iid | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | | `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | - ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close ``` @@ -606,6 +609,7 @@ Example response: ], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "id" : 85, "assignees" : [], "assignee" : null, @@ -692,6 +696,7 @@ Example response: "labels": [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "milestone": null, "assignees": [{ "name": "Miss Monserrate Beier", @@ -776,6 +781,7 @@ Example response: "labels": [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "milestone": null, "assignees": [{ "name": "Miss Monserrate Beier", @@ -822,7 +828,6 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. - **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. ## Unsubscribe from an issue @@ -859,6 +864,7 @@ Example response: "labels": [], "upvotes": 4, "downvotes": 0, + "merge_requests_count": 0, "milestone": null, "assignee": { "name": "Edwardo Grady", @@ -976,6 +982,7 @@ Example response: "user_notes_count": 7, "upvotes": 0, "downvotes": 0, + "merge_requests_count": 0, "due_date": null, "web_url": "http://example.com/example/example/issues/110", "confidential": false, @@ -990,7 +997,6 @@ Example response: **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. - **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. ## Set a time estimate for an issue @@ -1288,7 +1294,6 @@ Example response: ] ``` - ## Participants on issues ``` @@ -1327,7 +1332,6 @@ Example response: ] ``` - ## Comments on issues Comments are done via the [notes](notes.md) resource. diff --git a/doc/api/labels.md b/doc/api/labels.md index aec1a2c7592..9d10d383bf9 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -24,56 +24,66 @@ Example response: "id" : 1, "name" : "bug", "color" : "#d9534f", + "text_color" : "#FFFFFF", "description": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": false, - "priority": 10 + "priority": 10, + "is_project_label": true }, { "id" : 4, "color" : "#d9534f", + "text_color" : "#FFFFFF", "name" : "confirmed", "description": "Confirmed issue", "open_issues_count": 2, "closed_issues_count": 5, "open_merge_requests_count": 0, "subscribed": false, - "priority": null + "priority": null, + "is_project_label": true }, { "id" : 7, "name" : "critical", "color" : "#d9534f", + "text_color" : "#FFFFFF", "description": "Critical issue. Need fix ASAP", "open_issues_count": 1, "closed_issues_count": 3, "open_merge_requests_count": 1, "subscribed": false, - "priority": null + "priority": null, + "is_project_label": true }, { "id" : 8, "name" : "documentation", "color" : "#f0ad4e", + "text_color" : "#FFFFFF", "description": "Issue about documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, "subscribed": false, - "priority": null + "priority": null, + "is_project_label": false }, { "id" : 9, "color" : "#5cb85c", + "text_color" : "#FFFFFF", "name" : "enhancement", "description": "Enhancement proposal", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": true, - "priority": null + "priority": null, + "is_project_label": true } ] ``` @@ -105,12 +115,14 @@ Example response: "id" : 10, "name" : "feature", "color" : "#5843AD", + "text_color" : "#FFFFFF", "description":null, "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, "subscribed": false, - "priority": null + "priority": null, + "is_project_label": true } ``` @@ -149,7 +161,6 @@ PUT /projects/:id/labels | `description` | string | no | The new description of the label | | `priority` | integer | no | The new priority of the label. Must be greater or equal than zero or `null` to remove the priority. | - ```bash curl --request PUT --data "name=documentation&new_name=docs&color=#8E44AD&description=Documentation" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/labels" ``` @@ -161,12 +172,14 @@ Example response: "id" : 8, "name" : "docs", "color" : "#8E44AD", + "text_color" : "#FFFFFF", "description": "Documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, "subscribed": false, - "priority": null + "priority": null, + "is_project_label": true } ``` @@ -196,12 +209,14 @@ Example response: "id" : 1, "name" : "bug", "color" : "#d9534f", + "text_color" : "#FFFFFF", "description": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, "subscribed": true, - "priority": null + "priority": null, + "is_project_label": true } ``` diff --git a/doc/api/lint.md b/doc/api/lint.md index a0307f7081d..71c09d35b8c 100644 --- a/doc/api/lint.md +++ b/doc/api/lint.md @@ -2,7 +2,7 @@ > [Introduced][ce-5953] in GitLab 8.12. -Checks if your .gitlab-ci.yml file is valid. +Checks if your `.gitlab-ci.yml` file is valid. ``` POST /lint diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index d58cd45538d..e176cdffc5f 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -160,7 +160,6 @@ will be the same. In the case of a merge request from a fork, `target_project_id` and `project_id` will be the same and `source_project_id` will be the fork project's ID. - Parameters: | Attribute | Type | Required | Description | @@ -435,6 +434,9 @@ Parameters: "avatar_url": null, "web_url" : "https://gitlab.example.com/admin" }, + "user" : { + "can_merge" : false + } "assignee": { "id": 1, "name": "Administrator", @@ -528,7 +530,6 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request - ```json [ { @@ -563,7 +564,6 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request - ```json [ { diff --git a/doc/api/oauth2.md b/doc/api/oauth2.md index 6e156a14b25..dfe62554852 100644 --- a/doc/api/oauth2.md +++ b/doc/api/oauth2.md @@ -206,4 +206,3 @@ or you can put the token to the Authorization header: ``` curl --header "Authorization: Bearer OAUTH-TOKEN" https://gitlab.example.com/api/v4/user ``` - diff --git a/doc/api/pages_domains.md b/doc/api/pages_domains.md index 4c41350dcdb..70fbe24099f 100644 --- a/doc/api/pages_domains.md +++ b/doc/api/pages_domains.md @@ -8,7 +8,7 @@ The GitLab Pages feature must be enabled to use these endpoints. Find out more a Get a list of all pages domains. The user must have admin permissions. -```http +```text GET /pages/domains ``` @@ -34,7 +34,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Get a list of project pages domains. The user must have permissions to view pages domains. -```http +```text GET /projects/:id/pages/domains ``` @@ -69,7 +69,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Get a single project pages domain. The user must have permissions to view pages domains. -```http +```text GET /projects/:id/pages/domains/:domain ``` @@ -110,7 +110,7 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/ap Creates a new pages domain. The user must have permissions to create new pages domains. -```http +```text POST /projects/:id/pages/domains ``` @@ -146,7 +146,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "domain Updates an existing project pages domain. The user must have permissions to change an existing pages domains. -```http +```text PUT /projects/:id/pages/domains/:domain ``` @@ -182,7 +182,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --form "certifi Deletes an existing project pages domain. -```http +```text DELETE /projects/:id/pages/domains/:domain ``` diff --git a/doc/api/project_import_export.md b/doc/api/project_import_export.md index fc91c5741da..5155e996158 100644 --- a/doc/api/project_import_export.md +++ b/doc/api/project_import_export.md @@ -1,8 +1,8 @@ # Project import/export API -[Introduced][ce-41899] in GitLab 10.6 +> [Introduced][ce-41899] in GitLab 10.6. -[See also the project import/export documentation](../user/project/settings/import_export.md) +See also the [project import/export documentation](../user/project/settings/import_export.md). ## Schedule an export @@ -16,7 +16,7 @@ data file uploads to the final server. If the `upload` params is present, `upload[url]` param is required. (**Note:** This feature was introduced in GitLab 10.7) -```http +```text POST /projects/:id/export ``` @@ -28,8 +28,7 @@ POST /projects/:id/export | `upload[url]` | string | yes | The URL to upload the project | | `upload[http_method]` | string | no | The HTTP method to upload the exported project. Only `PUT` and `POST` methods allowed. Default is `PUT` | - -```console +```sh curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/export \ --data "upload[http_method]=PUT" \ --data-urlencode "upload[url]=https://example-bucket.s3.eu-west-3.amazonaws.com/backup?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIMBJHN2O62W8IELQ%2F20180312%2Feu-west-3%2Fs3%2Faws4_request&X-Amz-Date=20180312T110328Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=8413facb20ff33a49a147a0b4abcff4c8487cc33ee1f7e450c46e8f695569dbd" @@ -45,7 +44,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab Get the status of export. -```http +```text GET /projects/:id/export ``` @@ -53,7 +52,7 @@ GET /projects/:id/export | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -```console +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/export ``` @@ -86,7 +85,7 @@ to a web server, etc. Download the finished export. -```http +```text GET /projects/:id/export/download ``` @@ -94,18 +93,18 @@ GET /projects/:id/export/download | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -```console +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name --remote-name https://gitlab.example.com/api/v4/projects/5/export/download ``` -```console +```sh ls *export.tar.gz 2017-12-05_22-11-148_namespace_project_export.tar.gz ``` ## Import a file -```http +```text POST /projects/import ``` @@ -124,7 +123,7 @@ cURL to post data using the header `Content-Type: multipart/form-data`. The `file=` parameter must point to a file on your file system and be preceded by `@`. For example: -```console +```sh curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "path=api-project" --form "file=@/path/to/file" https://gitlab.example.com/api/v4/projects/import ``` @@ -168,7 +167,7 @@ requests.post(url, headers=headers, data=data, files=files) Get the status of an import. -```http +```text GET /projects/:id/import ``` @@ -176,7 +175,7 @@ GET /projects/:id/import | --------- | -------------- | -------- | ---------------------------------------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -```console +```sh curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/import ``` diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 8f4640fcbd6..f02674adfe2 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -124,7 +124,6 @@ Parameters: > **Notes:** > [Introduced][ce-29508] in GitLab 9.4. - Available only for admins. ``` diff --git a/doc/api/project_templates.md b/doc/api/project_templates.md index ef98205cd68..3b5b12c8da3 100644 --- a/doc/api/project_templates.md +++ b/doc/api/project_templates.md @@ -101,7 +101,6 @@ GET /projects/:id/templates/:type/:key Example response (Dockerfile): - ```json { "name": "Binary", diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index fa04680d406..a261bb75be5 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -5,6 +5,7 @@ **Valid access levels** The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` method. Currently, these levels are recognized: + ``` 0 => No access 30 => Developer access diff --git a/doc/api/releases/index.md b/doc/api/releases/index.md index 943109a3ea9..e7f79a0d359 100644 --- a/doc/api/releases/index.md +++ b/doc/api/releases/index.md @@ -2,7 +2,7 @@ > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. > - Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) entries. -> - For manipulating links as a release asset, see [Release Links API](links.md) +> - For manipulating links as a release asset, see [Release Links API](links.md). ## List Releases @@ -14,7 +14,7 @@ GET /projects/:id/releases | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | Example request: @@ -160,7 +160,7 @@ GET /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag where the release will be created from. | Example request: @@ -239,10 +239,10 @@ POST /projects/:id/releases | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | | `name` | string | yes | The release name. | | `tag_name` | string | yes | The tag where the release will be created from. | -| `description` | string | yes | The description of the release. You can use [markdown](../user/markdown.md). | +| `description` | string | yes | The description of the release. You can use [markdown](../../user/markdown.md). | | `ref` | string | no | If `tag_name` doesn't exist, the release will be created from `ref`. It can be a commit SHA, another tag name, or a branch name. | | `assets:links`| array of hash | no | An array of assets links. | | `assets:links:name`| string | no (if `assets:links` specified, it's required) | The name of the link. | @@ -331,10 +331,10 @@ PUT /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag where the release will be created from. | | `name` | string | no | The release name. | -| `description` | string | no | The description of the release. You can use [markdown](../user/markdown.md). | +| `description` | string | no | The description of the release. You can use [markdown](../../user/markdown.md). | Example request: @@ -412,7 +412,7 @@ DELETE /projects/:id/releases/:tag_name | Attribute | Type | Required | Description | | ------------- | -------------- | -------- | --------------------------------------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding). | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). | | `tag_name` | string | yes | The tag where the release will be created from. | Example request: diff --git a/doc/api/releases/links.md b/doc/api/releases/links.md index ae99f3bd8b6..fd7b9d6e6e2 100644 --- a/doc/api/releases/links.md +++ b/doc/api/releases/links.md @@ -3,6 +3,7 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/41766) in GitLab 11.7. Using this API you can manipulate GitLab's [Release](../../user/project/releases/index.md) links. For manipulating other Release assets, see [Release API](index.md). +GitLab supports links links to `http`, `https`, and `ftp` assets. ## Get links diff --git a/doc/api/repositories.md b/doc/api/repositories.md index 104c64a89ce..681dc72c934 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -119,7 +119,11 @@ would send an archive in ZIP format. Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `sha` (optional) - The commit SHA to download. A tag, branch reference or sha can be used. This defaults to the tip of the default branch if not specified +- `sha` (optional) - The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. For example: + + ```sh + curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.com/api/v4/projects/<project_id>/repository/archive?sha=<commit_sha> + ``` ## Compare branches, tags or commits diff --git a/doc/api/search.md b/doc/api/search.md index aaaed7d9956..aa601648b2c 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -281,7 +281,6 @@ Example response: ] ``` - ## Group Search API Search within the specified group. @@ -520,7 +519,6 @@ Search the expression within the specified scope. Currently these scopes are sup The response depends on the requested scope. - ### Scope: issues ```bash diff --git a/doc/api/services.md b/doc/api/services.md index 868bcdd07fc..5d5aa3e5b3e 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -412,7 +412,7 @@ Google GSuite team collaboration tool. Set Hangouts Chat service for a project. ``` -PUT /projects/:id/services/hangouts_chat +PUT /projects/:id/services/hangouts-chat ``` >**Note:** Specific event parameters (e.g. `push_events` flag) were [introduced in v10.4][11435] @@ -438,7 +438,7 @@ Parameters: Delete Hangouts Chat service for a project. ``` -DELETE /projects/:id/services/hangouts_chat +DELETE /projects/:id/services/hangouts-chat ``` ### Get Hangouts Chat service settings @@ -446,46 +446,7 @@ DELETE /projects/:id/services/hangouts_chat Get Hangouts Chat service settings for a project. ``` -GET /projects/:id/services/hangouts_chat -``` - -## HipChat - -Private group chat and IM - -### Create/Edit HipChat service - -Set HipChat service for a project. - -``` -PUT /projects/:id/services/hipchat -``` - -Parameters: - -| Parameter | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `token` | string | true | Room token | -| `color` | string | false | The room color | -| `notify` | boolean | false | Enable notifications | -| `room` | string | false |Room name or ID | -| `api_version` | string | false | Leave blank for default (v2) | -| `server` | string | false | Leave blank for default. For example, `https://hipchat.example.com`. | - -### Delete HipChat service - -Delete HipChat service for a project. - -``` -DELETE /projects/:id/services/hipchat -``` - -### Get HipChat service settings - -Get HipChat service settings for a project. - -``` -GET /projects/:id/services/hipchat +GET /projects/:id/services/hangouts-chat ``` ## Irker (IRC gateway) diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index 95dcf2d5277..5f2202fa51d 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -149,4 +149,3 @@ Example response: } } ``` - diff --git a/doc/api/tags.md b/doc/api/tags.md index 23dbf2d9ff7..3177fec618f 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -163,7 +163,6 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag - ## Create a new release Add release notes to the existing git tag. If there diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index 3804855129c..bf6a914e120 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -1,8 +1,8 @@ -# Gitignores API +# `.gitignore` API -## List gitignore templates +## List `.gitignore` templates -Get all gitignore templates. +Get all `.gitignore` templates. ``` GET /templates/gitignores @@ -99,9 +99,9 @@ Example response: ] ``` -## Single gitignore template +## Single `.gitignore` template -Get a single gitignore template. +Get a single `.gitignore` template. ``` GET /templates/gitignores/:key @@ -109,7 +109,7 @@ GET /templates/gitignores/:key | Attribute | Type | Required | Description | | ---------- | ------ | -------- | ----------- | -| `key` | string | yes | The key of the gitignore template | +| `key` | string | yes | The key of the `.gitignore` template | ```bash curl https://gitlab.example.com/api/v4/templates/gitignores/Ruby diff --git a/doc/api/users.md b/doc/api/users.md index fd8778abb17..b0977810120 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1043,7 +1043,6 @@ Will return `201 OK` on success, `404 User Not Found` is user cannot be found or Please refer to the [Events API documentation](events.md#get-user-contribution-events) - ## Get all impersonation tokens of a user > Requires admin permissions. diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 436d06cfd3a..12f048ac09b 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -119,7 +119,6 @@ PUT /projects/:id/wikis/:slug | `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` | | `slug` | string | yes | The slug (a unique string) of the wiki page | - ```bash curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo" ``` diff --git a/doc/articles/openshift_and_gitlab/index.md b/doc/articles/openshift_and_gitlab/index.md index 76fdb2eb00a..822d012aa3d 100644 --- a/doc/articles/openshift_and_gitlab/index.md +++ b/doc/articles/openshift_and_gitlab/index.md @@ -1,4 +1,3 @@ --- redirect_to: '../../install/openshift_and_gitlab/index.html' --- - diff --git a/doc/ci/README.md b/doc/ci/README.md index 4e066a0df97..e44db230a7f 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -5,131 +5,193 @@ description: "Learn how to use GitLab CI/CD, the GitLab built-in Continuous Inte # GitLab Continuous Integration (GitLab CI/CD) - +GitLab provides tools for continuously integrating and delivering code. + +Within the [entire DevOps lifecycle](../README.md#the-entire-devops-lifecycle), GitLab CI/CD spans +the [Verify (CI)](../README.md#verify) and [Release (CD)](../README.md#release) stages. -The benefits of Continuous Integration are huge when automation plays an -integral part of your workflow. GitLab comes with built-in Continuous -Integration, Continuous Deployment, and Continuous Delivery support -to build, test, and deploy your application. +## Overview -Here's some info we've gathered to get you started. +CI/CD is a vast area, so GitLab provides documentation for all levels of expertise. Consult the following table to find the right documentation for you: -## Getting started +| Level of expertise | Resource | +|:------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------| +| New to the concepts of CI and CD | For a high-level overview, see the [GitLab Continuous Integration & Delivery](https://about.gitlab.com/product/continuous-integration/) product page. | +| Familiar with the purpose of CI/CD | Delve into GitLab CI/CD by continuing down the page, starting with our [introduction](#introduction). | +| Familiar with GitLab CI/CD concepts | After getting familiar with GitLab CI/CD, let us walk you through a simple example in our [quick start guide](quick_start/README.md). | +| A GitLab CI/CD expert | Jump straight to our [`.gitlab.yml`](yaml/README.md) reference. | -The first steps towards your GitLab CI/CD journey. +## Introduction -- [Getting started with GitLab CI/CD](quick_start/README.md): understand how GitLab CI/CD works. -- [GitLab CI/CD configuration file: `.gitlab-ci.yml`](yaml/README.md) - Learn all about the ins and outs of `.gitlab-ci.yml`. -- [Pipelines and jobs](pipelines.md): configure your GitLab CI/CD pipelines to build, test, and deploy your application. -- Runners: The [GitLab Runner](https://docs.gitlab.com/runner/) is responsible by running the jobs in your CI/CD pipeline. On GitLab.com, Shared Runners are enabled by default, so -you don't need to set up anything to start to use them with GitLab CI/CD. +The following introduces the process of continuous integration (CI) and continuous delivery (CD): -### Introduction to GitLab CI/CD + -- Article (2016-08-05): [Continuous Integration, Delivery, and Deployment with GitLab - Intro to CI/CD](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) -- Article (2015-12-14): [Getting started with GitLab and GitLab CI - Intro to CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) -- Article (2017-07-13): [Making CI Easier with GitLab](https://about.gitlab.com/2017/07/13/making-ci-easier-with-gitlab/) -- Article (2017-05-22): [Fast and Natural Continuous Integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/) -- **Videos:** - - Demo (Streamed live on Jul 17, 2017): [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195) - - Demo (March, 2017): [How to get started using CI/CD with GitLab](https://about.gitlab.com/2017/03/13/ci-cd-demo/) - - Webcast (April, 2016): [Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/) -- **Third-party videos:** - - [Intégration continue avec GitLab (September, 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s) - - [GitLab CI for Minecraft Plugins (July, 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8) +In this illustration: -### Why GitLab CI/CD? +- New code is combined with existing code through a commit to a project's [repository](../user/project/repository/index.md). +- The newly combined code is sent to a CI [pipeline](pipelines.md) where: + - The code is [built](../user/project/pipelines/job_artifacts.md). + - Unit and integration tests are run over the built code. +- Assuming the build and tests are successful, a CD pipeline is triggered to allow for: + - Review using [Review Apps](review_apps/index.md). + - Deploying to configured [environments](environments.md). - - Article (2016-10-17): [Why We Chose GitLab CI for our CI/CD Solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/) - - Article (2016-07-22): [Building our web-app on GitLab CI: 5 reasons why Captain Train migrated from Jenkins to GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/) +The benefits of CI/CD are vast, allowing automation to be an integral part of your workflow for testing, building, deploying, and monitoring your code. -## Exploring GitLab CI/CD +Because CI and CD with GitLab is broad topic with many possibilities, the rest of this section provides +links to topics and resources needed to make use of GitLab CI/CD. -- [CI/CD Variables](variables/README.md) - Learn how to use variables defined in - your `.gitlab-ci.yml` or the ones defined in your project's settings - - [Where variables can be used](variables/where_variables_can_be_used.md) - A - deeper look on where and how the CI/CD variables can be used -- **The permissions model** - Learn about the access levels a user can have for - performing certain CI actions - - [User permissions](../user/permissions.md#gitlab-ci) - - [Job permissions](../user/permissions.md#job-permissions) -- [Configure a Runner, the application that runs your jobs](runners/README.md) -- Article (2016-03-01): [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) -- Article (2016-07-29): [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) -- Article (2016-08-26): [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) -- Article (2016-05-23): [Introduction to GitLab Container Registry](https://about.gitlab.com/2016/05/23/gitlab-container-registry/) +## Essentials -## Advanced use +The following documentation provides the minimum required knowledge for making use of GitLab CI/CD: -Once you get familiar with the basics of GitLab CI/CD, it's time to dive in and -learn how to leverage its potential even more. +| Topic | Description | +|:------------------------------------------------------------------------|:---------------------------------------------------------| +| [Getting started with GitLab CI/CD](quick_start/README.md) | Outlines the first steps for configuring GitLab CI/CD. | +| [Introduction to pipelines and jobs](pipelines.md) | Provides an overview of GitLab CI/CD and jobs. | +| [Configuration of your pipelines with `.gitlab-ci.yml`](yaml/README.md) | A comprehensive reference for the `.gitlab-ci.yml` file. | -- [Environments and deployments](environments.md): Separate your jobs into - environments and use them for different purposes like testing, building and - deploying -- [Job artifacts](../user/project/pipelines/job_artifacts.md) -- [Caching dependencies](caching/index.md) -- [Git submodules](git_submodules.md) - How to run your CI jobs when Git - submodules are involved -- [Pipelines for merge requests](merge_request_pipelines/index.md) -- [Use SSH keys in your build environment](ssh_keys/README.md) -- [Trigger pipelines through the GitLab API](triggers/README.md) -- [Trigger pipelines on a schedule](../user/project/pipelines/schedules.md) -- [Kubernetes clusters](../user/project/clusters/index.md) - Integrate one or - more Kubernetes clusters to your project -- [Interactive web terminal](interactive_web_terminal/index.md) - Open an interactive - web terminal to debug the running jobs +NOTE: **Note:** +Familiarity with [GitLab Runner](https://docs.gitlab.com/runner/) is useful because it is +responsible for running the jobs in your CI/CD pipeline. On GitLab.com, shared Runners are enabled +by default so you don't need to set up anything to get started. -## GitLab CI/CD for Docker +### Auto DevOps -Leverage the power of Docker to run your CI pipelines. +An alternative to manually configuring CI/CD, GitLab supports [Auto DevOps](../topics/autodevops/index.md), +which: -- [Use Docker images with GitLab Runner](docker/using_docker_images.md) -- [Use CI to build Docker images](docker/using_docker_build.md) -- [CI services (linked Docker containers)](services/README.md) -- Article (2016-03-01): [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) +- Provides simplified setup and execution of CI/CD. +- Allows GitLab to automatically detect, build, test, deploy, and monitor your applications. -## Review Apps +## Basic usage -- [Review Apps documentation](review_apps/index.md) -- Article (2016-11-22): [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/) -- [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) +With basic knowledge of how GitLab CI/CD works, the following documentation extends your knowledge +into more features: -## Auto DevOps +| Topic | Description | +|:-------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------| +| [CI/CD Variables](variables/README.md) | How environment variables can be configured and made available in pipelines. | +| [Where variables can be used](variables/where_variables_can_be_used.md) | A deeper look into where and how CI/CD variables can be used. | +| [User](../user/permissions.md#gitlab-ci) and [job](../user/permissions.md#job-permissions) permissions | Learn about the access levels a user can have for performing certain CI actions. | +| [Configuring GitLab Runners](runners/README.md) | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/). | -- [Auto DevOps](../topics/autodevops/index.md): Auto DevOps automatically detects, builds, tests, deploys, and monitors your applications. +## Advanced usage -## GitLab CI for GitLab Pages +Once you get familiar with the basics of GitLab CI/CD, consult the following documentation to make +use of advanced features: -See the documentation on [GitLab Pages](../user/project/pages/index.md). +| Topic | Description | +|:---------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------| +| [Introduction to environments and deployments](environments.md) | Learn how to separate your jobs into environments and use them for different purposes like testing, building and, deploying. | +| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Learn about the output of jobs. | +| [Cache dependencies in GitLab CI/CD](caching/index.md) | Discover how to speed up pipelines using caching. | +| [Using Git submodules with GitLab CI](git_submodules.md) | How to run your CI jobs when using Git submodules. | +| [Pipelines for merge requests](merge_request_pipelines/index.md) | Create pipelines specifically for merge requests. | +| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md) | Use SSH keys in your build environment. | +| [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. | +| [Pipeline schedules](../user/project/pipelines/schedules.md) | Trigger pipelines on a schedule. | +| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. | +| [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. | + +### GitLab Pages + +GitLab CI/CD can be used to build and host static websites. For more information, see the +documentation on [GitLab Pages](../user/project/pages/index.md). ## Examples -Check the [GitLab CI/CD examples](examples/README.md) for a collection of tutorials and guides on setting up your CI/CD pipeline for various programming languages, frameworks, -and operating systems. +Check out the [GitLab CI/CD examples](examples/README.md) for a collection of tutorials and guides on +setting up your CI/CD pipeline for various programming languages, frameworks, and operating systems. + +## Administration + +As a GitLab administrator, you can change the default behavior of GitLab CI/CD for: + +- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md). +- Specific projects, using [pipelines settings](../user/project/pipelines/settings.md). + +See also: + +- [How to enable or disable GitLab CI/CD](enable_or_disable_ci.md). +- Other [CI administration settings](../administration/index.md#continuous-integration-settings). + +## Using Docker + +Docker is commonly used with GitLab CI/CD. Learn more about how to to accomplish this with the following +documentation: + +| Topic | Description | +|:-------------------------------------------------------------------------|:-------------------------------------------------------------------------| +| [Using Docker images](docker/using_docker_images.md) | Use GitLab and GitLab Runner with Docker to build and test applications. | +| [Building Docker images with GitLab CI/CD](docker/using_docker_build.md) | Maintain Docker-based projects using GitLab CI/CD. | + +Related topics include: -## Integrations +- [Docker integration](docker/README.md). +- [CI services (linked Docker containers)](services/README.md). +- [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) (article). -- Article (2016-06-09): [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/) -- Article (2016-05-05): [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/) -- Article (2016-04-19): [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) +## Further resources -## Special configuration (GitLab admin) +This section provides further resources to help you get familiar with GitLab CI/CD. -As a GitLab administrator, you can change the default behavior of GitLab CI/CD in -your whole GitLab instance as well as in each project. +### Articles -- [Continuous Integration admin settings](../administration/index.md#continuous-integration-settings) -- **Project specific:** - - [Pipelines settings](../user/project/pipelines/settings.md) - - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) -- **Affecting the whole GitLab instance:** - - [Continuous Integration admin settings](../user/admin_area/settings/continuous_integration.md) +The following table provides a list of articles about CI/CD, sorted in reverse chronological order of publish date: + +| Publish Date | Article | +|:-------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2017-07-13 | [Making CI easier with GitLab](https://about.gitlab.com/2017/07/13/making-ci-easier-with-gitlab/). | +| 2017-05-22 | [Fast and natural continuous integration with GitLab CI](https://about.gitlab.com/2017/05/22/fast-and-natural-continuous-integration-with-gitlab-ci/). | +| 2016-11-22 | [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/). | +| 2016-08-26 | [GitLab CI: Deployment & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/). | +| 2016-08-05 | [Continuous Integration, Delivery, and Deployment with GitLab](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/). | +| 2016-07-29 | [GitLab CI: Run jobs sequentially, in parallel or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/). | +| 2016-06-09 | [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/) | +| 2016-05-23 | [GitLab Container Registry](https://about.gitlab.com/2016/05/23/gitlab-container-registry/). | +| 2016-05-05 | [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/) | +| 2016-04-19 | [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) | +| 2015-03-01 | [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/). | +| 2015-12-14 | [Getting started with GitLab and GitLab CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/). | + +### Videos + +The following table provides a list of videos about CI/CD, sorted in reverse chronological order of publish date: + +| Publish Date | Video | +|:-------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 2017-07-17 | [GitLab CI/CD Deep Dive](https://youtu.be/pBe4t1CD8Fc?t=195). | +| 2017-03-13 | [Demo: CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/). | +| 2016-04-20 | [Webcast Recording and Slides: Getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/). | + +In addition, the following third-party videos are available: + +- [Intégration continue avec GitLab (September 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s). +- [GitLab CI for Minecraft Plugins (July 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8). + +### Example Projects + +[`review-apps-nginx`](https://gitlab.com/gitlab-examples/review-apps-nginx/) provides an example of using Review Apps. + +Other example projects are available at the [`gitlab-examples`](https://gitlab.com/gitlab-examples) group. + +### Why GitLab CI/CD? + +The following articles explain reasons why you might use GitLab CI/CD for your CI/CD infrastructure: + +- [Why we chose GitLab CI for our CI/CD solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/). +- [Building our web-app on GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/). + +See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJaIOzCX4Vqg3dlwfELC3u2jEeCBbDk) presentation. ## Breaking changes -- [CI variables renaming for GitLab 9.0](variables/README.md#9-0-renaming) Read about the +As GitLab CI/CD has evolved, certain breaking changes have been necessary. These are: + +- [CI variables renaming for GitLab 9.0](variables/README.md#gitlab-90-renaming). Read about the deprecated CI variables and what you should use for GitLab 9.0+. -- [New CI job permissions model](../user/project/new_ci_build_permissions_model.md) - Read about what changed in GitLab 8.12 and how that affects your jobs. +- [New CI job permissions model](../user/project/new_ci_build_permissions_model.md). + See what changed in GitLab 8.12 and how that affects your jobs. There's a new way to access your Git submodules and LFS objects in jobs. diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 8b2ce425cf5..dbe3d9b62c9 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -46,7 +46,6 @@ needed to compile the project: with stages and shared artifacts before investing time in changes to the setup. - It's sometimes confusing because the name artifact sounds like something that is only useful outside of the job, like for downloading a final image. But artifacts are also available in between stages within a pipeline. So if you diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md index 8ae80b2bc02..446f5b54f0c 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -4,6 +4,8 @@ comments: false # Docker integration -- [Using Docker Images](using_docker_images.md) -- [Using Docker Build](using_docker_build.md) -- [Using kaniko](using_kaniko.md) +The following documentation is available for using GitLab CI/CD with Docker: + +- [Using Docker images](using_docker_images.md). +- [Building Docker images with GitLab CI/CD](using_docker_build.md). +- [Building images with kaniko and GitLab CI/CD](using_kaniko.md). diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index a8c119edaa0..87e86bef44b 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -40,6 +40,7 @@ There's also a collection of repositories with [example projects](https://gitlab ### Miscellaneous +- [End-to-end testing with GitLab CI/CD and WebdriverIO](end_to_end_testing_webdriverio/index.md) - [Using `dpl` as deployment tool](deployment/README.md) - [The `.gitlab-ci.yml` file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md index 6499413baf0..474a481836a 100644 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md +++ b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md @@ -112,7 +112,7 @@ on GitLab CI/CD. To set the environment variables, navigate to your project's  Once set up, GitLab CI/CD will deploy your app to CF at every push to your -repository's deafult branch. To see the build logs or watch your builds running +repository's default branch. To see the build logs or watch your builds running live, navigate to **CI/CD > Pipelines**. CAUTION: **Caution:** diff --git a/doc/ci/examples/deployment/composer-npm-deploy.md b/doc/ci/examples/deployment/composer-npm-deploy.md index 36358515b84..4758ccad5aa 100644 --- a/doc/ci/examples/deployment/composer-npm-deploy.md +++ b/doc/ci/examples/deployment/composer-npm-deploy.md @@ -4,7 +4,6 @@ This guide covers the building dependencies of a PHP project while compiling ass While is possible to create your own image with custom PHP and Node JS versions, for brevity, we will use an existing [Docker image](https://hub.docker.com/r/tetraweb/php/) that contains both PHP and NodeJS installed. - ```yaml image: tetraweb/php ``` diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png b/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png Binary files differnew file mode 100644 index 00000000000..c45d70d7f7a --- /dev/null +++ b/doc/ci/examples/end_to_end_testing_webdriverio/img/deployed_dependency_update.png diff --git a/doc/ci/examples/end_to_end_testing_webdriverio/index.md b/doc/ci/examples/end_to_end_testing_webdriverio/index.md new file mode 100644 index 00000000000..9f3b8d9ad14 --- /dev/null +++ b/doc/ci/examples/end_to_end_testing_webdriverio/index.md @@ -0,0 +1,251 @@ +--- +author: Vincent Tunru +author_gitlab: Vinnl +level: advanced +article_type: user guide +date: 2019-02-18 +description: 'Confidence checking your entire app every time a new feature is added can quickly become repetitive. Learn how to automate it with GitLab CI/CD.' +--- + +# End-to-end testing with GitLab CI/CD and WebdriverIO + +[Review Apps](../../review_apps/index.md) are great: for every merge request +(or branch, for that matter), the new code can be copied and deployed to a fresh production-like live +environment, making it incredibly low-effort to assess the impact of the changes. Thus, when we use a dependency manager like +[Dependencies.io](https://www.dependencies.io/), it can submit a merge request with an updated dependency, +and it will immediately be clear that the application can still be properly built and deployed. After all, you can _see_ it +running! + +<img src="img/deployed_dependency_update.png" alt="dependencies.io" class="image-noshadow"> + +However, looking at the freshly deployed code to check whether it still looks and behaves as +expected is repetitive manual work, which means it is a prime candidate for automation. This is +where automated [end-to-end testing](https://martinfowler.com/bliki/BroadStackTest.html) comes in: +having the computer run through a few simple scenarios that requires the proper functioning of all +layers of your application, from the frontend to the database. In this article, we will discuss how +to write such end-to-end tests, and how to set up GitLab CI/CD to automatically run these tests +against your new code, on a branch-by-branch basis. For the scope of this article, we will walk you +through the process of setting up GitLab CI/CD for end-to-end testing Javascript-based applications +with WebdriverIO, but the general strategy should carry over to other languages. +We assume you are familiar with GitLab, [GitLab CI/CD](../../README.md), [Review Apps](../../review_apps/index.md), and running your app locally, e.g., on `localhost:8000`. + +### What to test + +In the widely-used [testing pyramid strategy](https://martinfowler.com/bliki/TestPyramid.html), end-to-end tests act more like a +safeguard: [most of your code should be covered by +unit tests](https://vincenttunru.com/100-percent-coverage/) that allow you to easily identify the source of a problem, should one occur. Rather, you +will likely want to +[limit the number of end-to-end tests](https://testing.googleblog.com/2015/04/just-say-no-to-more-end-to-end-tests.html) +to just enough to give you the confidence that the deployment went as intended, that your +infrastructure is up and running, and that your units of code work well together. + +### Selenium and WebdriverIO + +[Selenium](http://www.seleniumhq.org/) is a piece of software that can control web browsers, e.g., to make them +visit a specific URL or interact with elements on the page. It can be programmatically controlled +from a variety of programming languages. In this article we're going to be using the +[WebdriverIO](http://webdriver.io/) Javascript bindings, but the general concept should carry over +pretty well to +[other programming languages supported by Selenium](http://docs.seleniumhq.org/about/platforms.jsp#programming-languages). + +## Writing tests + +You can write tests using +[several testing frameworks supported by WebdriverIO](http://webdriver.io/guide/testrunner/frameworks.html). +We will be using [Jasmine](https://jasmine.github.io/) here: + +```javascript +describe('A visitor without account', function(){ + it('should be able to navigate to the homepage from the 404 page', function(){ + browser.url('/page-that-does-not-exist'); + + expect(browser.getUrl()).toMatch('page-that-does-not-exist'); + + browser.element('.content a[href="/"]').click(); + + expect(browser.getUrl()).not.toMatch('page-that-does-not-exist'); + }); +}); +``` + +The functions `describe`, `it`, and `browser` are provided by WebdriverIO. Let's break them down one by one. + +The function `describe` allows you to group related tests. This can be useful if, for example, you want to +run the same initialization commands (using [`beforeEach`](https://jasmine.github.io/api/2.9/global.html#beforeEach)) for +multiple tests, such as making sure you are logged in. + +The function `it` defines an individual test. + +[The `browser` object](http://webdriver.io/guide/testrunner/browserobject.html) is WebdriverIO's +special sauce. It provides most of [the WebdriverIO API methods](http://webdriver.io/api.html) that are the key to +steering the browser. In this case, we can use +[`browser.url`](http://webdriver.io/api/protocol/url.html) to visit `/page-that-does-not-exist` to +hit our 404 page. We can then use [`browser.getUrl`](http://webdriver.io/api/property/getUrl.html) +to verify that the current page is indeed at the location we specified. To interact with the page, +we can simply pass CSS selectors to +[`browser.element`](http://webdriver.io/api/protocol/element.html) to get access to elements on the +page and to interact with them - for example, to click on the link back to the home page. + +The simple test shown above +can already give us a lot of confidence if it passes: we know our deployment has succeeded, that the +elements are visible on the page and that actual browsers can interact with it, and that routing +works as expected. And all that in just 10 lines with gratituous whitespace! Add to that succeeding +unit tests and a successfully completed pipeline, and you can be fairly confident that the +dependency upgrade did not break anything without even having to look at your website. + +## Running locally + +We'll get to running the above test in CI/CD in a moment. When writing tests, however, it helps if +you do not have to wait for your pipelines to succeed in order to check whether they do what you +expect them to do. In other words, let's get it to run locally. + +Make sure that your app is running locally. If you use Webpack, +you can use [the Webpack Dev Server WebdriverIO plugin](https://www.npmjs.com/package/wdio-webpack-dev-server-service) +that automatically starts a development server before executing the tests. + +The WebdriverIO documentation has +[an overview of all configuration options](http://webdriver.io/guide/getstarted/configuration.html), but the +easiest way to get started is to start with +[WebdriverIO's default configuration](http://webdriver.io/guide/testrunner/configurationfile.html), which +provides an overview of all available options. The two options that are going to be most relevant now are the +`specs` option, which is an array of paths to your tests, and the `baseUrl` option, which points to where your app is +running. And finally, we will need to tell WebdriverIO in which browsers we would like to run our +tests. This can be configured through the `capabilities` option, which is an array of browser names (e.g. +`firefox` or `chrome`). It is recommended to install +[selenium-assistant](https://googlechromelabs.github.io/selenium-assistant/) to detect all installed +browsers: + +```javascript + const seleniumAssistant = require('selenium-assistant'); + const browsers = seleniumAssistant.getLocalBrowsers(); + config.capabilities = browsers.map(browser => ({ browserName: browser.getId() })); +``` + +But of course, a simple configuration of `config.capabilities = ['firefox']` would work as well. + +If you've installed WebdriverIO as a dependency +(`npm install --save-dev webdriverio`), you can add a line to the `scripts` property in your +`package.json` that runs `wdio` with the path to your configuration file as value, e.g.: + +```javascript + "confidence-check": "wdio wdio.conf.js", +``` + +You can then execute the tests using `npm run confidence-check`, after which you will actually see a +new browser window interacting with your app as you specified. + +## Configuring GitLab CI/CD + +Which brings us to the exciting part: how do we run this in GitLab CI/CD? There are two things we +need to do for this: + +1. Set up [CI/CD jobs](../../yaml/README.md#jobs) that actually have a browser available. +2. Update our WebdriverIO configuration to use those browsers to visit the review apps. + +For the scope of this article, we've defined an additional [CI/CD stage](../../yaml/README.md#stages) +`confidence-check` that is executed _after_ the stage that deploys the review app. It uses the `node:latest` [Docker +image](../../docker/using_docker_images.html). However, WebdriverIO fires up actual browsers +to interact with your application, so we need to install and run them. +Furthermore, WebdriverIO uses Selenium as a common interface to control different browsers, +so we need to install and run Selenium as well. Luckily, the Selenium project provides the Docker images +[standalone-firefox](https://hub.docker.com/r/selenium/standalone-firefox/) and +[standalone-chrome](https://hub.docker.com/r/selenium/standalone-chrome/) that provide just that for +Firefox and Chrome, respectively. (Since Safari and Internet Explorer/Edge are not open source and +not available for Linux, we are unfortunately unable to use those in GitLab CI/CD). + +GitLab CI/CD makes it a breeze to link these images to our `confidence-check` jobs using the +`service` property, which makes the Selenium server available under a hostname based on the image +name. Our job configuration then looks something like this: + +```yaml +e2e:firefox: + stage: confidence-check + services: + - selenium/standalone-firefox + script: + - npm run confidence-check --host=selenium__standalone-firefox +``` + +And likewise for Chrome: + +```yaml +e2e:chrome: + stage: confidence-check + services: + - selenium/standalone-chrome + script: + - npm run confidence-check --host=selenium__standalone-chrome +``` + +Now that we have a job to run the end-to-end tests in, we need to tell WebdriverIO how to connect to +the Selenium servers running alongside it. We've already cheated a bit above by +passing the value of the [`host`](http://webdriver.io/guide/getstarted/configuration.html#host) +option as an argument to `npm run confidence-check` on the command line. +However, we still need to tell WebdriverIO which browser is available for it to use. + +[GitLab CI/CD makes +a number of variables available](../../variables/README.html#predefined-variables-environment-variables) +with information about the current CI job. We can use this information to dynamically set +up our WebdriverIO configuration according to the job that is running. More specifically, we can +tell WebdriverIO what browser to execute the test on depending on the name of the currently running +job. We can do so in WebdriverIO's configuration file, which we named `wdio.conf.js` above: + +```javascript +if(process.env.CI_JOB_NAME) { + dynamicConfig.capabilities = [ + { browserName: process.env.CI_JOB_NAME === 'e2e:chrome' ? 'chrome' : 'firefox' }, + ]; +} +``` + +Likewise, we can tell WebdriverIO where the review app is running - in this example's case, it's on +`<branch name>.flockademic.com`: + +```javascript +if(process.env.CI_COMMIT_REF_SLUG) { + dynamicConfig.baseUrl = `https://${process.env.CI_COMMIT_REF_SLUG}.flockademic.com`; +} +``` + +And we can make sure our local-specific configuration is only used when _not_ running in CI using +`if (!process.env.CI)`. That's basically all the ingredients you need to run your end-to-end tests +on GitLab CI/CD! + +To recap, our `.gitlab-ci.yml` configuration file looks something like this: + +```yaml +image: node:8.10 +stages: + - deploy + - confidence-check +deploy_terraform: + stage: deploy + script: + # Your Review App deployment scripts - for a working example please check https://gitlab.com/Flockademic/Flockademic/blob/5a45f1c2412e93810fab50e2dab8949e2d0633c7/.gitlab-ci.yml#L315 +e2e:firefox: + stage: confidence-check + services: + - selenium/standalone-firefox + script: + - npm run confidence-check --host=selenium__standalone-firefox +e2e:chrome: + stage: confidence-check + services: + - selenium/standalone-chrome + script: + - npm run confidence-check --host=selenium__standalone-chrome +``` + +## What's next + +If you are setting this up for yourself and want to peek at the working configuration of a +production project, see: + +- [Flockademic's `wdio.conf.js`](https://gitlab.com/Flockademic/Flockademic/blob/dev/wdio.conf.js) +- [Flockademic's `.gitlab-ci.yml`](https://gitlab.com/Flockademic/Flockademic/blob/dev/.gitlab-ci.yml) +- [Flockademic's tests](https://gitlab.com/Flockademic/Flockademic/tree/dev/__e2e__) + +There's plenty more that WebdriverIO can do. For example, you can configure a [`screenshotPath`](http://webdriver.io/guide/getstarted/configuration.html#screenshotPath) to tell WebdriverIO to take +a screenshot when tests are failing. Then tell GitLab CI/CD to store those +[artifacts](../../yaml/README.md#artifacts), and you'll be able to see what went +wrong within GitLab. diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index b1ccce744d8..d3b6650b0f4 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -68,7 +68,6 @@ Since we have our app up and running locally, it's time to push the codebase to Let's create [a new project](../../../gitlab-basics/create-project.md) in GitLab named `laravel-sample`. After that, follow the command line instructions displayed on the project's homepage to initiate the repository on our machine and push the first commit. - ```bash cd laravel-sample git init @@ -127,7 +126,6 @@ We'll use this variable in the `.gitlab-ci.yml` later, to easily connect to our We also need to add the public key to **Project** > **Settings** > **Repository** as a [Deploy Key](../../../ssh/README.md#deploy-keys), which gives us the ability to access our repository from the server through [SSH protocol](../../../gitlab-basics/command-line-commands.md#start-working-on-your-project). - ```bash # As the deployer user on the server # @@ -186,7 +184,6 @@ To use Envoy, we should first install it on our local machine [using the given i The pros of Envoy is that it doesn't require Blade engine, it just uses Blade syntax to define tasks. To start, we create an `Envoy.blade.php` in the root of our app with a simple task to test Envoy. - ```php @servers(['web' => 'remote_username@remote_host']) @@ -220,7 +217,6 @@ Our deployment plan is to clone the latest release from GitLab repository, insta The first step of our deployment process is to define a set of variables within [@setup](https://laravel.com/docs/envoy/#setup) directive. You may change the `app` to your application's name: - ```php ... @@ -246,7 +242,6 @@ You may change the `app` to your application's name: The [@story](https://laravel.com/docs/envoy/#stories) directive allows us define a list of tasks that can be run as a single task. Here we have three tasks called `clone_repository`, `run_composer`, `update_symlinks`. These variables are usable to making our task's codes more cleaner: - ```php ... @@ -618,7 +613,7 @@ Lastly, `when: manual` is used to turn the job from running automatically to a m deploy_production: script: - # Add the private SSH key to the build environment + # Add the private SSH key to the build environment - 'which ssh-agent || ( apt-get update -y && apt-get install openssh-client -y )' - eval $(ssh-agent -s) - ssh-add <(echo "$SSH_PRIVATE_KEY") diff --git a/doc/ci/examples/sast_docker.md b/doc/ci/examples/sast_docker.md index 9f4a63e296d..3a657b3a3d5 100644 --- a/doc/ci/examples/sast_docker.md +++ b/doc/ci/examples/sast_docker.md @@ -1 +1 @@ -This document was moved to [another location](./container_scanning.md).
\ No newline at end of file +This document was moved to [another location](./container_scanning.md). diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index bf1e61442d4..b7b5c660586 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -56,6 +56,49 @@ The same tag is shown on the pipeline's details:  +## Excluding certain jobs + +The behavior of the `only: merge_requests` rule is such that _only_ jobs with +that rule are run in the context of a merge request; no other jobs will be run. + +However, you may want to reverse this behaviour, having all of your jobs to run _except_ +for one or two. Consider the following pipeline, with jobs `A`, `B`, and `C`. If you want +all pipelines to always run `A` and `B`, but only want `C` to run for a merge request, +you can configure your `.gitlab-ci.yml` file as follows: + +``` yaml +.only-default: &only-default + only: + - master + - merge_requests + - tags + +A: + <<: *only-default + script: + - ... + +B: + <<: *only-default + script: + - ... + +C: + script: + - ... + only: + - merge_requests +``` + +Since `A` and `B` are getting the `only:` rule to execute in all cases, they will +always run. `C` specifies that it should only run for merge requests, so for any +pipeline except a merge request pipeline, it will not run. + +As you can see, this will help you avoid a lot of boilerplate where you'd need +to add that `only:` rule to all of your jobs in order to make them always run. You +can use this for scenarios like having only pipelines with merge requests get a +Review App set up, helping to save resources. + ## Important notes about merge requests from forked projects Note that the current behavior is subject to change. In the usual contribution diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index c742dc61368..ce55b231666 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -240,21 +240,64 @@ shared Runners will [only run the jobs they are equipped to run](../yaml/README. For instance, at GitLab we have Runners tagged with "rails" if they contain the appropriate dependencies to run Rails test suites. -### Preventing Runners with tags from picking jobs without tags +### Allowing Runners with tags to pick jobs without tags -You can configure a Runner to prevent it from picking -[jobs with tags](../yaml/README.md#tags) when the Runner does not have tags -assigned. This setting can be enabled the first -time you [register a Runner][register] and can be changed afterwards under -each Runner's settings. +When you [register a Runner][register], its default behavior is to **only pick** +[tagged jobs](../yaml/README.md#tags). -To make a Runner pick tagged/untagged jobs: +NOTE: **Note:** +Maintainer [permissions](../../user/permissions.md) are required to change the +Runner settings. -1. Visit your project's **Settings âž” CI/CD** -1. Find the Runner you wish and make sure it's enabled -1. Click the pencil button -1. Check the **Run untagged jobs** option -1. Click **Save changes** for the changes to take effect +To make a Runner pick untagged jobs: + +1. Visit your project's **Settings > CI/CD > Runners**. +1. Find the Runner you want to pick untagged jobs and make sure it's enabled. +1. Click the pencil button. +1. Check the **Run untagged jobs** option. +1. Click the **Save changes** button for the changes to take effect. + +NOTE: **Note:** +The Runner tags list can not be empty when it's not allowed to pick untagged jobs. + +Below are some example scenarios of different variations. + +#### Runner runs only tagged jobs + +The following examples illustrate the potential impact of the Runner being set +to run only tagged jobs. + +Example 1: + +1. The Runner is configured to run only tagged jobs and has the `docker` tag. +1. A job that has a `hello` tag is executed and stuck. + +Example 2: + +1. The Runner is configured to run only tagged jobs and has the `docker` tag. +1. A job that has a `docker` tag is executed and run. + +Example 3: + +1. The Runner is configured to run only tagged jobs and has the `docker` tag. +1. A job that has no tags defined is executed and stuck. + +#### Runner is allowed to run untagged jobs + +The following examples illustrate the potential impact of the Runner being set +to run tagged and untagged jobs. + +Example 1: + +1. The Runner is configured to run untagged jobs and has the `docker` tag. +1. A job that has no tags defined is executed and run. +1. A second job that has a `docker` tag defined is executed and run. + +Example 2: + +1. The Runner is configured to run untagged jobs and has no tags defined. +1. A job that has no tags defined is executed and run. +1. A second job that has a `docker` tag defined is stuck. ### Setting maximum job timeout for a Runner diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 984878b6c9b..424be91773c 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1,7 +1,7 @@ -# Configuration of your jobs with .gitlab-ci.yml +# Configuration of your pipelines with .gitlab-ci.yml This document describes the usage of `.gitlab-ci.yml`, the file that is used by -GitLab Runner to manage your project's jobs. +GitLab Runner to manage your project's pipelines. From version 7.12, GitLab CI uses a [YAML](https://en.wikipedia.org/wiki/YAML) file (`.gitlab-ci.yml`) for the project configuration. It is placed in the root @@ -96,9 +96,9 @@ This can be an array or a multi-line string. jobs, including failed ones. This has to be an array or a multi-line string. The `before_script` and the main `script` are concatenated and run in a single context/container. -The `after_script` is run separately, so depending on the executor, changes done -outside of the working tree might not be visible, e.g. software installed in the -`before_script`. +The `after_script` is run separately. The current working directory is set back to +default. Depending on the executor, changes done outside of the working tree might +not be visible, e.g. software installed in the `before_script`. It's possible to overwrite the globally defined `before_script` and `after_script` if you set it per-job: @@ -423,10 +423,28 @@ connected with merge requests yet, and because GitLab is creating pipelines before an user can create a merge request we don't know a target branch at this point. -Without a target branch, it is not possible to know what the common ancestor is, -thus we always create a job in that case. This feature works best for stable -branches like `master` because in that case GitLab uses the previous commit -that is present in a branch to compare against the latest SHA that was pushed. +#### Using `changes` with `merge_requests` + +With [pipelines for merge requests](../merge_request_pipelines/index.md), +make it possible to define if a job should be created base on files modified +in a merge request. + +For example: + +``` +docker build service one: + script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . + only: + refs: + - merge_requests + changes: + - Dockerfile + - service-one/**/* +``` + +In the scenario above, if you create or update a merge request that changes +either files in `service-one` folder or `Dockerfile`, GitLab creates and triggers +the `docker build service one` job. ## `tags` diff --git a/doc/customization/help_message.md b/doc/customization/help_message.md new file mode 100644 index 00000000000..c2e592d03bf --- /dev/null +++ b/doc/customization/help_message.md @@ -0,0 +1,13 @@ +# GitLab Help custom text + +In larger organizations it is useful to have information about who has the responsibility of maintaining the company GitLab server. + +1. Navigate to the admin area, click on **Preferences** and expand **Help page**. + +1. Under **Help text** fill in the required information about the person(s) administering GitLab or any other information relevant to your needs. + +  + +1. After saving the page this information will be shown on the GitLab login page and on the GitLab `/help` page (e.g., <https://gitlab.com/help>). + +  diff --git a/doc/customization/help_message/help_text.png b/doc/customization/help_message/help_text.png Binary files differnew file mode 100644 index 00000000000..99697a106bf --- /dev/null +++ b/doc/customization/help_message/help_text.png diff --git a/doc/customization/help_message/help_text_on_help_page.png b/doc/customization/help_message/help_text_on_help_page.png Binary files differnew file mode 100644 index 00000000000..288b4b8c1eb --- /dev/null +++ b/doc/customization/help_message/help_text_on_help_page.png diff --git a/doc/customization/index.md b/doc/customization/index.md new file mode 100644 index 00000000000..71e87b3f111 --- /dev/null +++ b/doc/customization/index.md @@ -0,0 +1,18 @@ +--- +description: Learn how to customize GitLab's appearance for self-managed installations. +--- + +# Customizing GitLab's appearance **[CORE ONLY]** + +For GitLab self-managed instances, it's possible to customize +a few pages. + +Read through the following documents to adjust GitLab's +look and feel to meet your needs: + +- [Custom login page](branded_login_page.md) +- [Custom header and email logo](branded_page_and_email_header.md) +- [Custom favicon](favicon.md) +- [Libravatar](libravatar.md) +- [New project page](new_project_page.md) +- [Custom `/help` message](help_message.md)
\ No newline at end of file diff --git a/doc/customization/libravatar.md b/doc/customization/libravatar.md index 9bd22d3966d..18aaeb5a712 100644 --- a/doc/customization/libravatar.md +++ b/doc/customization/libravatar.md @@ -38,7 +38,6 @@ For example, you host a service on `http://libravatar.example.com` the `plain_ur `http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon` - ## Omnibus-gitlab example In `/etc/gitlab/gitlab.rb`: @@ -57,10 +56,8 @@ gitlab_rails['gravatar_enabled'] = true gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon" ``` - Run `sudo gitlab-ctl reconfigure` for changes to take effect. - ## Default URL for missing images [Libravatar supports different sets](https://wiki.libravatar.org/api/) of `missing images` for emails not found on the Libravatar service. @@ -68,7 +65,6 @@ Run `sudo gitlab-ctl reconfigure` for changes to take effect. In order to use a different set other than `identicon`, replace `&d=identicon` portion of the URL with another supported set. For example, you can use `retro` set in which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"` - ## Usage examples #### For Microsoft Office 365 diff --git a/doc/customization/welcome_message.md b/doc/customization/welcome_message.md index 0aef0bf5abb..9194f847cdf 100644 --- a/doc/customization/welcome_message.md +++ b/doc/customization/welcome_message.md @@ -1,12 +1 @@ -# Customize the complete sign-in page - -Please see [Branded login page](branded_login_page.md) - -# Add a welcome message to the sign-in page (GitLab Community Edition) - -It is possible to add a markdown-formatted welcome message to your GitLab -sign-in page. Users of GitLab Enterprise Edition should use the [branded login -page feature](branded_login_page.md) instead. - -The welcome message (extra_sign_in_text) can now be set/changed in the Admin UI. -Admin area > Settings +This document was moved to [another location](branded_login_page.md). diff --git a/doc/development/README.md b/doc/development/README.md index d5829e31343..13646cbfe48 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -49,6 +49,7 @@ description: 'Learn how to contribute to GitLab.' - [Working with the GitHub importer](github_importer.md) - [Import/Export development documentation](import_export.md) - [Working with Merge Request diffs](diffs.md) +- [Kubernetes integration guidelines](kubernetes.md) - [Permissions](permissions.md) - [Prometheus metrics](prometheus_metrics.md) - [Guidelines for reusing abstractions](reusing_abstractions.md) diff --git a/doc/development/architecture.md b/doc/development/architecture.md index e65c5f05505..63574b28edc 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -35,7 +35,7 @@ run: redis: (pid 30560) 14274s; run: log: (pid 13807) 2432047s run: redis-exporter: (pid 30946) 14205s; run: log: (pid 13869) 2432045s run: sidekiq: (pid 30953) 14205s; run: log: (pid 13810) 2432047s run: unicorn: (pid 30960) 14204s; run: log: (pid 13809) 2432047s -``` +``` ### Layers @@ -51,11 +51,11 @@ GitLab can be considered to have two layers from a process perspective: - Omnibus configuration options - Layer: Monitoring -[Alert manager](https://prometheus.io/docs/alerting/alertmanager/) is a tool provided by prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue gitlab-ce#45740](https://gitlab.com/gitlab-org/gitlab-ce/issues/45740) about what we will be alerting on. +[Alert manager](https://prometheus.io/docs/alerting/alertmanager/) is a tool provided by prometheus that _"handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integration such as email, PagerDuty, or OpsGenie. It also takes care of silencing and inhibition of alerts."_ You can read more in [issue gitlab-ce#45740](https://gitlab.com/gitlab-org/gitlab-ce/issues/45740) about what we will be alerting on. ### gitaly -- [Omnibus configuration options](https://gitlab.com/gitlab-org/gitaly/tree/master/doc/configuration) +- [Omnibus configuration options](https://gitlab.com/gitlab-org/gitaly/tree/master/doc/configuration) - Layer: Core Service (Data) Gitaly is a service designed by GitLab to remove our need for NFS for Git storage in distributed deployments of GitLab. (Think GitLab.com or High Availablity Deployments) As of 11.3.0, This service handles all Git level access in GitLab. You can read more about the project [in the project's readme](https://gitlab.com/gitlab-org/gitaly). @@ -63,7 +63,7 @@ Gitaly is a service designed by GitLab to remove our need for NFS for Git storag ### gitlab-monitor - Omnibus configuration options -- Layer: Monitoring +- Layer: Monitoring GitLab Monitor is a process disigned in house that allows us to export metrics about GitLab application internals to prometheus. You can read more [in the project's readme](https://gitlab.com/gitlab-org/gitlab-monitor) @@ -100,14 +100,14 @@ Nginx as an ingress port for all HTTP requests and routes them to the approriate - [Omnibus configuration options](https://docs.gitlab.com/ee/administration/monitoring/prometheus/postgres_exporter.html) - Layer: Monitoring -[Postgres-exporter](https://github.com/wrouesnel/postgres_exporter) is the community provided Prometheus exporter that will deliver data about Postgres to prometheus for use in Grafana Dashboards. +[Postgres-exporter](https://github.com/wrouesnel/postgres_exporter) is the community provided Prometheus exporter that will deliver data about Postgres to prometheus for use in Grafana Dashboards. ### postgresql - [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/database.html) - Layer: Core Service (Data) -GitLab packages the popular Database to provide storage for Application meta data and user information. +GitLab packages the popular Database to provide storage for Application meta data and user information. ### prometheus @@ -121,11 +121,11 @@ Prometheus is a time-series tool that helps GitLab administrators expose metrics - [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/redis.html) - Layer: Core Service (Data) -Redis is packaged to provide a place to store: +Redis is packaged to provide a place to store: - session data - temporary cache information -- background job queues. +- background job queues. ### redis-exporter @@ -146,7 +146,7 @@ Sidekiq is a Ruby background job processor that pulls jobs from the redis queue - [Omnibus configuration options](https://docs.gitlab.com/omnibus/settings/unicorn.html) - Layer: Core Service (Processor) -[Unicorn](https://bogomips.org/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. +[Unicorn](https://bogomips.org/unicorn/) is a Ruby application server that is used to run the core Rails Application that provides the user facing features in GitLab. Often process output you will see this as `bundle` or `config.ru` depending on the GitLab version. ### Additional Processes @@ -176,7 +176,6 @@ When making a request to an HTTP Endpoint (Think `/users/sign_in`) the request w - unicorn - Since this is a web request, and it needs to access the application it will go to Unicorn. - Postgres/Gitaly/Redis - Depending on the type of request, it may hit these services to store or retreive data. - ### GitLab Git Request Cycle Below we describe the different pathing that HTTP vs. SSH Git requests will take. There is some overlap with the Web Request Cycle but also some differences. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 25ea2211b64..1b591c7c322 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -23,6 +23,11 @@ one of the [Merge request coaches][team]. If you need assistance with security scans or comments, feel free to include the Security Team (`@gitlab-com/gl-security`) in the review. +The `danger-review` CI job will randomly pick a reviewer and a maintainer for +each area of the codebase that your merge request seems to touch. It only makes +recommendations - feel free to override it if you think someone else is a better +fit! + Depending on the areas your merge request touches, it must be **approved** by one or more [maintainers](https://about.gitlab.com/handbook/engineering/workflow/code-review/#maintainer): @@ -132,6 +137,14 @@ If a developer who happens to also be a maintainer was involved in a merge reque as a domain expert and/or reviewer, it is recommended that they are not also picked as the maintainer to ultimately approve and merge it. +Try to review in a timely manner; doing so allows everyone involved in the merge +request to iterate faster as the context is fresh in memory. Further, this +improves contributors' experiences significantly. Reviewers should aim to review +within two working days from the date they were assigned the merge request. If +you don't think you'll be able to review a merge request within that time, let +the author know as soon as possible. When the author of the merge request has not +heard anything after two days, a new reviewer should be assigned. + Maintainers should check before merging if the merge request is approved by the required approvers. diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 19b6181c9a2..4e766f37871 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -89,6 +89,11 @@ request is as follows: 1. If your merge request introduces changes that require additional steps when installing GitLab from source, add them to `doc/install/installation.md` in the same merge request. +1. If your merge request introduces changes that require additional steps when + upgrading GitLab from source, add them to + `doc/update/upgrading_from_source.md` in the same merge request. If these + instructions are specific to a version, add them to the "Version specific + upgrading instructions" section. Please keep the change in a single MR **as small as possible**. If you want to contribute a large feature think very hard what the minimum viable change is. diff --git a/doc/development/database_debugging.md b/doc/development/database_debugging.md index b2c804b2ff0..f00c5ccb9e9 100644 --- a/doc/development/database_debugging.md +++ b/doc/development/database_debugging.md @@ -13,7 +13,6 @@ Available `RAILS_ENV` - `development` (this is your main GDK db) - `test` (used for tests like rspec) - ## Nuke everything and start over If you just want to delete everything and start over with an empty DB (~1 minute): @@ -36,7 +35,6 @@ If your test DB is giving you problems, it is safe to nuke it because it doesn't - `bundle exec rake db:migrate:up VERSION=20170926203418 RAILS_ENV=development`: Set up a migration - `bundle exec rake db:migrate:redo VERSION=20170926203418 RAILS_ENV=development`: Re-run a specific migration - ## Manually access the database Access the database via one of these commands (they all get you to the same place) @@ -54,7 +52,6 @@ bundle exec rails db RAILS_ENV=development - `SELECT * FROM schema_migrations WHERE version = '20170926203418';`: Check if a migration was run - `DELETE FROM schema_migrations WHERE version = '20170926203418';`: Manually remove a migration - ## FAQ ### `ActiveRecord::PendingMigrationError` with Spring diff --git a/doc/development/diffs.md b/doc/development/diffs.md index 43fc125c21d..56e869c21f8 100644 --- a/doc/development/diffs.md +++ b/doc/development/diffs.md @@ -59,28 +59,24 @@ Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] = Gitlab::Git::Di File diffs will be collapsed (but be expandable) if 100 files have already been rendered. - ```ruby Gitlab::Git::DiffCollection.collection_limits[:safe_max_lines] = Gitlab::Git::DiffCollection::DEFAULT_LIMITS[:max_lines] = 5000 ``` File diffs will be collapsed (but be expandable) if 5000 lines have already been rendered. - ```ruby Gitlab::Git::DiffCollection.collection_limits[:safe_max_bytes] = Gitlab::Git::DiffCollection.collection_limits[:safe_max_files] * 5.kilobytes = 500.kilobytes ``` File diffs will be collapsed (but be expandable) if 500 kilobytes have already been rendered. - ```ruby Gitlab::Git::DiffCollection.collection_limits[:max_files] = Commit::DIFF_HARD_LIMIT_FILES = 1000 ``` No more files will be rendered at all if 1000 files have already been rendered. - ```ruby Gitlab::Git::DiffCollection.collection_limits[:max_lines] = Commit::DIFF_HARD_LIMIT_LINES = 50000 ``` @@ -129,4 +125,3 @@ Diff Viewers, which can be found on `models/diff_viewer/*` are classes used to m whether it's a binary, which partial should be used to render it or which File extensions this class accounts for. `DiffViewer::Base` validates _blobs_ (old and new versions) content, extension and file type in order to check if it can be rendered. - diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index aac98c6ee7f..287a472d0d8 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -12,7 +12,7 @@ In addition to this page, the following resources to help craft and contribute d - [Structure and template](structure.md) - Learn the typical parts of a doc page and how to write each one. - [Workflow](workflow.md) - A landing page for our key workflows: - [Feature-change documentation workflow](feature-change-workflow.md) - Adding required documentation when developing a GitLab feature. - - [Documentation improvement worflow](improvement-workflow.md) - New content not associated with a new feature. + - [Documentation improvement workflow](improvement-workflow.md) - New content not associated with a new feature. - [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. - [Site architecture](site_architecture/index.md) - How docs.gitlab.com is built. diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index 62ca7d6c805..0aa3c41a225 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -234,7 +234,7 @@ Examples: ```yaml - category_title: Issues category_url: 'user/project/issues/' - # note that the above URL does not start with a slash and + # note that the above URL does not start with a slash and # does not include index.html at the end docs: @@ -295,7 +295,6 @@ On the other hand, if the user is looking at `/ce/` docs, all the links in the CE nav should link internally to `/ce/` files, except for [`ee-only` docs](#ee-only-docs). - ```html <% if dir != 'ce' %> <a href="/ee/<%= sec[:section_url] %>">...</a> diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index cda66447c2c..7a3a8f25c2d 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -112,7 +112,7 @@ table_display_block: true ## Emphasis - Use double asterisks (`**`) to mark a word or text in bold (`**bold**`). -- Use undescore (`_`) for text in italics (`_italic_`). +- Use underscore (`_`) for text in italics (`_italic_`). - Use greater than (`>`) for blockquotes. ## Punctuation diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index e0985922443..3e85c0e1995 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -831,6 +831,29 @@ should remain working as-is when EE is running without a license. Instead place EE specs in the `ee/spec` folder. +### Code in `spec/factories` + +Use `FactoryBot.modify` to extend factories already defined in CE. + +Note that you cannot define new factories (even nested ones) inside the `FactoryBot.modify` block. You can do so in a +separate `FactoryBot.define` block as shown in the example below: + +```ruby +# ee/spec/factories/notes.rb +FactoryBot.modify do + factory :note do + trait :on_epic do + noteable { create(:epic) } + project nil + end + end +end + +FactoryBot.define do + factory :note_on_epic, parent: :note, traits: [:on_epic] +end +``` + ## JavaScript code in `assets/javascripts/` To separate EE-specific JS-files we should also move the files into an `ee` folder. diff --git a/doc/development/fe_guide/accessibility.md b/doc/development/fe_guide/accessibility.md index 366b220cbb2..df32242a522 100644 --- a/doc/development/fe_guide/accessibility.md +++ b/doc/development/fe_guide/accessibility.md @@ -8,6 +8,5 @@ are useful for testing for potential accessibility problems in GitLab. Accessibility best-practices and more in-depth information is available on [the Audit Rules page][audit-rules] for the Chrome Accessibility Developer Tools. - [chrome-accessibility-developer-tools]: https://github.com/GoogleChrome/accessibility-developer-tools [audit-rules]: https://github.com/GoogleChrome/accessibility-developer-tools/wiki/Audit-Rules diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index e05887a19af..0342d16a87c 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -74,5 +74,4 @@ new Foo({ container: '.my-element' }); ``` You can find an example of the above in this [class][container-class-example]; - [container-class-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/mini_pipeline_graph_dropdown.js diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md index e6aa0be671f..2f8c79abde1 100644 --- a/doc/development/fe_guide/droplab/droplab.md +++ b/doc/development/fe_guide/droplab/droplab.md @@ -90,7 +90,6 @@ const list = document.getElementById('list'); droplab.addHook(trigger, list); ``` - ### Dynamic data Adding `data-dynamic` to your dropdown element will enable dynamic list rendering. diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md index 8e28a41f32e..e229103e462 100644 --- a/doc/development/fe_guide/droplab/plugins/input_setter.md +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -13,7 +13,6 @@ to update the `input` element with. You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements. - ```html <input id="input" value=""> <div id="div" data-selected-id=""></div> diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index 3a3cb77f592..86b8972a69e 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -1,7 +1,7 @@ # Frontend Development Guidelines > **Notice:** -We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md) +> We are currently in the process of re-writing our development guide to make it easier to find information. The new guide is still WIP but viewable in [development/new_fe_guide](../new_fe_guide/index.md) This document describes various guidelines to ensure consistency and quality across GitLab's frontend team. @@ -32,32 +32,41 @@ For our currently-supported browsers, see our [requirements][requirements]. --- ## [Development Process](development_process.md) + How we plan and execute the work on the frontend. ## [Architecture](architecture.md) + How we go about making fundamental design decisions in GitLab's frontend team or make changes to our frontend development guidelines. ## [Testing](../testing_guide/frontend_testing.md) + How we write frontend tests, run the GitLab test suite, and debug test related issues. ## [Design Patterns](design_patterns.md) + Common JavaScript design patterns in GitLab's codebase. ## [Vue.js Best Practices](vue.md) + Vue specific design patterns and practices. ## [Vuex](vuex.md) + Vuex specific design patterns and practices. ## [Axios](axios.md) + Axios specific practices and gotchas. ## [GraphQL](graphql.md) + How to use GraphQL ## [Icons and Illustrations](icons.md) + How we use SVG for our Icons and Illustrations. ## [Components](components.md) @@ -70,7 +79,7 @@ How we use UI components. ### [JavaScript Style Guide](style_guide_js.md) -We use eslint to enforce our JavaScript style guides. Our guide is based on +We use eslint to enforce our JavaScript style guides. Our guide is based on the excellent [Airbnb][airbnb-js-style-guide] style guide with a few small changes. @@ -81,23 +90,26 @@ Our SCSS conventions which are enforced through [scss-lint][scss-lint]. --- ## [Performance](performance.md) + Best practices for monitoring and maximizing frontend performance. --- ## [Security](security.md) + Frontend security practices. --- ## [Accessibility](accessibility.md) + Our accessibility standards and resources. ## [Internationalization (i18n) and Translations](../i18n/externalization.md) + Frontend internationalization support is described in [this document](../i18n/). The [externalization part of the guide](../i18n/externalization.md) explains the helpers/methods available. - [rails]: http://rubyonrails.org/ [haml]: http://haml.info/ [hamlit]: https://github.com/k0kubun/hamlit @@ -116,6 +128,7 @@ The [externalization part of the guide](../i18n/externalization.md) explains the --- ## [DropLab](droplab/droplab.md) + Our internal `DropLab` dropdown library. - [DropLab](droplab/droplab.md) diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index e5a383c25f5..0aba38aca8c 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -169,7 +169,6 @@ General tips: - [Profiling with Chrome DevTools][google-devtools-profiling] - [Browser Diet][browser-diet] is a community-built guide that catalogues practical tips for improving web page performance. - [web-page-test]: http://www.webpagetest.org/ [pagespeed-insights]: https://developers.google.com/speed/pagespeed/insights/ [google-devtools-profiling]: https://developers.google.com/web/tools/chrome-devtools/profile/?hl=en diff --git a/doc/development/fe_guide/security.md b/doc/development/fe_guide/security.md index 19e72c1d368..83bb449e54d 100644 --- a/doc/development/fe_guide/security.md +++ b/doc/development/fe_guide/security.md @@ -77,7 +77,6 @@ Inline styles should be avoided in almost all cases, they should only be used when no alternatives can be found. This allows reusability of styles as well as readability. - [observatory-cli]: https://github.com/mozilla/http-observatory-cli [qualys-ssl]: https://www.ssllabs.com/ssltest/analyze.html [secure_headers]: https://github.com/twitter/secureheaders diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 9c614e3468a..60f322c6e75 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -229,7 +229,6 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's - Vuex code follows the [documented pattern](./vuex.md#actions-pattern-request-and-receive-namespaces) - Knowledge about the existing Vue and Vuex applications and existing reusable components - [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards [environments-table]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/environments diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index b6161cd6163..67356a12eba 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -124,4 +124,3 @@ Feature.enable(:feature_flag_name) ## Enabling a feature flag (in production) Check how to [roll out changes using feature flags](rolling_out_changes_using_feature_flags.md). - diff --git a/doc/development/file_storage.md b/doc/development/file_storage.md index 597812c8c49..18e4dc2ca0c 100644 --- a/doc/development/file_storage.md +++ b/doc/development/file_storage.md @@ -20,7 +20,6 @@ There are many places where file uploading is used, according to contexts: - LFS Objects - Merge request diffs - ## Disk storage GitLab started saving everything on local disk. While directory location changed from previous versions, diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index ac910e80a89..6054873cb46 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -85,7 +85,7 @@ are very appreciative of the work done by translators and proofreaders! - Spanish - Pedro Garcia - [GitLab](https://gitlab.com/pedgarrod), [Crowdin](https://crowdin.com/profile/breaking_pitt) - Turkish - - Proofreaders needed. + - Ali Demirtaş - [GitLab](https://gitlab.com/alidemirtas), [Crowdin](https://crowdin.com/profile/alidemirtas) - Ukrainian - Volodymyr Sobotovych - [GitLab](https://gitlab.com/wheleph), [Crowdin](https://crowdin.com/profile/wheleph) - Andrew Vityuk - [GitLab](https://gitlab.com/3_1_3_u), [Crowdin](https://crowdin.com/profile/andruwa13) diff --git a/doc/development/import_export.md b/doc/development/import_export.md index 71db1abb201..e2108605d54 100644 --- a/doc/development/import_export.md +++ b/doc/development/import_export.md @@ -60,12 +60,12 @@ class StuckImportJobsWorker Marked stuck import jobs as failed. JIDs: xyz ``` -``` +``` +-----------+ +-----------------------------------+ |Export Job |--->| Calls ActiveRecord `as_json` and | +-----------+ | `to_json` on all project models | +-----------------------------------+ - + +-----------+ +-----------------------------------+ |Import Job |--->| Loads all JSON in memory, then | +-----------+ | inserts into the DB in batches | @@ -109,13 +109,13 @@ The `AttributeCleaner` removes any prohibited keys: # Removes all `_ids` and other prohibited keys class AttributeCleaner ALLOWED_REFERENCES = RelationFactory::PROJECT_REFERENCES + RelationFactory::USER_REFERENCES + ['group_id'] - + def clean @relation_hash.reject do |key, _value| prohibited_key?(key) || !@relation_class.attribute_method?(key) || excluded_key?(key) end.except('id') end - + ... ``` @@ -133,7 +133,7 @@ The `AttributeConfigurationSpec` checks and confirms the addition of new columns SAFE_MODEL_ATTRIBUTES: #{File.expand_path(safe_attributes_file)} IMPORT_EXPORT_CONFIG: #{Gitlab::ImportExport.config_file} -MSG +MSG ``` The `ModelConfigurationSpec` checks and confirms the addition of new models: @@ -157,7 +157,7 @@ The `ExportFileSpec` detects encrypted or sensitive columns: ```ruby # ExportFileSpec <<-MSG - Found a new sensitive word <#{key_found}>, which is part of the hash #{parent.inspect} + Found a new sensitive word <#{key_found}>, which is part of the hash #{parent.inspect} If you think this information shouldn't get exported, please exclude the model or attribute in IMPORT_EXPORT_CONFIG. @@ -214,7 +214,6 @@ We do not need to bump the version up in any of the following cases: - Remove a column or model (unless there is a DB constraint) - Export new things (such as a new type of upload) - Every time we bump the version, the integration specs will fail and can be fixed with: ```bash @@ -231,7 +230,7 @@ meaning that we want to bump the version up in the next version (or patch releas For example: 1. Add rename to `RelationRenameService` in X.Y -2. Remove it from `RelationRenameService` in X.Y + 1 +2. Remove it from `RelationRenameService` in X.Y + 1 3. Bump Import/Export version in X.Y + 1 ```ruby @@ -270,8 +269,8 @@ included_attributes: user: - :id - :email - ... - + ... + ``` Do not include the following attributes for the models specified: @@ -319,7 +318,7 @@ module Gitlab ensure remove_import_file end - + def restorers [repo_restorer, wiki_restorer, project_tree, avatar_restorer, uploads_restorer, lfs_restorer, statistics_restorer] @@ -346,7 +345,7 @@ module Projects end def save_services - [version_saver, avatar_saver, project_tree_saver, uploads_saver, repo_saver, + [version_saver, avatar_saver, project_tree_saver, uploads_saver, repo_saver, wiki_repo_saver, lfs_saver].all?(&:save) end ``` diff --git a/doc/development/kubernetes.md b/doc/development/kubernetes.md new file mode 100644 index 00000000000..4b2d48903ac --- /dev/null +++ b/doc/development/kubernetes.md @@ -0,0 +1,126 @@ +# Kubernetes integration - development guidelines + +This document provides various guidelines when developing for GitLab's +[Kubernetes integration](../user/project/clusters/index.md). + +## Development + +### Architecture + +Some Kubernetes operations, such as creating restricted project +namespaces are performed on the GitLab Rails application. These +operations are performed using a [client library](#client-library). +These operations will carry an element of risk as the operations will be +run as the same user running the GitLab Rails application, see the +[security](#security) section below. + +Some Kubernetes operations, such as installing cluster applications are +performed on one-off pods on the Kubernetes cluster itself. These +installation pods are currently named `install-<application_name>` and +are created within the `gitlab-managed-apps` namespace. + +In terms of code organization, we generally add objects that represent +Kubernetes resources in +[`lib/gitlab/kubernetes`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/lib/gitlab/kubernetes). + +### Client library + +We use the [`kubeclient`](https://rubygems.org/gems/kubeclient) gem to +perform Kubernetes API calls. As the `kubeclient` gem does not support +different API Groups (e.g. `apis/rbac.authorization.k8s.io`) from a +single client, we have created a wrapper class, +[`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/kubernetes/kube_client.rb) +that will enable you to achieve this. + +Selected Kubernetes API groups are currently supported. Do add support +for new API groups or methods to +[`Gitlab::Kubernetes::KubeClient`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/kubernetes/kube_client.rb) +if you need to use them. New API groups or API group versions can be +added to `SUPPORTED_API_GROUPS` - internally, this will create an +internal client for that group. New methods can be added as a delegation +to the relevant internal client. + +### Performance considerations + +All calls to the Kubernetes API must be in a background process. Do not +perform Kubernetes API calls within a web request as this will block +unicorn and can easily lead to a Denial Of Service (DoS) attack in GitLab as +the Kubernetes cluster response times are outside of our control. + +The easiest way to ensure your calls happen a background process is to +delegate any such work to happen in a [sidekiq +worker](sidekiq_style_guide.md). + +There are instances where you would like to make calls to Kubernetes and +return the response and as such a background worker does not seem to be +a good fit. For such cases you should make use of [reactive +caching](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/models/concerns/reactive_caching.rb). +For example: + +```ruby + def calculate_reactive_cache! + { pods: cluster.platform_kubernetes.kubeclient.get_pods } + end + + def pods + with_reactive_cache do |data| + data[:pods] + end + end +``` + +### Testing + +We have some Webmock stubs in +[`KubernetesHelpers`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/support/helpers/kubernetes_helpers.rb) +which can help with mocking out calls to Kubernetes API in your tests. + +## Security + +### SSRF + +As URLs for Kubernetes clusters are user controlled it is easily +susceptible to Server Side Request Forgery (SSRF) attacks. You should +understand the mitigation strategies if you are adding more API calls to +a cluster. + +Mitigation strategies include: + +1. Not allowing redirects to attacker controller resources: + [`Kubeclient::KubeClient`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/kubernetes/kube_client.rb#) + can be configured to disallow any redirects by passing in + `http_max_redirects: 0` as an option. +1. Not exposing error messages: by doing so, we + prevent attackers from triggering errors to expose results from + attacker controlled requests. For example, we do not expose (or store) + raw error messages: + + ```ruby + rescue Kubernetes::HttpError => e + # bad + # app.make_errored!("Kubernetes error: #{e.message}") + + # good + app.make_errored!("Kubernetes error: #{e.error_code}") + ``` + +## Debugging + +Logs related to the Kubernetes integration can be found in +[kubernetes.log](../administration/logs.md#kuberneteslog). On a local +GDK install, this will be present in `log/kubernetes.log`. + +Some services such as +[`Clusters::Applications::InstallService`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/services/clusters/applications/install_service.rb#L18) +rescues `StandardError` which can make it harder to debug issues in an +development environment. The current workaround is to temporarily +comment out the `rescue` in your local development source. + +You can also follow the installation pod logs to debug issues related to +installation. Once the installation/upgrade is underway, wait for the +pod to be created. Then run the following to obtain the pods logs as +they are written: + +```bash +kubectl logs <pod_name> --follow -n gitlab-managed-apps +``` diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 98b54684d39..bb40c0d32b4 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -48,7 +48,6 @@ various database operations, such as and whether they require downtime and how to work around that whenever possible. - ## Downtime Tagging Every migration must specify if it requires downtime or not, and if it should diff --git a/doc/development/new_fe_guide/development/testing.md b/doc/development/new_fe_guide/development/testing.md index d74f141f08f..8441089418e 100644 --- a/doc/development/new_fe_guide/development/testing.md +++ b/doc/development/new_fe_guide/development/testing.md @@ -339,7 +339,6 @@ afterEach(() => { Some regressions only affect a specific browser version. We can install and test in particular browsers with either Firefox or Browserstack using the following steps: - ### Browserstack [Browserstack](https://www.browserstack.com/) allows you to test more than 1200 mobile devices and browsers. diff --git a/doc/development/new_fe_guide/event_tracking.md b/doc/development/new_fe_guide/event_tracking.md new file mode 100644 index 00000000000..1958f1ce528 --- /dev/null +++ b/doc/development/new_fe_guide/event_tracking.md @@ -0,0 +1,74 @@ +# Event Tracking + +We use [Snowplow](https://github.com/snowplow/snowplow) for tracking custom events. + +## Generic tracking function + +In addition to Snowplow's built-in method for tracking page views, we use a generic tracking function which enables us to selectively apply listeners to events. + +The generic tracking function can be imported in EE-specific JS files as follows: + +```javascript +import { trackEvent } from `ee/stats`; +``` + +This gives the user access to the `trackEvent` method, which takes the following parameters: + +| parameter | type | description | required | +| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `category` | string | Describes the page that you're capturing click events on. Unless infeasible, please use the Rails page attribute `document.body.dataset.page` by default. | true | +| `eventName` | string | Describes the action the user is taking. The first word should always describe the action. For example, clicks should be `click` and activations should be `activate`. Use underscores to describe what was acted on. For example, activating a form field would be `activate_form_input`. Clicking on a dropdown is `click_dropdown`. | true | +| `additionalData` | object | Additional data such as `label`, `property`, and `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). | false | + +Read more about instrumentation and the taxonomy in the [Product Handbook](https://about.gitlab.com/handbook/product/feature-instrumentation). + +### Tracking in `.js` and `.vue` files + +The most simple use case is to add tracking programmatically to an event of interest in Javascript. + +The following example demonstrates how to track a click on a button in Javascript by calling the `trackEvent` method explicitly: + +```javascript +import { trackEvent } from `ee/stats`; + +trackEvent('dashboard:projects:index', 'click_button', { + label: 'create_from_template', + property: 'template_preview', + value: 'rails', +}); +``` + +### Tracking in HAML templates + +Sometimes we want to track clicks for multiple elements on a page. Creating event handlers for all elements could soon turn into a tedious task. + +There's a more convenient solution to this problem. When working with HAML templates, we can add `data-track-*` attributes to elements of interest. This way, all elements that have both `data-track-label` and `data-track-event` attributes assigned get marked for event tracking. All we have to do is call the `bindTrackableContainer` method on a container which allows for better scoping. + +Below is an example of `data-track-*` attributes assigned to a button in HAML: + +```ruby +%button.btn{ data: { track_label: "create_from_template", track_property: "template_preview", track_event: "click_button", track_value: "my-template" } } +``` + +By calling `bindTrackableContainer('.my-container')`, click handlers get bound to all elements located in `.my-container` provided that they have the necessary `data-track-*` attributes assigned to them. + +```javascript +import Stats from 'ee/stats'; + +document.addEventListener('DOMContentLoaded', () => { + Stats.bindTrackableContainer('.my-container', 'category'); +}); +``` + +The second parameter in `bindTrackableContainer` is optional. If omitted, the value of `document.body.dataset.page` will be used as category instead. + +Below is a list of supported `data-track-*` attributes: + +| attribute | description | required | +| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | +| `data-track-label` | The `label` in `trackEvent` | true | +| `data-track-event` | The `eventName` in `trackEvent` | true | +| `data-track-property` | The `property` in `trackEvent`. If omitted, an empty string will be used as a default value. | false | +| `data-track-value` | The `value` in `trackEvent`. If omitted, this will be `target.value` or empty string. For checkboxes, the default value being tracked will be the element's checked attribute if `data-track-value` is omitted. | false | + +Since Snowplow is an Enterprise Edition feature, it's necessary to create a CE backport when adding `data-track-*` attributes to HAML templates in most cases. diff --git a/doc/development/new_fe_guide/index.md b/doc/development/new_fe_guide/index.md index bfcca9cec7b..5fd5af252ef 100644 --- a/doc/development/new_fe_guide/index.md +++ b/doc/development/new_fe_guide/index.md @@ -27,6 +27,10 @@ Learn about all the internal JavaScript modules that make up our frontend. Style guides to keep our code consistent. +## [Event Tracking with Snowplow](event_tracking.md) + +How we use Snowplow to track custom events. + ## [Tips](tips.md) Tips from our frontend team to develop more efficiently and effectively. diff --git a/doc/development/performance.md b/doc/development/performance.md index 972c93be817..32970152911 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -336,7 +336,6 @@ the same method won't end up retrieving data from Redis upon every call. When memoizing cached data in an instance variable, make sure to also reset the instance variable when flushing the cache. An example: - ```ruby def first_branch @first_branch ||= cache.fetch(:first_branch) { branches.first } diff --git a/doc/development/policies.md b/doc/development/policies.md index 97424d90fb5..6a3b90f3604 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -8,7 +8,6 @@ The policy used is based on the subject's class name - so `Ability.allowed?(user Permissions are broken into two parts: `conditions` and `rules`. Conditions are boolean expressions that can access the database and the environment, while rules are statically configured combinations of expressions and other rules that enable or prevent certain abilities. For an ability to be allowed, it must be enabled by at least one rule, and not prevented by any. - ### Conditions Conditions are defined by the `condition` method, and are given a name and a block. The block will be executed in the context of the policy object - so it can access `@user` and `@subject`, as well as call any methods defined on the policy. Note that `@user` may be nil (in the anonymous case), but `@subject` is guaranteed to be a real instance of the subject class. @@ -66,7 +65,51 @@ Within the rule DSL, you can use: To see how the rules get evaluated into a judgment, it is useful in a console to use `policy.debug(:some_ability)`. This will print the rules in the order they are evaluated. -When a policy is asked whether a particular ability is allowed (`policy.allowed?(:some_ability)`), it does not necessarily have to compute all the conditions on the policy. First, only the rules relevant to that particular ability are selected. Then, the execution model takes advantage of short-circuiting, and attempts to sort rules based on a heuristic of how expensive they will be to calculate. The sorting is dynamic and cache-aware, so that previously calculated conditions will be considered first, before computing other conditions. +For example, let's say you wanted to debug `IssuePolicy`. You might run +the debugger in this way: + +```ruby +user = User.find_by(username: 'john') +issue = Issue.first +policy = IssuePolicy.new(user, issue) +policy.debug(:read_issue) +``` + +An example debug output would look as follows: + +```ruby +- [0] prevent when all?(confidential, ~can_read_confidential) ((@john : Issue/1)) +- [0] prevent when archived ((@john : Project/4)) +- [0] prevent when issues_disabled ((@john : Project/4)) +- [0] prevent when all?(anonymous, ~public_project) ((@john : Project/4)) ++ [32] enable when can?(:reporter_access) ((@john : Project/4)) +``` + +Each line represents a rule that was evaluated. There are a few things to note: + +1. The `-` or `+` symbol indicates whether the rule block was evaluated to be +`false` or `true`, respectively. +2. The number inside the brackets indicates the score. +3. The last part of the line (e.g. `@john : Issue/1`) shows the username +and subject for that rule. + +Here you can see that the first four rules were evaluated `false` for +which user and subject. For example, you can see in the last line that +the rule was activated because the user `root` had at reporter access to +the `Project/4`. + +When a policy is asked whether a particular ability is allowed +(`policy.allowed?(:some_ability)`), it does not necessarily have to +compute all the conditions on the policy. First, only the rules relevant +to that particular ability are selected. Then, the execution model takes +advantage of short-circuiting, and attempts to sort rules based on a +heuristic of how expensive they will be to calculate. The sorting is +dynamic and cache-aware, so that previously calculated conditions will +be considered first, before computing other conditions. + +Note that the score is chosen by a developer via the `score:` parameter +in a `condition` to denote how expensive evaluating this rule would be +relative to other rules. ## Scope diff --git a/doc/development/profiling.md b/doc/development/profiling.md index 0b0c6dfc8cf..f41d635de43 100644 --- a/doc/development/profiling.md +++ b/doc/development/profiling.md @@ -72,6 +72,15 @@ Gitlab::Profiler.print_by_total_time(result, max_percent: 60, min_percent: 2) # 0.02 0.865 0.000 0.000 0.864 638 *Enumerable#inject ``` +To print the profile in HTML format, use the following example: + +```ruby +result = Gitlab::Profiler.profile('/my-user') + +printer = RubyProf::CallStackPrinter.new(result) +printer.print(File.open('/tmp/profile.html', 'w')) +``` + [GitLab-Profiler](https://gitlab.com/gitlab-com/gitlab-profiler) is a project that builds on this to add some additional niceties, such as allowing configuration with a single Yaml file for multiple URLs, and uploading of the @@ -82,7 +91,6 @@ Redash to Looker](https://gitlab.com/gitlab-com/Product/issues/5#note_121194467) We are [currently investigating how to make this data public](https://gitlab.com/meltano/looker/issues/294). - ## Sherlock Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_ diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index ae9bf863419..4cc500ed1b6 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -151,7 +151,6 @@ following: bundle exec rake gemojione:digests ``` - This will update the file `fixtures/emojis/digests.json` based on the currently available Emoji. diff --git a/doc/development/shell_commands.md b/doc/development/shell_commands.md index 73893f9dd46..7bdf676be58 100644 --- a/doc/development/shell_commands.md +++ b/doc/development/shell_commands.md @@ -190,7 +190,7 @@ A check like this could have avoided CVE-2013-4583. ## Properly anchor regular expressions to the start and end of strings -When using regular expressions to validate user input that is passed as an argument to a shell command, make sure to use the `\A` and `\z` anchors that designate the start and end of the string, rather than `^` and `$`, or no anchors at all. +When using regular expressions to validate user input that is passed as an argument to a shell command, make sure to use the `\A` and `\z` anchors that designate the start and end of the string, rather than `^` and `$`, or no anchors at all. If you don't, an attacker could use this to execute commands with potentially harmful effect. @@ -198,7 +198,7 @@ For example, when a project's `import_url` is validated like below, the user cou ```ruby validates :import_url, format: { with: URI.regexp(%w(ssh git http https)) } -# URI.regexp(%w(ssh git http https)) roughly evaluates to /(ssh|git|http|https):(something_that_looks_like_a_url)/ +# URI.regexp(%w(ssh git http https)) roughly evaluates to /(ssh|git|http|https):(something_that_looks_like_a_url)/ ``` Suppose the user submits the following as their import URL: @@ -211,7 +211,6 @@ Since there are no anchors in the used regular expression, the `git:/tmp/lol` in When importing, GitLab would execute the following command, passing the `import_url` as an argument: - ```sh git clone file://git:/tmp/lol ``` diff --git a/doc/development/testing_guide/ci.md b/doc/development/testing_guide/ci.md index d685cacf9ea..5aa668290b4 100644 --- a/doc/development/testing_guide/ci.md +++ b/doc/development/testing_guide/ci.md @@ -24,7 +24,7 @@ Our current CI parallelization setup is as follows: uploaded to S3. After that, the next pipeline will use the up-to-date -`knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file. +`knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file. ### Monitoring diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md index 3af97717775..85b47f88cc4 100644 --- a/doc/development/testing_guide/review_apps.md +++ b/doc/development/testing_guide/review_apps.md @@ -143,17 +143,21 @@ thousands of unused Docker images.** **How big are the Kubernetes clusters (`review-apps-ce` and `review-apps-ee`)?** > The clusters are currently set up with a single pool of preemptible nodes, - with a minimum of 1 node and a maximum of 100 nodes. + with a minimum of 1 node and a maximum of 50 nodes. **What are the machine running on the cluster?** - > We're currently using `n1-standard-4` (4 vCPUs, 15 GB memory) machines. + > We're currently using `n1-standard-16` (16 vCPUs, 60 GB memory) machines. **How do we secure this from abuse? Apps are open to the world so we need to find a way to limit it to only us.** > This isn't enabled for forks. +## Other resources + +* [Review Apps integration for CE/EE (presentation)](https://docs.google.com/presentation/d/1QPLr6FO4LduROU8pQIPkX1yfGvD13GEJIBOenqoKxR8/edit?usp=sharing) + [charts-1068]: https://gitlab.com/charts/gitlab/issues/1068 [gitlab-pipeline]: https://gitlab.com/gitlab-org/gitlab-ce/pipelines/44362587 [gitlab:assets:compile]: https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/149511610 diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 070b6477a7a..a7a3459719b 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -159,6 +159,10 @@ Every new feature should come with a [test plan]. > See [end-to-end tests](end_to_end_tests.md) for more information. +Note that `qa/spec` contains unit tests of the QA framework itself, not to be +confused with the application's [unit tests](#unit-tests) or +[end-to-end tests](#black-box-tests-at-the-system-level-aka-end-to-end-tests). + [multiple pieces]: ../architecture.md#components [GitLab Shell]: https://gitlab.com/gitlab-org/gitlab-shell [GitLab Workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse diff --git a/doc/gitlab-basics/create-your-ssh-keys.md b/doc/gitlab-basics/create-your-ssh-keys.md index 881629c3bfd..8c2f48fb1e2 100644 --- a/doc/gitlab-basics/create-your-ssh-keys.md +++ b/doc/gitlab-basics/create-your-ssh-keys.md @@ -27,7 +27,6 @@  - >**Note:** Once you add a key, you cannot edit it, only remove it. In case the paste didn't work, you will have to remove the offending key and re-add it. diff --git a/doc/install/README.md b/doc/install/README.md index ae48306e65e..52011526768 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -3,7 +3,7 @@ comments: false description: Read through the GitLab installation methods. --- -# Installation +# 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 e209a00b38c..51d2a232dc0 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -471,7 +471,6 @@ gitlab_rails['redis_port'] = 6379 Finally, reconfigure GitLab for the change to take effect: - ```sh sudo gitlab-ctl reconfigure ``` diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index 19a6e46f969..be14858f4c8 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -1,5 +1,5 @@ --- -description: 'Learn how to spin up a +description: 'Learn how to spin up a pre-configured GitLab VM on Microsoft Azure and have your very own private GitLab instance up and running in around 30 minutes.' --- @@ -9,10 +9,10 @@ pre-configured GitLab VM on Microsoft Azure and have your very own private GitLa > > _Ported to the GitLab documentation and updated on 2017-08-24 by [Ian Scorer](https://gitlab.com/iscorer)._ -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. +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 @@ -20,40 +20,40 @@ Let's get 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 +- 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 +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][Azure-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 +- 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. Login to Azure using +Once you have an Azure account, you can get started. Login to Azure using [portal.azure.com](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, +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][Azure-Marketplace] is an online store for pre-configured applications and +The [Azure Marketplace][Azure-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, but for GitLab Enterprise Edition you can follow the same process. -To begin creating a new GitLab VM, click on the **+ New** icon, type "GitLab" into the search +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"** +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:  @@ -70,18 +70,18 @@ The first items we need to configure are the basic settings of the underlying vi 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** - 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 + 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 + 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. + > **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 @@ -94,23 +94,23 @@ Check the settings you have entered, and then click **"OK"** when you're ready t ## Size -Next, you need to choose the size of your VM - selecting features such as the number of CPU cores, +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. -> **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 +> **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. -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 +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:  -> **Note:** be aware that whilst 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 +> **Note:** be aware that whilst 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 [how to properly shutdown an Azure VM to save money][Azure-Properly-Shutdown-VM]. Go ahead and click your chosen size, then click **"Select"** when you're ready to proceed to the @@ -118,8 +118,8 @@ next step. ## Settings -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 +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:  @@ -128,80 +128,80 @@ Review the settings and then click **"OK"** when you're ready to proceed to the ## Purchase -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 +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:  -> **Note:** at this stage, you can review and modify the any of the settings you have made during all +> **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. When you have read and agreed to the terms of use and are ready to proceed, click **"Purchase"**. ## Deployment -At this point, Azure will begin deploying your new VM. The deployment process will take a few +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:  -Once the deployment process is complete, the new VM and its associated resources will be displayed +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):  -The new VM can also be accessed by clicking the `All resources` or `Virtual machines` icons in the +The new VM can also be accessed by clicking the `All resources` or `Virtual machines` icons in the Azure Portal sidebar navigation menu. ## Set up a domain name -The VM will have a public IP address (static by default), but Azure allows us to assign a friendly +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. -From the Dashboard, click on the **"GitLab-CE"** tile to open the management blade for the new VM. +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:  -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 +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:  -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)_. +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)_. Click **"Save"** for the changes to take effect. -> **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 +> **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 [IP address types and allocation methods in Azure][Azure-IP-Address-Types] 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 +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. +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. -> **Note:** if you gave your VM a different name then the NSG automatically created by Azure will +> **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. -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 +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:  -With the **"Network security group"** blade open, click on **"Inbound security rules"** under +With the **"Network security group"** blade open, click on **"Inbound security rules"** under **"Settings"**:  @@ -212,18 +212,18 @@ Next, click **"Add"**: ### Which ports to open? -Like all servers, our VM will be running many services. However, we want to open up the correct +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: -1. **HTTP** (port 80) - opening port 80 will enable our VM to respond to HTTP requests, allowing +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 +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] access to our VM [later on in this tutorial](#maintaining-your-gitlab-instance))_ ### Open HTTP on Port 80 -In the **"Add inbound security rule"** blade, let's open port 80 so that our VM will accept HTTP +In the **"Add inbound security rule"** blade, let's open port 80 so that our VM will accept HTTP connections:  @@ -235,7 +235,7 @@ connections: ### Open SSH on Port 22 -Repeat the above process, adding a second Inbound security rule to open port 22, enabling our VM to +Repeat the above process, adding a second Inbound security rule to open port 22, enabling our VM to accept [SSH] connections:  @@ -245,16 +245,15 @@ accept [SSH] connections: 1. Make sure the `Action` is set to **Allow** 1. Click **"OK"** - -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 +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:  ## 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 +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: @@ -262,26 +261,26 @@ created by GitLab: Enter your _new_ password into both form fields, and then click **"Change your password"**. -Once you have changed the password you will be redirected to the GitLab login page. Use `root` as +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"**:  ### Success? -After signing in successfully, you should see the GitLab Projects page displaying a +After signing in successfully, you should see the GitLab Projects page displaying a **"Welcome to GitLab!"** message:  -If so, you now have a working GitLab instance on your own private Azure VM. **Congratulations!** +If so, you now have a working GitLab instance on your own private Azure VM. **Congratulations!** ## Creating your first GitLab project -You can skip this section if you are familiar with Git and GitLab. Otherwise, let's create our first +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"**. -Let's give our project a name and a description, and then accept the default values for everything +Let's give our project a name and a description, and then accept the default values for everything else: 1. Enter **"demo"** into the `Project path` project name field @@ -290,12 +289,12 @@ else:  -Once the new project has been created (which should only take a moment), you'll be redirected to +Once the new project has been created (which should only take a moment), you'll be redirected to homepage for the project:  -If you scroll further down the project's home page, you'll see some basic instructions on how to +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:  @@ -304,50 +303,50 @@ set up a local clone of your new repository and push and pull from it: ## Maintaining your GitLab instance -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. +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. ### Checking our current version 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. +the wrench icon displayed in the top-right, next to the search box. -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 +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:  -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. +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. -> **Note:** The version of GitLab in your own VM instance may well be different, but the update +> **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][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][SSH]). -If you're running Windows, you'll need to connect using [PuTTY] or an equivalent Windows SSH client. -If you're running Linux or macOS, then you already have an SSH client installed. +If you're running Windows, you'll need to connect using [PuTTY] or an equivalent Windows SSH client. +If you're running Linux or macOS, then you already have an SSH client installed. -> **Note:** -> - Remember that you will need to login with the username and password you specified +> **Note:** +> - Remember that you will need to login with the username and password you specified > [when you created](#basics) your Azure VM -> - If you need to reset your VM password, read +> - If you need to reset your VM password, read > [how to reset SSH credentials for a user on an Azure VM][Azure-Troubleshoot-SSH-Connection]. #### SSH from the command-line -If you're running [SSH] 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. +If you're running [SSH] 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 +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: ```bash @@ -357,7 +356,7 @@ Provide your password at the prompt to authenticate. #### SSH from Windows (PuTTY) -If you're using [PuTTY] in Windows as your [SSH] client, then you might want to take a quick +If you're using [PuTTY] in Windows as your [SSH] client, then you might want to take a quick read on [using PuTTY in Windows][Using-SSH-In-Putty]. ### Updating GitLab @@ -369,8 +368,8 @@ version: sudo apt-get update && sudo apt-get install gitlab-ce ``` -This command will update 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 +This command will update 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:  @@ -387,23 +386,23 @@ before anything else. #### 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. +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"** +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. +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 +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. diff --git a/doc/install/installation.md b/doc/install/installation.md index a8064ae046e..fb24d4fa0ef 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -108,7 +108,7 @@ sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libs # Download and compile from source cd /tmp -curl --remote-name --progress https://www.kernel.org/pub/software/scm/git/git-2.18.0.tar.gz +curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.18.0.tar.gz echo '94faf2c0b02a7920b0b46f4961d8e9cad08e81418614102898a55f980fa3e7e4 git-2.18.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.18.0.tar.gz cd git-2.18.0/ ./configure diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md index 26ced45de7b..9db246b3eb3 100644 --- a/doc/install/kubernetes/gitlab_chart.md +++ b/doc/install/kubernetes/gitlab_chart.md @@ -5,7 +5,7 @@ This is the official way to install GitLab on a cloud native environment. NOTE: **Kubernetes experience required:** Our Helm charts are recommended for those who are familiar with Kubernetes. If you're not sure if Kubernetes is for you, our -[Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended) +[Omnibus GitLab packages](../README.md#installing-gitlab-using-the-omnibus-gitlab-package-recommended) are mature, scalable, support [high availability](../../administration/high_availability/README.md) and are used today on GitLab.com. It is not necessary to have GitLab installed on Kubernetes in order to use [GitLab Kubernetes integration](https://docs.gitlab.com/ee/user/project/clusters/index.html). diff --git a/doc/install/kubernetes/gitlab_omnibus.md b/doc/install/kubernetes/gitlab_omnibus.md index 2ae5485869e..c0cb7694e91 100644 --- a/doc/install/kubernetes/gitlab_omnibus.md +++ b/doc/install/kubernetes/gitlab_omnibus.md @@ -4,7 +4,7 @@ CAUTION: **Caution:** This chart is **deprecated**. We recommend using the [`gitlab` chart](gitlab_chart.md) instead. A comparison of the two charts is available in [this video](https://youtu.be/Z6jWR8Z8dv8). -For more information on available GitLab Helm Charts, see the [charts overview](index.md#chart-overview). +For more information on available GitLab Helm Charts, see [Installing GitLab on Kubernetes](index.md). - This GitLab-Omnibus chart has been tested on Google Kubernetes Engine and Azure Container Service. - This work is based partially on: <https://github.com/lwolf/kubernetes-gitlab/>. GitLab would like to thank Sergey Nuzhdin for his work. @@ -39,7 +39,7 @@ The deployment includes: - _At least_ 4 GB of RAM available on your cluster. 41GB of storage and 2 CPU are also required. - Kubernetes 1.4+ with Beta APIs enabled - [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) provisioner support in the underlying infrastructure -- A [wildcard DNS entry](#networking-prerequisites), which resolves to the external IP address +- A [wildcard DNS entry](#networking-requirements), which resolves to the external IP address - The `kubectl` CLI installed locally and authenticated for the cluster - The [Helm client](https://github.com/kubernetes/helm/blob/master/docs/quickstart.md) installed locally on your machine @@ -52,7 +52,7 @@ and [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/). To support the GitLab services and dynamic environments, a wildcard DNS entry is required which resolves to the [load balancer](#load-balancer-ip) or -[external IP](#external-ip). Configuration of the DNS entry will depend upon +[external IP](#external-ip-recommended). Configuration of the DNS entry will depend upon the DNS service being used. #### External IP (recommended) @@ -84,13 +84,13 @@ to configure the Wildcard DNS entry. For more information on creating a wildcard DNS entry, consult the documentation for the DNS server you are using. For production deployments of GitLab, we strongly recommend using a -[external IP](#external-ip). +[external IP](#external-ip-recommended). ## Configuring and Installing GitLab For most installations, two parameters are required: -- `baseDomain`: the [base domain](#networking-prerequisites) of the wildcard host entry. For example, `mycompany.io` if the wild card entry is `*.mycompany.io`. +- `baseDomain`: the [base domain](#networking-requirements) of the wildcard host entry. For example, `mycompany.io` if the wild card entry is `*.mycompany.io`. - `legoEmail`: Email address to use when requesting new SSL certificates from Let's Encrypt. Other common configuration options: @@ -105,7 +105,7 @@ For additional configuration options, consult the ### Choosing a different GitLab release version -The version of GitLab installed is based on the `gitlab` setting (see [section](#choosing-gitlab-edition) above), and +The version of GitLab installed is based on the `gitlab` setting (see [section](#configuring-and-installing-gitLab) above), and the value of the corresponding helm setting: `gitlabCEImage` or `gitabEEImage`. ```yaml diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md index 3c2f883f29d..68b2a146115 100644 --- a/doc/install/kubernetes/gitlab_runner_chart.md +++ b/doc/install/kubernetes/gitlab_runner_chart.md @@ -11,7 +11,7 @@ This chart configures the Runner to: - For each new job it receives from [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/), it will provision a new pod within the specified namespace to run it. -For more information on available GitLab Helm Charts, please see our [overview](index.md#chart-overview). +For more information on available GitLab Helm Charts, please see our [overview](index.md). ## Prerequisites @@ -33,7 +33,7 @@ In order for GitLab Runner to function, your config file **must** specify the fo - `gitlabUrl` - the GitLab Server URL (with protocol) to register the runner against - `runnerRegistrationToken` - The Registration Token for adding new Runners to the GitLab Server. This must be - retrieved from your GitLab Instance. See the [GitLab Runner Documentation](../../ci/runners/README.md#creating-and-registering-a-runner) for more information. + retrieved from your GitLab Instance. See the [GitLab Runner Documentation](../../ci/runners/README.md) for more information. Unless you need to specify additional configuration, you are [ready to install](#installing-gitlab-runner-using-the-helm-chart). @@ -51,7 +51,7 @@ gitlabUrl: http://gitlab.your-domain.com/ ## The Registration Token for adding new Runners to the GitLab Server. This must ## be retrieved from your GitLab Instance. -## ref: https://docs.gitlab.com/ce/ci/runners/README.html#creating-and-registering-a-runner +## ref: https://docs.gitlab.com/ee/ci/runners/README.html ## runnerRegistrationToken: "" @@ -227,7 +227,7 @@ helm repo add gitlab https://charts.gitlab.io helm init ``` -Once you [have configured](#configuration) GitLab Runner in your `values.yml` file, +Once you [have configured](#configuring-gitlab-runner-using-the-helm-chart) GitLab Runner in your `values.yml` file, run the following: ```bash @@ -236,7 +236,7 @@ helm install --namespace <NAMESPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE - `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner. - `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the - [Configuration](#configuration) section to create it. + [Configuring GitLab Runner using the Helm Chart](#configuring-gitlab-runner-using-the-helm-chart) section to create it. ## Updating GitLab Runner using the Helm Chart @@ -247,11 +247,12 @@ helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitl ``` Where: + - `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed - `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the - [Configuration](#configuration) section to create it. + [Configuring GitLab Runner using the Helm Chart](#configuring-gitlab-runner-using-the-helm-chart) section to create it. - `<RELEASE-NAME>` is the name you gave the chart when installing it. - In the [Install section](#installing) we called it `gitlab-runner`. + In the [Installing GitLab Runner using the Helm Chart](#installing-gitlab-runner-using-the-helm-chart) section, we called it `gitlab-runner`. ## Uninstalling GitLab Runner using the Helm Chart @@ -265,4 +266,4 @@ where: - `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed - `<RELEASE-NAME>` is the name you gave the chart when installing it. - In the [Install section](#installing) we called it `gitlab-runner`. + In the [Installing GitLab Runner using the Helm Chart](#installing-gitlab-runner-using-the-helm-chart) section, we called it `gitlab-runner`. diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md index 281630174e7..ecc956d04e9 100644 --- a/doc/install/kubernetes/index.md +++ b/doc/install/kubernetes/index.md @@ -7,7 +7,7 @@ description: 'Read through the different methods to deploy GitLab on Kubernetes. NOTE: **Kubernetes experience required:** Our Helm charts are recommended for those who are familiar with Kubernetes. If you're not sure if Kubernetes is for you, our -[Omnibus GitLab packages](../README.md#install-gitlab-using-the-omnibus-gitlab-package-recommended) +[Omnibus GitLab packages](../README.md#installing-gitlab-using-the-omnibus-gitlab-package-recommended) are mature, scalable, support [high availability](../../administration/high_availability/README.md) and are used today on GitLab.com. It is not necessary to have GitLab installed on Kubernetes in order to use [GitLab Kubernetes integration](https://docs.gitlab.com/ee/user/project/clusters/index.html). diff --git a/doc/install/kubernetes/preparation/eks.md b/doc/install/kubernetes/preparation/eks.md index c40177c4302..647b856d54e 100644 --- a/doc/install/kubernetes/preparation/eks.md +++ b/doc/install/kubernetes/preparation/eks.md @@ -26,7 +26,7 @@ With EKS, there are a few important details to keep in mind: The easiest way to solve this and still utilize dynamic provisioning is to utilize, or create, a Storage Class that is locked to a specific zone. -> **Note**: Restricting volumes to specific zone will cause GitLab and any other application using this Storage Class to only reside in that zone. For multiple zone support, utilize [manually provisioned volumes](#manual-provisioning-of-volumes). +> **Note**: Restricting volumes to specific zone will cause GitLab and any other application using this Storage Class to only reside in that zone. For multiple zone support, utilize [manually provisioned volumes](#manual-provisioning-of-volumes-recommended). To create the storage class, download and edit Amazon EKS's [sample Storage Class](https://docs.aws.amazon.com/eks/latest/userguide/storage-classes.html) and add the following parameter: diff --git a/doc/install/kubernetes/preparation/networking.md b/doc/install/kubernetes/preparation/networking.md index 34a6130de27..b9fb9a7399f 100644 --- a/doc/install/kubernetes/preparation/networking.md +++ b/doc/install/kubernetes/preparation/networking.md @@ -12,7 +12,7 @@ To support the GitLab services and dynamic environments, a wildcard DNS entry is To provision an external IP on GCP and Azure, simply request a new address from the Networking section. Ensure that the region matches the region your container cluster is created in. Note, it is important that the IP is not assigned at this point in time. It will be automatically assigned once the Helm chart is installed, to the Load Balancer. -Set `global.hosts.externalIP` to this IP address when [deploying GitLab](../gitlab_chart.md#configuring-and-installing-gitlab). +Set `global.hosts.externalIP` to this IP address when [deploying GitLab](../gitlab_chart.md#installing-gitlab-using-the-helm-chart). Then, create a [wildcard DNS record](#wildcard-dns-entry) which resolves to this IP address. @@ -35,4 +35,4 @@ Please consult the documentation for your DNS service for more information on cr - [Google Domains](https://support.google.com/domains/answer/3290350?hl=en) - [GoDaddy](https://www.godaddy.com/help/add-an-a-record-19238) -Set `global.hosts.domain` to this DNS name when [deploying GitLab](../gitlab_chart.md#configuring-and-installing-gitlab). +Set `global.hosts.domain` to this DNS name when [deploying GitLab](../gitlab_chart.md#installing-gitlab-using-the-helm-chart). diff --git a/doc/install/kubernetes/preparation/tools_installation.md b/doc/install/kubernetes/preparation/tools_installation.md index 210bc2f9e58..d2f7a69a0af 100644 --- a/doc/install/kubernetes/preparation/tools_installation.md +++ b/doc/install/kubernetes/preparation/tools_installation.md @@ -16,4 +16,4 @@ You can get Helm from the project's [releases page](https://github.com/kubernete # Next steps -Once installed, proceed to the next [installation step](../gitlab_chart.md#prerequisites). +Once installed, proceed to the next [installation step](../gitlab_chart.md#installing-gitlab-using-the-helm-chart). diff --git a/doc/integration/README.md b/doc/integration/README.md index 8a93d4cb84b..7941cb42667 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -30,8 +30,8 @@ Bitbucket.org account ## Project services -Integration with services such as Campfire, Flowdock, HipChat, -Pivotal Tracker, and Slack are available in the form of a [Project Service][]. +Integration with services such as Campfire, Flowdock, Pivotal Tracker, and Slack +are available in the form of a [Project Service][]. [Project Service]: ../user/project/integrations/project_services.md diff --git a/doc/integration/akismet.md b/doc/integration/akismet.md index 35024a78fca..4f7be70baf2 100644 --- a/doc/integration/akismet.md +++ b/doc/integration/akismet.md @@ -34,7 +34,6 @@ To use Akismet:  - ## Training > *Note:* Training the Akismet filter is only available in 8.11 and above. diff --git a/doc/integration/cas.md b/doc/integration/cas.md index f757edf0bc2..c6178fa44f0 100644 --- a/doc/integration/cas.md +++ b/doc/integration/cas.md @@ -38,7 +38,6 @@ To enable the CAS OmniAuth provider you must register your application with your } ] ``` - For installations from source: @@ -65,4 +64,3 @@ On the sign in page there should now be a CAS tab in the sign in form. [reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source - diff --git a/doc/integration/github.md b/doc/integration/github.md index eca9aa16499..bee68688ace 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -21,10 +21,10 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Homepage URL: the URL to your GitLab installation. e.g., `https://gitlab.company.com` - Application description: Fill this in if you wish. - - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port. + - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth/github/callback`. Please make sure the port is included if your GitLab instance is not configured on default port.  - NOTE: Be sure to append `/users/auth` to the end of the callback URL + NOTE: Be sure to append `/users/auth/github/callback` to the end of the callback URL to prevent a [OAuth2 convert redirect](http://tetraph.com/covert_redirect/) vulnerability. @@ -93,7 +93,6 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe args: { scope: 'user:email' } } ``` - For GitHub Enterprise: ``` diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index f5f1f9486c2..4db986197f3 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -231,7 +231,6 @@ In order to enable/disable an OmniAuth provider, go to Admin Area -> Settings ->  - ## Disabling Omniauth Starting from version 11.4 of GitLab, Omniauth is enabled by default. This only diff --git a/doc/integration/saml.md b/doc/integration/saml.md index bb3cd9a005f..8ee07a7fcdc 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -249,7 +249,6 @@ If you want some SAML authentication methods to count as 2FA on a per session ba 1. Save the file and [restart GitLab][] for the changes ot take effect - In addition to the changes in GitLab, make sure that your Idp is returning the `AuthnContext`. For example: diff --git a/doc/integration/slash_commands.md b/doc/integration/slash_commands.md index 7d73026a6c6..82ba1d7d984 100644 --- a/doc/integration/slash_commands.md +++ b/doc/integration/slash_commands.md @@ -8,7 +8,6 @@ We suggest you use the project name as the trigger term for simplicity and clari Taking the trigger term as `project-name`, the commands are: - | Command | Effect | | ------- | ------ | | `/project-name help` | Shows all available slash commands | diff --git a/doc/intro/README.md b/doc/intro/README.md index d9acc5bdeac..9bc7c3d9ea4 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -9,13 +9,13 @@ comments: false Create projects and groups. - [Create a new project](../gitlab-basics/create-project.md) -- [Create a new group](../gitlab-basics/create-group.md) +- [Create a new group](../user/group/index.md#create-a-new-group) ## Prioritize Create issues, labels, milestones, cast your vote, and review issues. -- [Create a new issue](../user/project/issues/index.md#new-issue) +- [Create an issue](../user/project/issues/create_new_issue.md) - [Assign labels to issues](../user/project/labels.md) - [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md) - [Use voting to express your like/dislike to issues and merge requests](../workflow/award_emoji.md) diff --git a/doc/project_services/hipchat.md b/doc/project_services/hipchat.md deleted file mode 100644 index 4ae9f6c6b2e..00000000000 --- a/doc/project_services/hipchat.md +++ /dev/null @@ -1 +0,0 @@ -This document was moved to [user/project/integrations/hipchat.md](../user/project/integrations/hipchat.md). diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 037b71a27b9..2514ca94775 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -442,7 +442,6 @@ backups will be copied to, and will be created if it does not exist. If the directory that you want to copy the tarballs to is the root of your mounted directory, just use `.` instead. - For Omnibus GitLab packages: 1. Edit `/etc/gitlab/gitlab.rb`: @@ -564,7 +563,6 @@ For installations from source: 1. [Restart GitLab] for the changes to take effect. - ```sh sudo -u git crontab -e # Edit the crontab for the git user ``` @@ -806,9 +804,22 @@ If you have failed to [back up the secrets file](#storing-configuration-files), then users with 2FA enabled will not be able to log into GitLab. In that case, you need to [disable 2FA for everyone](../security/two_factor_authentication.md#disabling-2fa-for-everyone). -In the case of CI/CD, if your project has secure variables set, you might experience -some weird behavior, like stuck jobs or 500 errors. In that case, you can try -deleting the `ci_variables` table from the database. +The secrets file is also responsible for storing the encryption key for several +columns containing sensitive information. If the key is lost, GitLab will be +unable to decrypt those columns. This will break a wide range of functionality, +including (but not restricted to): + +* [CI/CD variables](../ci/variables/README.md) +* [Kubernetes / GCP integration](../user/project/clusters/index.md) +* [Custom Pages domains](../user/project/pages/getting_started_part_three.md) +* [Project error tracking](../user/project/operations/error_tracking.md) +* [Runner authentication](../ci/runners/README.md) +* [Project mirroring](../workflow/repository_mirroring.md) +* [Web hooks](../user/project/integrations/webhooks.md) + +In the case of CI/CD, variables, you might experience some weird behavior, like +stuck jobs or 500 errors. In that case, you can try removing contents of the +`ci_group_variables` and `ci_project_variables` tables from the database. CAUTION: **Warning:** Use the following commands at your own risk, and make sure you've taken a @@ -828,9 +839,10 @@ backup beforehand. sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production ``` -1. Check the `ci_variables` table: +1. Check the `ci_group_variables` and `ci_variables` tables: ```sql + SELECT * FROM public."ci_group_variables"; SELECT * FROM public."ci_variables"; ``` @@ -839,6 +851,7 @@ backup beforehand. 1. Drop the table: ```sql + DELETE FROM ci_group_variables; DELETE FROM ci_variables; ``` @@ -848,5 +861,9 @@ backup beforehand. You should now be able to visit your project, and the jobs will start running again. +A similar strategy can be employed for the remaining features - by removing the +data that cannot be decrypted, GitLab can be brought back into working order, +and the lost data can be manually replaced. + [reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source diff --git a/doc/raketasks/user_management.md b/doc/raketasks/user_management.md index e1b1912ed47..571e784e530 100644 --- a/doc/raketasks/user_management.md +++ b/doc/raketasks/user_management.md @@ -52,7 +52,6 @@ bundle exec rake gitlab:import:all_users_to_all_groups RAILS_ENV=production - Enable this setting to keep new users blocked until they have been cleared by the admin (default: false). - ``` block_auto_created_users: false ``` @@ -77,7 +76,6 @@ GitLab stores the secret data enabling 2FA to work in an encrypted database column. The encryption key for this data is known as `otp_key_base`, and is stored in `config/secrets.yml`. - If that file is leaked, but the individual 2FA secrets have not, it's possible to re-encrypt those secrets with a new encryption key. This allows you to change the leaked key without forcing all users to change their 2FA details. diff --git a/doc/security/README.md b/doc/security/README.md index e22dc00759d..a90127e0356 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -15,3 +15,4 @@ comments: false - [How we manage the CRIME vulnerability](crime_vulnerability.md) - [Enforce Two-factor authentication](two_factor_authentication.md) - [Send email confirmation on sign-up](user_email_confirmation.md) +- [Security of running jobs](https://docs.gitlab.com/runner/security/) diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 1b53be15b44..9c4a391e8da 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -247,6 +247,17 @@ Public SSH keys need to be unique to GitLab, as they will bind to your account. Your SSH key is the only identifier you'll have when pushing code via SSH, that's why it needs to uniquely map to a single user. +## Per-repository SSH keys + +If you want to use different keys depending on the repository you are working +on, you can issue the following command while inside your repository: + +```sh +git config core.sshCommand "ssh -o IdentitiesOnly=yes -i ~/.ssh/private-key-filename-for-this-repository -F /dev/null" +``` + +This will not use the SSH Agent and requires at least Git 2.10. + ## Deploy keys ### Per-repository deploy keys diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index 6d63906ea4d..55b678d6af5 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -138,7 +138,7 @@ Please refer to `group_rename` and `user_rename` for that case. "created_at": "2012-07-21T07:30:56Z", "updated_at": "2012-07-21T07:38:22Z", "event_name": "user_add_to_team", - "project_access": "Maintainer", + "access_level": "Maintainer", "project_id": 74, "project_name": "StoreCloud", "project_path": "storecloud", diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md index a354d3e7884..df6897002c9 100644 --- a/doc/topics/authentication/index.md +++ b/doc/topics/authentication/index.md @@ -21,7 +21,7 @@ This page gathers all the resources for the topic **Authentication** within GitL - [Enforce Two-factor Authentication (2FA)](../../security/two_factor_authentication.md#enforce-two-factor-authentication-2fa) - **Articles:** - [How to Configure LDAP with GitLab CE](../../administration/auth/how_to_configure_ldap_gitlab_ce/index.md) - - [How to Configure LDAP with GitLab EE](https://docs.gitlab.com/ee/articles/how_to_configure_ldap_gitlab_ee/) + - [How to Configure LDAP with GitLab EE](https://docs.gitlab.com/ee/administration/auth/how_to_configure_ldap_gitlab_ee/index.md) - [Feature Highlight: LDAP Integration](https://about.gitlab.com/2014/07/10/feature-highlight-ldap-sync/) - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/support-engineering/ldap/debugging_ldap.html) - **Integrations:** diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 463bdd59282..1ab0372fb67 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -13,7 +13,7 @@ Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for al projects. If it has not been explicitly enabled for the project, Auto DevOps will be automatically disabled on the first pipeline failure. Your project will continue to use an alternative [CI/CD configuration file](../../ci/yaml/README.md) if one is found. A GitLab -administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops) +administrator can [change this setting](../../user/admin_area/settings/continuous_integration.html#auto-devops-core-only) in the admin area. With Auto DevOps, the software development process becomes easier to set up @@ -58,15 +58,15 @@ project in a simple and automatic way: 1. [Auto Build](#auto-build) 1. [Auto Test](#auto-test) -1. [Auto Code Quality](#auto-code-quality) **[STARTER]** -1. [Auto SAST (Static Application Security Testing)](#auto-sast) **[ULTIMATE]** -1. [Auto Dependency Scanning](#auto-dependency-scanning) **[ULTIMATE]** -1. [Auto License Management](#auto-license-management) **[ULTIMATE]** +1. [Auto Code Quality](#auto-code-quality-starter) **[STARTER]** +1. [Auto SAST (Static Application Security Testing)](#auto-sast-ultimate) **[ULTIMATE]** +1. [Auto Dependency Scanning](#auto-dependency-scanning-ultimate) **[ULTIMATE]** +1. [Auto License Management](#auto-license-management-ultimate) **[ULTIMATE]** 1. [Auto Container Scanning](#auto-container-scanning) 1. [Auto Review Apps](#auto-review-apps) -1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast) **[ULTIMATE]** +1. [Auto DAST (Dynamic Application Security Testing)](#auto-dast-ultimate) **[ULTIMATE]** 1. [Auto Deploy](#auto-deploy) -1. [Auto Browser Performance Testing](#auto-browser-performance-testing) **[PREMIUM]** +1. [Auto Browser Performance Testing](#auto-browser-performance-testing-premium) **[PREMIUM]** 1. [Auto Monitoring](#auto-monitoring) As Auto DevOps relies on many different components, it's good to have a basic @@ -114,7 +114,7 @@ To make full use of Auto DevOps, you will need: will need Prometheus installed somewhere (inside or outside your cluster) and configured to scrape your Kubernetes cluster. To get response metrics (in addition to system metrics), you need to - [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-prometheus-to-monitor-for-nginx-ingress-metrics). + [configure Prometheus to monitor NGINX](../../user/project/integrations/prometheus_library/nginx_ingress.md#configuring-nginx-ingress-monitoring). The [Prometheus service](../../user/project/integrations/prometheus.md) integration needs to be enabled for the project, or enabled as a [default service template](../../user/project/integrations/services_templates.md) @@ -128,7 +128,7 @@ Auto Deploy, and Auto Monitoring will be silently skipped. NOTE: **Note** `AUTO_DEVOPS_DOMAIN` environment variable is deprecated and -[is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959) in GitLab 12.0. +[is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). The Auto DevOps base domain is required if you want to make use of [Auto Review Apps](#auto-review-apps) and [Auto Deploy](#auto-deploy). It can be defined @@ -166,7 +166,7 @@ them to the Kubernetes pods that run your application(s). When using Auto DevOps, you may want to deploy different environments to different Kubernetes clusters. This is possible due to the 1:1 connection that -[exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters). +[exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters-premium). In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) (used behind the scenes by Auto DevOps), there are currently 3 defined environment names that you need to know: @@ -179,7 +179,7 @@ Those environments are tied to jobs that use [Auto Deploy](#auto-deploy), so except for the environment scope, they would also need to have a different domain they would be deployed to. This is why you need to define a separate `KUBE_INGRESS_BASE_DOMAIN` variable for all the above -[based on the environment](../../ci/variables/README.md#limiting-environment-scopes-of-variables). +[based on the environment](https://docs.gitlab.com/ee/ci/variables/index.html#limiting-environment-scopes-of-variables-premium). The following table is an example of how the three different clusters would be configured. @@ -188,7 +188,7 @@ be configured. | ------------ | -------------- | ----------------------------- | ------------- | ------ | | review | `review/*` | `review.example.com` | `review/*` | The review cluster which will run all [Review Apps](../../ci/review_apps/index.md). `*` is a wildcard, which means it will be used by every environment name starting with `review/`. | | staging | `staging` | `staging.example.com` | `staging` | (Optional) The staging cluster which will run the deployments of the staging environments. You need to [enable it first](#deploy-policy-for-staging-and-production-environments). | -| production | `production` | `example.com` | `production` | The production cluster which will run the deployments of the production environment. You can use [incremental rollouts](#incremental-rollout-to-production). | +| production | `production` | `example.com` | `production` | The production cluster which will run the deployments of the production environment. You can use [incremental rollouts](#incremental-rollout-to-production-premium). | To add a different cluster for each environment: @@ -211,8 +211,7 @@ other environments. NOTE: **Note:** From GitLab 11.8, `KUBE_INGRESS_BASE_DOMAIN` replaces `AUTO_DEVOPS_DOMAIN`. -`AUTO_DEVOPS_DOMAIN` [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959) -in GitLab 12.0. +`AUTO_DEVOPS_DOMAIN` [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). ## Enabling/Disabling Auto DevOps @@ -270,12 +269,12 @@ The available options are: - **Continuous deployment to production**: Enables [Auto Deploy](#auto-deploy) with `master` branch directly deployed to production. - **Continuous deployment to production using timed incremental rollout**: Sets the - [`INCREMENTAL_ROLLOUT_MODE`](#timed-incremental-rollout-to-production) variable + [`INCREMENTAL_ROLLOUT_MODE`](#timed-incremental-rollout-to-production-premium) variable to `timed`, and production deployment will be executed with a 5 minute delay between each increment in rollout. - **Automatic deployment to staging, manual deployment to production**: Sets the [`STAGING_ENABLED`](#deploy-policy-for-staging-and-production-environments) and - [`INCREMENTAL_ROLLOUT_MODE`](#incremental-rollout-to-production) variables + [`INCREMENTAL_ROLLOUT_MODE`](#incremental-rollout-to-production-premium) variables to `1` and `manual`. This means: - `master` branch is directly deployed to staging. @@ -504,7 +503,7 @@ Auto Deploy doesn't include deployments to staging or canary by default, but the [Auto DevOps template] contains job definitions for these tasks if you want to enable them. -You can make use of [environment variables](#helm-chart-variables) to automatically +You can make use of [environment variables](#environment-variables) to automatically scale your pod replicas. It's important to note that when a project is deployed to a Kubernetes cluster, @@ -554,7 +553,7 @@ Herokuish](https://github.com/gliderlabs/herokuish#paths) > [Introduced][ce-19507] in GitLab 11.0. -For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md###gitlab-deploy-token) +For internal and private projects a [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token) will be automatically created, when Auto DevOps is enabled and the Auto DevOps settings are saved. This Deploy Token can be used for permanent access to the registry. @@ -582,7 +581,7 @@ The metrics include: In order to make use of monitoring you need to: -1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster +1. [Deploy Prometheus](../../user/project/integrations/prometheus.md) into your Kubernetes cluster 1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/kubernetes/ingress-nginx/blob/master/docs/examples/customization/custom-vts-metrics-prometheus/nginx-vts-metrics-conf.yaml). @@ -685,7 +684,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | **Variable** | **Description** | | ------------ | --------------- | -| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-domain). By default, set automatically by the [Auto DevOps setting](#enabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959) in GitLab 12.0. Use `KUBE_INGRESS_BASE_DOMAIN` instead. | +| `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-base-domain). By default, set automatically by the [Auto DevOps setting](#enablingdisabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). Use `KUBE_INGRESS_BASE_DOMAIN` instead. | | `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/charts/auto-deploy-app). | | `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | @@ -704,8 +703,8 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `DB_INITIALIZE` | From GitLab 11.4, this variable can be used to specify the command to run to initialize the application's PostgreSQL database. It runs inside the application pod. | | `DB_MIGRATE` | From GitLab 11.4, this variable can be used to specify the command to run to migrate the application's PostgreSQL database. It runs inside the application pod. | | `STAGING_ENABLED` | From GitLab 10.8, this variable can be used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). | -| `CANARY_ENABLED` | From GitLab 11.0, this variable can be used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments). | -| `INCREMENTAL_ROLLOUT_MODE`| From GitLab 11.4, this variable, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production) of your application for the production environment.<br/>Set to: <ul><li>`manual`, for manual deployment jobs.</li><li>`timed`, for automatic rollout deployments with a 5 minute delay each one.</li></ul> | +| `CANARY_ENABLED` | From GitLab 11.0, this variable can be used to define a [deploy policy for canary environments](#deploy-policy-for-canary-environments-premium). | +| `INCREMENTAL_ROLLOUT_MODE`| From GitLab 11.4, this variable, if present, can be used to enable an [incremental rollout](#incremental-rollout-to-production-premium) of your application for the production environment.<br/>Set to: <ul><li>`manual`, for manual deployment jobs.</li><li>`timed`, for automatic rollout deployments with a 5 minute delay each one.</li></ul> | | `TEST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `test` job. If the variable is present, the job will not be created. | | `CODE_QUALITY_DISABLED` | From GitLab 11.0, this variable can be used to disable the `codequality` job. If the variable is present, the job will not be created. | | `SAST_DISABLED` | From GitLab 11.0, this variable can be used to disable the `sast` job. If the variable is present, the job will not be created. | @@ -939,7 +938,7 @@ TIP: **Tip:** You can also set this inside your [project's settings](#deployment-strategy). This configuration based on -[incremental rollout to production](#incremental-rollout-to-production). +[incremental rollout to production](#incremental-rollout-to-production-premium). Everything behaves the same way, except: diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 9749bd63f2b..367e192b85a 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -159,15 +159,15 @@ In the **test** stage, GitLab runs various checks on the application: - The `test` job runs unit and integration tests by detecting the language and framework ([Auto Test](index.md#auto-test)) - The `code_quality` job checks the code quality and is allowed to fail - ([Auto Code Quality](index.md#auto-code-quality)) **[STARTER]** + ([Auto Code Quality](index.md#auto-code-quality-starter)) **[STARTER]** - The `container_scanning` job checks the Docker container if it has any vulnerabilities and is allowed to fail ([Auto Container Scanning](index.md#auto-container-scanning)) - The `dependency_scanning` job checks if the application has any dependencies - susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning)) **[ULTIMATE]** + susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning-ultimate)) **[ULTIMATE]** - The `sast` job runs static analysis on the current code to check for potential - security issues and is allowed to fail([Auto SAST](index.md#auto-sast)) **[ULTIMATE]** + security issues and is allowed to fail([Auto SAST](index.md#auto-sast-ultimate)) **[ULTIMATE]** - The `license_management` job searches the application's dependencies to determine each of their - licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management)) **[ULTIMATE]** + licenses and is allowed to fail ([Auto License Management](index.md#auto-license-management-ultimate)) **[ULTIMATE]** NOTE: **Note:** As you might have noticed, all jobs except `test` are allowed to fail in the @@ -178,7 +178,7 @@ deploys the application in Kubernetes ([Auto Deploy](index.md#auto-deploy)). Lastly, in the **performance** stage, some performance tests will run on the deployed application -([Auto Browser Performance Testing](index.md#auto-browser-performance-testing)). **[PREMIUM]** +([Auto Browser Performance Testing](index.md#auto-browser-performance-testing-premium)). **[PREMIUM]** --- @@ -285,8 +285,8 @@ all within GitLab. Despite its automatic nature, Auto DevOps can also be configu and customized to fit your workflow. Here are some helpful resources for further reading: 1. [Auto DevOps](index.md) -1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters) **[PREMIUM]** -1. [Incremental rollout to production](index.md#incremental-rollout-to-production) **[PREMIUM]** +1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters-premium) **[PREMIUM]** +1. [Incremental rollout to production](index.md#incremental-rollout-to-production-premium) **[PREMIUM]** 1. [Disable jobs you don't need with environment variables](index.md#environment-variables) 1. [Use a static IP for your cluster](../../user/project/clusters/index.md#using-a-static-ip) 1. [Use your own buildpacks to build your application](index.md#custom-buildpacks) diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 7195b0f0f04..8a8021dc36d 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -45,7 +45,6 @@ Here's what we'll cover in this tutorial: - [How to modify history](#how-modifying-history-is-done) - [How to remove sensitive information from repository](#deleting-sensitive-information-from-commits) - ### Branching strategy [Git][git-official] is a de-centralized version control system, which means that beside regular @@ -64,14 +63,12 @@ prevent that anything is lost or out of sync when feature is complete. You can a read through this blog post on [Git Tips & Tricks][gitlab-git-tips-n-tricks] to learn how to easily **do** things in Git. - ## Undo local changes Until you push your changes to any remote repository, they will only affect you. That broadens your options on how to handle undoing them. Still, local changes can be on various stages and each stage has a different approach on how to tackle them. - ### Unstaged local changes (before you commit) When a change is made, but it is not added to the staged tree, Git itself @@ -315,7 +312,6 @@ In case you want to modify something introduced in commit `B`. You can find some more examples in [below section where we explain how to modify history](#how-modifying-history-is-done) - ### Redoing the Undo Sometimes you realize that the changes you undid were useful and you want them @@ -396,8 +392,8 @@ a nicer history of your contribution. Keep in mind that this also removes the comments attached to certain commits in merge requests, so if you need to retain traceability in GitLab, then modifying history is not acceptable. -A feature-branch of a merge request is a public branch and might be used by -other developers, but project process and rules might allow or require +A feature-branch of a merge request is a public branch and might be used by +other developers, but project process and rules might allow or require you to use `git rebase` (command that changes history) to reduce number of displayed commits on target branch after reviews are done (for example GitLab). There is a `git merge --squash` command which does exactly that diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 404a686f1cf..254e234a22c 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -41,7 +41,7 @@ Objects (usually binary and large) created by a build process. These can include ### Atlassian -A [company](https://www.atlassian.com) that develops software products for developers and project managers including Bitbucket, Jira, Hipchat, Confluence, Bamboo. +A [company](https://www.atlassian.com) that develops software products for developers and project managers including Bitbucket, Jira, Confluence, Bamboo. ### Audit Log @@ -706,4 +706,3 @@ Files that have been modified but are not committed. Check them by using the com ### YAML A human-readable data serialization [language](http://www.yaml.org/about.html) that takes concepts from programming languages such as C, Perl, and Python, and ideas from XML and the data format of electronic mail. - diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index 77a1892b656..b4ba5b7a24e 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -80,7 +80,6 @@ our newly created VPC.  - ### Internet Gateway Now still on the same dashboard head over to Internet Gateways and @@ -238,7 +237,6 @@ running reconfigure we need to make sure all our services are tied down so just leave the reconfigure command until after we edit our gitlab.rb file. - ### Extension for PostgreSQL Connect to your new RDS instance to verify access and to install @@ -277,8 +275,6 @@ username, and password. Next, we only need to configure the Redis section by adding the host and uncommenting the port. - - The last configuration step is to [change the default file locations ](http://docs.gitlab.com/ee/administration/high_availability/nfs.html) to make the EFS integration easier to manage. @@ -344,7 +340,6 @@ text area that allows us to add a lot of custom configurations which allows you to add a custom script for when launching an instance. Let's add the following script to the User Data section: - #cloud-config package_upgrade: true packages: diff --git a/doc/university/support/README.md b/doc/university/support/README.md index 805af253367..feb90ae9bad 100644 --- a/doc/university/support/README.md +++ b/doc/university/support/README.md @@ -2,7 +2,6 @@ comments: false --- - # Support Boot Camp **Goal:** Prepare new Service Engineers at GitLab diff --git a/doc/university/training/end-user/README.md b/doc/university/training/end-user/README.md index 53578a34d1c..60c0eadc572 100644 --- a/doc/university/training/end-user/README.md +++ b/doc/university/training/end-user/README.md @@ -2,7 +2,6 @@ comments: false --- - # Training This training material is the markdown used to generate training slides @@ -205,7 +204,6 @@ git push origin squash_some_bugs - Anyone can comment, not just the assignee - Push corrections to the same branch - --- ### Merge request example @@ -395,7 +393,6 @@ git revert vs git reset Reset removes the commit while revert removes the changes but leaves the commit Revert is safer considering we can revert a revert - # Changed file git commit -am "bug introduced" git revert HEAD diff --git a/doc/university/training/topics/git_log.md b/doc/university/training/topics/git_log.md index 127fdf4d44a..763ef802a04 100644 --- a/doc/university/training/topics/git_log.md +++ b/doc/university/training/topics/git_log.md @@ -40,7 +40,6 @@ Git log lists commit history. It allows searching and filtering. git log --since=1.month.ago --until=3.weeks.ago ``` - ---------- ## Git Log Workflow diff --git a/doc/university/training/topics/rollback_commits.md b/doc/university/training/topics/rollback_commits.md index ca3a64e4347..96b89e3319a 100644 --- a/doc/university/training/topics/rollback_commits.md +++ b/doc/university/training/topics/rollback_commits.md @@ -51,7 +51,6 @@ comments: false 1. Pull for updates 1. Push changes - ---------- ## Commands diff --git a/doc/update/10.0-to-10.1.md b/doc/update/10.0-to-10.1.md index d4373ca3f23..8514aa13f48 100644 --- a/doc/update/10.0-to-10.1.md +++ b/doc/update/10.0-to-10.1.md @@ -1,360 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.0 to 10.1 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.5.tar.gz -echo '3247e217d6745c27ef23bdc77b6abdb4b57a118f ruby-2.3.5.tar.gz' | shasum -c - && tar xzf ruby-2.3.5.tar.gz -cd ruby-2.3.5 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-1-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-1-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-0-stable:config/gitlab.yml.example origin/10-1-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-0-stable:lib/support/nginx/gitlab-ssl origin/10-1-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-0-stable:lib/support/nginx/gitlab origin/10-1-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-1-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-1-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-0-stable:lib/support/init.d/gitlab.default.example origin/10-1-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 9.5 to 10.0](9.5-to-10.0.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-1-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-1-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.1-to-10.2.md b/doc/update/10.1-to-10.2.md index 0705b58ed7a..8514aa13f48 100644 --- a/doc/update/10.1-to-10.2.md +++ b/doc/update/10.1-to-10.2.md @@ -1,360 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.1 to 10.2 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.5.tar.gz -echo '3247e217d6745c27ef23bdc77b6abdb4b57a118f ruby-2.3.5.tar.gz' | shasum -c - && tar xzf ruby-2.3.5.tar.gz -cd ruby-2.3.5 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-2-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-2-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-1-stable:config/gitlab.yml.example origin/10-2-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-1-stable:lib/support/nginx/gitlab-ssl origin/10-2-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-1-stable:lib/support/nginx/gitlab origin/10-2-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-2-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-2-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-1-stable:lib/support/init.d/gitlab.default.example origin/10-2-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.0 to 10.1](10.0-to-10.1.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-2-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-2-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.2-to-10.3.md b/doc/update/10.2-to-10.3.md index 33a52d3e807..8514aa13f48 100644 --- a/doc/update/10.2-to-10.3.md +++ b/doc/update/10.2-to-10.3.md @@ -1,359 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.2 to 10.3 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.5.tar.gz -echo '3247e217d6745c27ef23bdc77b6abdb4b57a118f ruby-2.3.5.tar.gz' | shasum -c - && tar xzf ruby-2.3.5.tar.gz -cd ruby-2.3.5 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets. -We require a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-3-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-3-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-2-stable:config/gitlab.yml.example origin/10-3-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-2-stable:lib/support/nginx/gitlab-ssl origin/10-3-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-2-stable:lib/support/nginx/gitlab origin/10-3-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-3-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-3-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-2-stable:lib/support/init.d/gitlab.default.example origin/10-3-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.1 to 10.2](10.1-to-10.2.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-3-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-3-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.3-to-10.4.md b/doc/update/10.3-to-10.4.md index 3ba96535965..8514aa13f48 100644 --- a/doc/update/10.3-to-10.4.md +++ b/doc/update/10.3-to-10.4.md @@ -1,361 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.3 to 10.4 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.6.tar.gz -echo '4e6a0f828819e15d274ae58485585fc8b7caace0 ruby-2.3.6.tar.gz' | shasum -c - && tar xzf ruby-2.3.6.tar.gz -cd ruby-2.3.6 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets. -We require a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-4-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-4-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-3-stable:config/gitlab.yml.example origin/10-4-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-3-stable:lib/support/nginx/gitlab-ssl origin/10-4-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-3-stable:lib/support/nginx/gitlab origin/10-4-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-4-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-4-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-3-stable:lib/support/init.d/gitlab.default.example origin/10-4-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.2 to 10.3](10.2-to-10.3.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-4-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-4-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.4-to-10.5.md b/doc/update/10.4-to-10.5.md index f00bbcaeaa6..8514aa13f48 100644 --- a/doc/update/10.4-to-10.5.md +++ b/doc/update/10.4-to-10.5.md @@ -1,361 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.4 to 10.5 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.6.tar.gz -echo '4e6a0f828819e15d274ae58485585fc8b7caace0 ruby-2.3.6.tar.gz' | shasum -c - && tar xzf ruby-2.3.6.tar.gz -cd ruby-2.3.6 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets. -We require a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-5-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-4-stable:config/gitlab.yml.example origin/10-5-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-4-stable:lib/support/nginx/gitlab-ssl origin/10-5-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-4-stable:lib/support/nginx/gitlab origin/10-5-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-5-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-5-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-4-stable:lib/support/init.d/gitlab.default.example origin/10-5-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.4) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.3 to 10.4](10.3-to-10.4.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-5-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-5-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.5-to-10.6.md b/doc/update/10.5-to-10.6.md index 6c3f8b663cc..8514aa13f48 100644 --- a/doc/update/10.5-to-10.6.md +++ b/doc/update/10.5-to-10.6.md @@ -1,361 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.5 to 10.6 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.6.tar.gz -echo '4e6a0f828819e15d274ae58485585fc8b7caace0 ruby-2.3.6.tar.gz' | shasum -c - && tar xzf ruby-2.3.6.tar.gz -cd ruby-2.3.6 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-6-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-5-stable:config/gitlab.yml.example origin/10-6-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-5-stable:lib/support/nginx/gitlab-ssl origin/10-6-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-5-stable:lib/support/nginx/gitlab origin/10-6-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-6-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-6-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-5-stable:lib/support/init.d/gitlab.default.example origin/10-6-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.5) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.4 to 10.5](10.4-to-10.5.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-6-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-6-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.6-to-10.7.md b/doc/update/10.6-to-10.7.md index 9bd354a5bcd..8514aa13f48 100644 --- a/doc/update/10.6-to-10.7.md +++ b/doc/update/10.6-to-10.7.md @@ -1,361 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.6 to 10.7 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.6.tar.gz -echo '4e6a0f828819e15d274ae58485585fc8b7caace0 ruby-2.3.6.tar.gz' | shasum -c - && tar xzf ruby-2.3.6.tar.gz -cd ruby-2.3.6 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.9 and dropped support for Go -1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.9.linux-amd64.tar.gz -echo 'd70eadefce8e160638a9a6db97f7192d8463069ab33138893ad3bf31b0650a79 go1.9.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.9.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.9.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-7-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-6-stable:config/gitlab.yml.example origin/10-7-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-6-stable:lib/support/nginx/gitlab-ssl origin/10-7-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-6-stable:lib/support/nginx/gitlab origin/10-7-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-7-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-7-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-6-stable:lib/support/init.d/gitlab.default.example origin/10-7-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.6) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.5 to 10.6](10.5-to-10.6.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-7-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-7-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.7-to-10.8.md b/doc/update/10.7-to-10.8.md index 9aafd3f269f..8514aa13f48 100644 --- a/doc/update/10.7-to-10.8.md +++ b/doc/update/10.7-to-10.8.md @@ -1,362 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.7 to 10.8 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.7.tar.gz -echo '540996fec64984ab6099e34d2f5820b14904f15a ruby-2.3.7.tar.gz' | shasum -c - && tar xzf ruby-2.3.7.tar.gz -cd ruby-2.3.7 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-8-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-7-stable:config/gitlab.yml.example origin/10-8-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-7-stable:lib/support/nginx/gitlab-ssl origin/10-8-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-7-stable:lib/support/nginx/gitlab origin/10-8-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-7-stable:lib/support/init.d/gitlab.default.example origin/10-8-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.7) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.6 to 10.7](10.6-to-10.7.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-8-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/10.8-to-11.0.md b/doc/update/10.8-to-11.0.md index f6fdc342e3d..8514aa13f48 100644 --- a/doc/update/10.8-to-11.0.md +++ b/doc/update/10.8-to-11.0.md @@ -1,361 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 10.8 to 11.0 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-0-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz -echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz -cd ruby-2.4.4 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.0 and higher only supports Go 1.9.x and newer, and dropped support for Go -1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz -echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-0-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-0-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/10-8-stable:config/gitlab.yml.example origin/11-0-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/10-8-stable:lib/support/nginx/gitlab-ssl origin/11-0-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/10-8-stable:lib/support/nginx/gitlab origin/11-0-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-0-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-0-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/10-8-stable:lib/support/init.d/gitlab.default.example origin/11-0-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (10.8) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.7 to 10.8](10.7-to-10.8.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-0-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-0-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.0-to-11.1.md b/doc/update/11.0-to-11.1.md index 25a7c1cf929..8514aa13f48 100644 --- a/doc/update/11.0-to-11.1.md +++ b/doc/update/11.0-to-11.1.md @@ -1,378 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.0 to 11.1 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-1-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz -echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz -cd ruby-2.4.4 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.0 and higher only supports Go 1.9.x and newer, and dropped support for Go -1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz -echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-1-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-1-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages. - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-0-stable:config/gitlab.yml.example origin/11-1-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-0-stable:lib/support/nginx/gitlab-ssl origin/11-1-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-0-stable:lib/support/nginx/gitlab origin/11-1-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-1-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-1-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-0-stable:lib/support/init.d/gitlab.default.example origin/11-1-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 10.8 to 11.0](10.8-to-11.0.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-1-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-1-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.1-to-11.2.md b/doc/update/11.1-to-11.2.md index ced59c245b8..8514aa13f48 100644 --- a/doc/update/11.1-to-11.2.md +++ b/doc/update/11.1-to-11.2.md @@ -1,378 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.1 to 11.2 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-2-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz -echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz -cd ruby-2.4.4 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.0 and higher only supports Go 1.9.x and newer, and dropped support for Go -1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz -echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-2-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-2-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages. - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-1-stable:config/gitlab.yml.example origin/11-2-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-1-stable:lib/support/nginx/gitlab-ssl origin/11-2-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-1-stable:lib/support/nginx/gitlab origin/11-2-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-2-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-2-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-1-stable:lib/support/init.d/gitlab.default.example origin/11-2-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.0 to 11.1](11.0-to-11.1.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-2-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-2-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.2-to-11.3.md b/doc/update/11.2-to-11.3.md index fa0c6872182..8514aa13f48 100644 --- a/doc/update/11.2-to-11.3.md +++ b/doc/update/11.2-to-11.3.md @@ -1,378 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.2 to 11.3 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-3-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.4.tar.gz -echo 'ec82b0d53bd0adad9b19e6b45e44d54e9ec3f10c ruby-2.4.4.tar.gz' | shasum -c - && tar xzf ruby-2.4.4.tar.gz -cd ruby-2.4.4 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.0 and higher only supports Go 1.9.x and newer, and dropped support for Go -1.5.x through 1.8.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz -echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-3-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-3-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages. - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-2-stable:config/gitlab.yml.example origin/11-3-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-2-stable:lib/support/nginx/gitlab-ssl origin/11-3-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-2-stable:lib/support/nginx/gitlab origin/11-3-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-2-stable:lib/support/init.d/gitlab.default.example origin/11-3-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.1 to 11.2](11.1-to-11.2.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-3-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.3-to-11.4.md b/doc/update/11.3-to-11.4.md index 18bbfe4747e..8514aa13f48 100644 --- a/doc/update/11.3-to-11.4.md +++ b/doc/update/11.3-to-11.4.md @@ -1,378 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.3 to 11.4 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-4-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz -echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz -cd ruby-2.4.5 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go -1.9.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.3.linux-amd64.tar.gz -echo 'fa1b0e45d3b647c252f51f5e1204aba049cde4af177ef9f2181f43004f901035 go1.10.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-4-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-4-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages. - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-3-stable:config/gitlab.yml.example origin/11-4-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-3-stable:lib/support/nginx/gitlab-ssl origin/11-4-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-3-stable:lib/support/nginx/gitlab origin/11-4-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-3-stable:lib/support/init.d/gitlab.default.example origin/11-4-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.2 to 11.3](11.2-to-11.3.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-4-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.4-to-11.5.md b/doc/update/11.4-to-11.5.md index 8f588f8b2ae..8514aa13f48 100644 --- a/doc/update/11.4-to-11.5.md +++ b/doc/update/11.4-to-11.5.md @@ -1,390 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.4 to 11.5 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-5-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.4/ruby-2.4.5.tar.gz -echo '4d650f302f1ec00256450b112bb023644b6ab6dd ruby-2.4.5.tar.gz' | shasum -c - && tar xzf ruby-2.4.5.tar.gz -cd ruby-2.4.5 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go -1.9.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.5.linux-amd64.tar.gz -echo 'a035d9beda8341b645d3f45a1b620cf2d8fb0c5eb409be36b389c0fd384ecc3a go1.10.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.5.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.5.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-5-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages. - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New `unicorn.rb` configuration - -Note: we have made [changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22372) to `unicorn.rb` to allow GitLab run with both Unicorn and Puma in future. - -- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/unicorn.rb.example> but with your settings. - - In particular, make sure that `require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"` line exists and the `before_exec`, `before_fork`, and `after_fork` handlers are configured as shown below: - -```ruby -require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events" - -before_exec do |server| - # Signal application hooks that we're about to restart - Gitlab::Cluster::LifecycleEvents.do_master_restart -end - -before_fork do |server, worker| - # Signal application hooks that we're about to fork - Gitlab::Cluster::LifecycleEvents.do_before_fork -end - -after_fork do |server, worker| - # Signal application hooks of worker start - Gitlab::Cluster::LifecycleEvents.do_worker_start -end -``` - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-4-stable:config/gitlab.yml.example origin/11-5-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-4-stable:lib/support/nginx/gitlab-ssl origin/11-5-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-4-stable:lib/support/nginx/gitlab origin/11-5-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-4-stable:lib/support/init.d/gitlab.default.example origin/11-5-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.4) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.3 to 11.4](11.3-to-11.4.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-5-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.5-to-11.6.md b/doc/update/11.5-to-11.6.md index f95ce54650e..8514aa13f48 100644 --- a/doc/update/11.5-to-11.6.md +++ b/doc/update/11.5-to-11.6.md @@ -1,390 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.5 to 11.6 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-6-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 11.0 and higher only support Ruby 2.4.x and dropped support for Ruby 2.3.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.5/ruby-2.5.3.tar.gz -echo 'f919a9fbcdb7abecd887157b49833663c5c15fda ruby-2.5.3.tar.gz' | shasum -c - && tar xzf ruby-2.5.3.tar.gz -cd ruby-2.5.3 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.2.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go -1.9.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.5.linux-amd64.tar.gz -echo 'a035d9beda8341b645d3f45a1b620cf2d8fb0c5eb409be36b389c0fd384ecc3a go1.10.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.5.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.5.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-6-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New `unicorn.rb` configuration - -We have made [changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22372) to `unicorn.rb` to allow GitLab run with both Unicorn and Puma in future. - -Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/11-6-stable/config/unicorn.rb.example> but with your settings. -In particular, make sure that `require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"` line exists and the `before_exec`, `before_fork`, and `after_fork` handlers are configured as shown below: - -```ruby -require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events" - -before_exec do |server| - # Signal application hooks that we're about to restart - Gitlab::Cluster::LifecycleEvents.do_master_restart -end - -before_fork do |server, worker| - # Signal application hooks that we're about to fork - Gitlab::Cluster::LifecycleEvents.do_before_fork -end - -after_fork do |server, worker| - # Signal application hooks of worker start - Gitlab::Cluster::LifecycleEvents.do_worker_start -end -``` - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-5-stable:config/gitlab.yml.example origin/11-6-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-5-stable:lib/support/nginx/gitlab-ssl origin/11-6-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-5-stable:lib/support/nginx/gitlab origin/11-6-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-6-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-6-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-5-stable:lib/support/init.d/gitlab.default.example origin/11-6-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --deployment --without development test mysql aws kerberos - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --deployment --without development test postgres aws kerberos - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.5) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.4 to 11.5](11.4-to-11.5.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-6-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-6-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.6-to-11.7.md b/doc/update/11.6-to-11.7.md index b4d830e8ce0..8514aa13f48 100644 --- a/doc/update/11.6-to-11.7.md +++ b/doc/update/11.6-to-11.7.md @@ -1,390 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.6 to 11.7 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-7-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: Beginning in GitLab 11.0, we only support Ruby 2.4 or higher, and dropped -support for Ruby 2.3. Be sure to upgrade if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.5/ruby-2.5.3.tar.gz -echo 'f919a9fbcdb7abecd887157b49833663c5c15fda ruby-2.5.3.tar.gz' | shasum -c - && tar xzf ruby-2.5.3.tar.gz -cd ruby-2.5.3 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v6.0.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v6.0.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.10.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go -1.9.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.5.linux-amd64.tar.gz -echo 'a035d9beda8341b645d3f45a1b620cf2d8fb0c5eb409be36b389c0fd384ecc3a go1.10.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.5.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.5.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-7-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New `unicorn.rb` configuration - -We have made [changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22372) to `unicorn.rb` to allow GitLab run with both Unicorn and Puma in future. - -Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/11-7-stable/config/unicorn.rb.example> but with your settings. -In particular, make sure that `require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"` line exists and the `before_exec`, `before_fork`, and `after_fork` handlers are configured as shown below: - -```ruby -require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events" - -before_exec do |server| - # Signal application hooks that we're about to restart - Gitlab::Cluster::LifecycleEvents.do_master_restart -end - -before_fork do |server, worker| - # Signal application hooks that we're about to fork - Gitlab::Cluster::LifecycleEvents.do_before_fork -end - -after_fork do |server, worker| - # Signal application hooks of worker start - Gitlab::Cluster::LifecycleEvents.do_worker_start -end -``` - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-6-stable:config/gitlab.yml.example origin/11-7-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-6-stable:lib/support/nginx/gitlab-ssl origin/11-7-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-6-stable:lib/support/nginx/gitlab origin/11-7-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-7-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-7-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-6-stable:lib/support/init.d/gitlab.default.example origin/11-7-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --deployment --without development test mysql aws kerberos - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --deployment --without development test postgres aws kerberos - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.6) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.5 to 11.6](11.5-to-11.6.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-7-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-7-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/11.7-to-11.8.md b/doc/update/11.7-to-11.8.md index d5cd557d7b5..8514aa13f48 100644 --- a/doc/update/11.7-to-11.8.md +++ b/doc/update/11.7-to-11.8.md @@ -1,394 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 11.7 to 11.8 - -Make sure you view this update guide from the branch (version) of GitLab you would -like to install (e.g., `11-8-stable`. You can select the branch in the version -dropdown at the top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -NOTE: If you installed GitLab from source, make sure `rsync` is installed. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: Beginning in GitLab 11.0, we only support Ruby 2.4 or higher, and dropped -support for Ruby 2.3. Be sure to upgrade if necessary. - -You can check which version you are running with `ruby -v`. - -Download Ruby and compile it: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.5/ruby-2.5.3.tar.gz -echo 'f919a9fbcdb7abecd887157b49833663c5c15fda ruby-2.5.3.tar.gz' | shasum -c - && tar xzf ruby-2.5.3.tar.gz -cd ruby-2.5.3 - -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -NOTE: Beginning in GitLab 11.8, we only support node 8 or higher, and dropped -support for node 6. Be sure to upgrade if necessary. - -GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. -This requires a minimum version of node v8.10.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v8.10.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -GitLab also requires the use of yarn `>= v1.10.0` to manage JavaScript -dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go -1.9.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://dl.google.com/go/go1.10.5.linux-amd64.tar.gz -echo 'a035d9beda8341b645d3f45a1b620cf2d8fb0c5eb409be36b389c0fd384ecc3a go1.10.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.10.5.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.10.5.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all --prune -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 11-8-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.1 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update gitlab-pages - -#### Only needed if you use GitLab Pages - -Install and compile gitlab-pages. GitLab-Pages uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-pages - -sudo -u git -H git fetch --all --tags --prune -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) -sudo -u git -H make -``` - -### 11. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 12. Update configuration files - -#### New `unicorn.rb` configuration - -We have made [changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22372) to `unicorn.rb` to allow GitLab run with both Unicorn and Puma in future. - -Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/config/unicorn.rb.example> but with your settings. -In particular, make sure that `require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events"` line exists and the `before_exec`, `before_fork`, and `after_fork` handlers are configured as shown below: - -```ruby -require_relative "/home/git/gitlab/lib/gitlab/cluster/lifecycle_events" - -before_exec do |server| - # Signal application hooks that we're about to restart - Gitlab::Cluster::LifecycleEvents.do_master_restart -end - -before_fork do |server, worker| - # Signal application hooks that we're about to fork - Gitlab::Cluster::LifecycleEvents.do_before_fork -end - -after_fork do |server, worker| - # Signal application hooks of worker start - Gitlab::Cluster::LifecycleEvents.do_worker_start -end -``` - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/11-7-stable:config/gitlab.yml.example origin/11-8-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/11-7-stable:lib/support/nginx/gitlab-ssl origin/11-8-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/11-7-stable:lib/support/nginx/gitlab origin/11-8-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/11-7-stable:lib/support/init.d/gitlab.default.example origin/11-8-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 13. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --deployment --without development test mysql aws kerberos - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --deployment --without development test postgres aws kerberos - - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 14. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 15. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (11.7) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 11.6 to 11.7](11.6-to-11.7.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/11-8-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/2.6-to-3.0.md b/doc/update/2.6-to-3.0.md index 8f18bd93cea..8514aa13f48 100644 --- a/doc/update/2.6-to-3.0.md +++ b/doc/update/2.6-to-3.0.md @@ -1,70 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 2.6 to 3.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/2.6-to-3.0.md) for the most up to date instructions.* - -## 1. Stop server & resque - - sudo service gitlab stop - -## 2. Update code & db - - -```bash -# Get latest code -git fetch origin -git checkout v3.0.3 - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u gitlab -H vim Gemfile - -# Install libs -sudo -u gitlab bundle install --without development test postgres - -# update db -sudo -u gitlab bundle exec rake db:migrate RAILS_ENV=production - -# !!! Config should be replaced with a new one. Check it after replace -cp config/gitlab.yml.example config/gitlab.yml - -# update Gitolite hooks - -# Gitolite v2: -sudo cp ./lib/hooks/post-receive /home/git/share/gitolite/hooks/common/post-receive -sudo chown git:git /home/git/share/gitolite/hooks/common/post-receive - -# Gitolite v3: -sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive -sudo chown git:git /home/git/.gitolite/hooks/common/post-receive - -# set valid path to hooks in gitlab.yml in git_host section -# like this -git_host: - # Gitolite 2 - hooks_path: /home/git/share/gitolite/hooks - # Gitolite 3 - hooks_path: /home/git/.gitolite/hooks/ - - -# Make some changes to Gitolite config -# For more information visit https://github.com/gitlabhq/gitlabhq/pull/1719 - -# Gitolite v2 -sudo -u git -H sed -i 's/\(GL_GITCONFIG_KEYS\s*=>*\s*\).\{2\}/\\1"\.\*"/g' /home/git/.gitolite.rc - -# gitlite v3 -sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\\1'\.\*'/g" /home/git/.gitolite.rc - - -# Check app status -sudo -u gitlab bundle exec rake gitlab:app:status RAILS_ENV=production - -``` - -## 3. Start all - - sudo service gitlab start +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/2.9-to-3.0.md b/doc/update/2.9-to-3.0.md index 6a3c2387683..8514aa13f48 100644 --- a/doc/update/2.9-to-3.0.md +++ b/doc/update/2.9-to-3.0.md @@ -1,46 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 2.9 to 3.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/2.9-to-3.0.md) for the most up to date instructions.* - -## 1. Stop server & resque - - sudo service gitlab stop - -## 2. Follow instructions - -```bash - -# Get latest code -sudo -u gitlab -H git fetch origin -sudo -u gitlab -H git checkout v3.0.3 - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u gitlab -H vim Gemfile - -# Install gems -sudo -u gitlab -H bundle install --without development test postgres - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -# Make some changes to gitolite v3 config -# For more information visit https://github.com/gitlabhq/gitlabhq/pull/1719 - -# Gitolite version 3 -sudo -u git -H sed -i "s/\(GIT_CONFIG_KEYS\s*=>*\s*\).\{2\}/\\1'\.\*'/g" /home/git/.gitolite.rc - -# If you still use gitolite v2 -sudo -u git -H sed -i 's/\(GL_GITCONFIG_KEYS\s*=>*\s*\).\{2\}/\\1"\.\*"/g' /home/git/.gitolite.rc - -# Check APP Status -sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production -``` - -## 3. Start all - - sudo service gitlab start +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/3.0-to-3.1.md b/doc/update/3.0-to-3.1.md index 1f25b8265c9..8514aa13f48 100644 --- a/doc/update/3.0-to-3.1.md +++ b/doc/update/3.0-to-3.1.md @@ -1,106 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 3.0 to 3.1 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/3.0-to-3.1.md) for the most up to date instructions.* - -**IMPORTANT!** - -In this release **we moved Resque jobs under own gitlab namespace** - -Despite a lot of advantages it requires from our users to **replace gitolite post-receive hook with new one**. - -Most of projects has post-receive file as symlink to gitolite `/home/git/.gitolite/hooks/post-receive`. But some of them may have a real file. In this case you should rewrite it with symlink to gitolite hook. - -I wrote a bash script which will do it automatically for you. Just make sure all path inside is valid for you - -## 1. Stop server & resque - - sudo service gitlab stop - -## 2. Update GitLab - -```bash -# Get latest code -sudo -u gitlab -H git fetch -sudo -u gitlab -H git checkout v3.1.0 - -# Install new charlock_holmes -sudo gem install charlock_holmes --version '0.6.9' - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u gitlab -H vim Gemfile - -# Install gems for MySQL -sudo -u gitlab -H bundle install --without development test postgres sqlite - - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -``` - -## 3. Update post-receive hooks - -### Gitolite 3 - -Step 1: Rewrite post-receive hook - -```bash -# Rewrite hook for gitolite 3 -sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive -sudo chown git:git /home/git/.gitolite/hooks/common/post-receive -``` - -Step 2: Rewrite hooks in all projects to symlink gitolite hook - -```bash -# 1. Check for valid path -sudo -u gitlab -H vim lib/support/rewrite-hooks.sh - -# 2. Run script -sudo -u git -H lib/support/rewrite-hooks.sh -``` - -### Gitolite v2 - -Step 1: rewrite post-receive hook for gitolite 2 - -``` -sudo cp ./lib/hooks/post-receive /home/git/share/gitolite/hooks/common/post-receive -sudo chown git:git /home/git/share/gitolite/hooks/common/post-receive -``` - -Step 2: Replace symlinks in project to valid place - - #!/bin/bash - src="/home/git/repositories" - for dir in `ls "$src/"` - do - if [ -d "$src/$dir" ]; then - - if [ "$dir" = "gitolite-admin.git" ] - then - continue - fi - - project_hook="$src/$dir/hooks/post-receive" - gitolite_hook="/home/git/share/gitolite/hooks/common/post-receive" - - ln -s -f $gitolite_hook $project_hook - fi - done - -## 4. Check app status - -```bash -# Check APP Status -sudo -u gitlab -H bundle exec rake gitlab:app:status RAILS_ENV=production -``` - -## 5. Start all - - sudo service gitlab start +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/3.1-to-4.0.md b/doc/update/3.1-to-4.0.md index 1a53ddeb4bd..8514aa13f48 100644 --- a/doc/update/3.1-to-4.0.md +++ b/doc/update/3.1-to-4.0.md @@ -1,99 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 3.1 to 4.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/3.1-to-4.0.md) for the most up to date instructions.* - -## Important changes - -- Support for SQLite was dropped -- Support for Gitolite 2 was dropped -- Projects are organized in namespaces -- The GitLab post-receive hook needs to be updated -- The configuration file needs to be updated -- Availability of `python2` executable - -Most of projects has post-receive file as symlink to Gitolite `/home/git/.gitolite/hooks/post-receive`. But some of them may have a real file. In this case you should rewrite it with symlink to Gitolite hook. - -I wrote a bash script which will do it automatically for you. Just make sure all path inside is valid for you - -## 1. Stop GitLab & Resque - - sudo service gitlab stop - -## 2. Update GitLab - -```bash - -# Get latest code -sudo -u gitlab -H git fetch -sudo -u gitlab -H git checkout 4-0-stable - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u gitlab -H vim Gemfile - -# Install gems for MySQL -sudo -u gitlab -H bundle install --without development test postgres - -# Update repos permissions -sudo chmod -R ug+rwXs /home/git/repositories/ -sudo chown -R git:git /home/git/repositories/ - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -# Enable namespaces (**Warning!** All projects in groups will be moved to subdirectories) -sudo -u gitlab -H bundle exec rake gitlab:enable_namespaces RAILS_ENV=production - -``` - -## 3. Update post-receive hooks (Requires Gitolite v3 ) - -Step 1: Rewrite post-receive hook - -```bash -sudo cp ./lib/hooks/post-receive /home/git/.gitolite/hooks/common/post-receive -sudo chown git:git /home/git/.gitolite/hooks/common/post-receive -``` - -Step 2: Update project hooks to be symlinks to the Gitolite hook - -```bash -# 1. Check paths in script -sudo -u gitlab -H vim lib/support/rewrite-hooks.sh - -# 2. Run script -sudo -u git -H lib/support/rewrite-hooks.sh -``` - -## 4. Replace config with new one - - # backup old one - sudo -u gitlab -H cp config/gitlab.yml config/gitlab.yml.old - - # copy new one - sudo -u gitlab -H cp config/gitlab.yml.example config/gitlab.yml - - # edit it - sudo -u gitlab -H vim config/gitlab.yml - -## 5. Disable ssh known_host check for own domain - - echo "Host localhost - StrictHostKeyChecking no - UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config - - echo "Host YOUR_DOMAIN_NAME - StrictHostKeyChecking no - UserKnownHostsFile=/dev/null" | sudo tee -a /etc/ssh/ssh_config - -## 6. Check GitLab's status - - sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production - -## 7. Start GitLab & Resque - - sudo service gitlab start +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/4.0-to-4.1.md b/doc/update/4.0-to-4.1.md index 40a133e796e..8514aa13f48 100644 --- a/doc/update/4.0-to-4.1.md +++ b/doc/update/4.0-to-4.1.md @@ -1,65 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 4.0 to 4.1 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/4.0-to-4.1.md) for the most up to date instructions.* - -## Important changes - -- Resque replaced with Sidekiq -- New options for configuration file added -- Init.d script should be updated -- **requires ruby1.9.3-p327** - -## 1. Stop GitLab & Resque - - sudo service gitlab stop - -## 2. Update GitLab - -```bash -# Set the working directory -cd /home/gitlab/gitlab/ - -# Get latest code -sudo -u gitlab -H git fetch -sudo -u gitlab -H git checkout 4-1-stable - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u gitlab -H vim Gemfile - -# Install gems for MySQL -sudo -u gitlab -H bundle install --without development test postgres - -# Migrate db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -``` - -## 3. Replace init.d script with a new one - -``` -# backup old one -sudo mv /etc/init.d/gitlab /etc/init.d/gitlab.old - -# get new one using sidekiq -sudo curl --location --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/4-1-stable/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab - -``` - -## 4. Check GitLab's status - - sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production - - -## 5. Start GitLab & Sidekiq - - sudo service gitlab start - -## 6. Remove old init.d script - - sudo rm /etc/init.d/gitlab.old +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/4.1-to-4.2.md b/doc/update/4.1-to-4.2.md index 1fd6c58bda7..8514aa13f48 100644 --- a/doc/update/4.1-to-4.2.md +++ b/doc/update/4.1-to-4.2.md @@ -1,48 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 4.1 to 4.2 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/4.1-to-4.2.md) for the most up to date instructions.* - -## 1. Stop server & Resque - - sudo service gitlab stop - -## 2. Update code & DB - -```bash - -#Set the working directory -cd /home/gitlab/gitlab/ - -# Get latest code -sudo -u gitlab -H git fetch - -sudo -u gitlab -H git checkout 4-2-stable - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u gitlab -H vim Gemfile - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u gitlab -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u gitlab -H bundle install --without development test postgres --deployment - -# update db -sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production - -``` - -## 3. Check GitLab's status - -```bash -sudo -u gitlab -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -## 4. Start all - - sudo service gitlab start +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/4.2-to-5.0.md b/doc/update/4.2-to-5.0.md index d292327efbd..8514aa13f48 100644 --- a/doc/update/4.2-to-5.0.md +++ b/doc/update/4.2-to-5.0.md @@ -1,224 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 4.2 to 5.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/4.2-to-5.0.md) for the most up to date instructions.* - -## Warning - -GitLab 5.0 is affected by critical security vulnerability CVE-2013-4490. - -## Important changes - -- We don't use `gitlab` user any more. Everything will be moved to `git` user -- Self signed SSL certificates are not supported until GitLab 5.1 -- **requires ruby1.9.3** - -## 0. Stop GitLab - - sudo service gitlab stop - -## 1. add bash to git user - -``` -sudo chsh -s /bin/bash git -``` - -## 2. git clone gitlab-shell - -``` -cd /home/git/ -sudo -u git -H git clone https://github.com/gitlabhq/gitlab-shell.git /home/git/gitlab-shell -``` - -## 3. set up gitlab-shell - -```bash -# chmod all repos and files under git -sudo chown git:git -R /home/git/repositories/ - -# login as git -sudo su git -cd /home/git/gitlab-shell -git checkout v1.1.0 - -# copy config -cp config.yml.example config.yml - -# change URL to GitLab instance -# ! make sure the URL ends with '/' like 'https://gitlab.example/' -vim config.yml - -# rewrite hooks -./support/rewrite-hooks.sh - -# check ruby version for git user ( 1.9 required!! ) -# GitLab shell requires system ruby 1.9 -ruby -v - -# exit from git user -exit -``` - -## 4. Copy GitLab instance to git user - -```bash -sudo cp -R /home/gitlab/gitlab /home/git/gitlab -sudo chown git:git -R /home/git/gitlab -sudo rm -rf /home/gitlab/gitlab-satellites - -# if exists -sudo rm /tmp/gitlab.socket -``` - -## 5. Update GitLab to recent version - -```bash -cd /home/git/gitlab - -# backup current config -sudo -u git -H cp config/gitlab.yml config/gitlab.yml.old - -sudo -u git -H git fetch -sudo -u git -H git checkout 5-0-stable - -# replace config with recent one -sudo -u git -H cp config/gitlab.yml.example config/gitlab.yml - -# edit it -sudo -u git -H vim config/gitlab.yml - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:shell:setup RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:shell:build_missing_projects RAILS_ENV=production - -sudo -u git -H mkdir -p /home/git/gitlab-satellites -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production - -# migrate wiki to git -sudo -u git -H bundle exec rake gitlab:wiki:migrate RAILS_ENV=production - - -# check permissions for /home/git/.ssh/ -sudo -u git -H chmod 700 /home/git/.ssh -sudo -u git -H chmod 600 /home/git/.ssh/authorized_keys - -# check permissions for /home/git/gitlab/ -sudo chown -R git /home/git/gitlab/log/ -sudo chown -R git /home/git/gitlab/tmp/ -sudo chmod -R u+rwX /home/git/gitlab/log/ -sudo chmod -R u+rwX /home/git/gitlab/tmp/ -sudo -u git -H mkdir -p /home/git/gitlab/tmp/pids/ -sudo chmod -R u+rwX /home/git/gitlab/tmp/pids - -``` - -## 6. Update init.d script and Nginx config - -```bash -# init.d -sudo rm /etc/init.d/gitlab -sudo curl --location --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/5-0-stable/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab - -# unicorn -sudo -u git -H cp /home/git/gitlab/config/unicorn.rb /home/git/gitlab/config/unicorn.rb.old -sudo -u git -H cp /home/git/gitlab/config/unicorn.rb.example /home/git/gitlab/config/unicorn.rb - -# Nginx -# Replace path from '/home/gitlab/' to '/home/git/' -sudo vim /etc/nginx/sites-enabled/gitlab -sudo service nginx restart - -``` - -## 7. Start GitLab instance - -``` -sudo service gitlab start - -# check if unicorn and sidekiq started -# If not try to logout, also check replaced path from '/home/gitlab/' to '/home/git/' -# in Nginx, unicorn, init.d etc -ps aux | grep unicorn -ps aux | grep sidekiq - -``` - -## 8. Check installation - - -```bash -# In 5-10 seconds lets check gitlab-shell -sudo -u git -H /home/git/gitlab-shell/bin/check - -# Example of success output -# Check GitLab API access: OK -# Check directories and files: -# /home/git/repositories: OK -# /home/git/.ssh/authorized_keys: OK - - -# Now check GitLab instance -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -``` - -## 9. Cleanup - -**If everything works as expected you can cleanup some old things** -Recommend you wait a bit and do a backup before completing the following. - -```bash -# remove GitLab user from system -sudo userdel -r gitlab - -cd /home/git - -# cleanup .profile -## remove text from .profile added during gitolite installation: -## PATH=\$PATH:/home/git/bin -## export PATH -## to see what a clean .profile for new users on your system would look like see /etc/skel/.profile -sudo -u git -H vim .profile - -# remove gitolite -sudo rm -R bin -sudo rm -Rf gitolite -sudo rm -R .gitolite -sudo rm .gitolite.rc -sudo rm -f gitlab.pub -sudo rm projects.list - -# reset tmp folders -sudo service gitlab stop -cd /home/git/gitlab -sudo rm -R tmp -sudo -u git -H mkdir tmp -sudo chmod -R u+rwX tmp/ - -# create directory for pids, make sure GitLab can write to it -sudo -u git -H mkdir tmp/pids/ -sudo chmod -R u+rwX tmp/pids/ - -# if you are already running a newer version of GitLab check that installation guide for other tmp folders you need to create - -# reboot system -sudo reboot - -# login, check that GitLab is running fine -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.0-to-5.1.md b/doc/update/5.0-to-5.1.md index 7067ea4c40c..8514aa13f48 100644 --- a/doc/update/5.0-to-5.1.md +++ b/doc/update/5.0-to-5.1.md @@ -1,105 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.0 to 5.1 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.0-to-5.1.md) for the most up to date instructions.* - -## Warning - -GitLab 5.1 is affected by critical security vulnerability CVE-2013-4490. - -## Release notes - -- `unicorn` replaced with `puma` -- merge request cached diff will be truncated - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-1-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.3.0 -# replace your old config with the new one -sudo -u git -H mv config.yml config.yml.old -sudo -u git -H cp config.yml.example config.yml -# edit options to match old config -sudo -u git -H vi config.yml -``` - -## 4. Install libs, migrations etc - -```bash -cd /home/git/gitlab -sudo rm tmp/sockets/gitlab.socket -sudo -u git -H cp config/puma.rb.example config/puma.rb - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_merge_requests RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update init.d script with a new one - -```bash -# init.d -sudo rm /etc/init.d/gitlab -sudo curl --location --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlab-recipes/5-1-stable/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 6. MySQL grant privileges - -Only if you are using MySQL: - -```bash -mysql -u root -p -mysql> GRANT LOCK TABLES ON `gitlabhq_production`.* TO 'gitlab'@'localhost'; -mysql> \q -``` - -## 7. Start application - - sudo service gitlab start - -## 8. Check installation - - -```bash -# In 5-10 seconds lets check gitlab-shell -sudo -u git -H /home/git/gitlab-shell/bin/check - -# Example of success output -# Check GitLab API access: OK -# Check directories and files: -# /home/git/repositories: OK -# /home/git/.ssh/authorized_keys: OK - - -# Now check gitlab instance -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.1-to-5.2.md b/doc/update/5.1-to-5.2.md index bcc9058ff99..8514aa13f48 100644 --- a/doc/update/5.1-to-5.2.md +++ b/doc/update/5.1-to-5.2.md @@ -1,124 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.1 to 5.2 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.1-to-5.2.md) for the most up to date instructions.* - -## Warning - -GitLab 5.2 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -## 0. Backup - -It's useful to make a backup just in case things go south: -(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-2-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.4.0 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-2-stable/config/puma.rb.example> but with your settings. - -## 6. Update Init script - -```bash -cd /home/git/gitlab -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 7. Create uploads directory - -```bash -cd /home/git/gitlab -sudo -u git -H mkdir public/uploads -sudo chmod -R u+rwX public/uploads -``` - -## 8. Start application - - sudo service gitlab start - sudo service nginx restart - -## 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.0 to 5.1](5.0-to-5.1.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.1-to-5.4.md b/doc/update/5.1-to-5.4.md index 5767c9cc121..8514aa13f48 100644 --- a/doc/update/5.1-to-5.4.md +++ b/doc/update/5.1-to-5.4.md @@ -1,120 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.1 to 5.4 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.1-to-5.4.md) for the most up to date instructions.* - -Also works starting from 5.2. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-4-stable # Latest version of 5-4-stable addresses CVE-2013-4489 -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example> but with your settings. - -## 6. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 7. Create uploads directory - -```bash -cd /home/git/gitlab -sudo -u git -H mkdir public/uploads -sudo chmod -R u+rwX public/uploads -``` - -## 8. Start application - - sudo service gitlab start - sudo service nginx restart - -## 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.2 to 5.3](5.2-to-5.3.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.1-to-6.0.md b/doc/update/5.1-to-6.0.md index 4993d034b6e..8514aa13f48 100644 --- a/doc/update/5.1-to-6.0.md +++ b/doc/update/5.1-to-6.0.md @@ -1,236 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.1 to 6.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.1-to-6.0.md) for the most up to date instructions.* - -## Warning - -GitLab 6.0 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -## Deprecations - -### Global projects - -The root (global) namespace for projects is deprecated. - -So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote URL. Please make sure you disable sending email when you do a test of the upgrade. - -### Teams - -We introduce group membership in 6.0 as a replacement for teams. - -The old combination of groups and teams was confusing for a lot of people. - -And when the members of a team where changed this wasn't reflected in the project permissions. - -In GitLab 6.0 you will be able to add members to a group with a permission level for each member. - -These group members will have access to the projects in that group. - -Any changes to group members will immediately be reflected in the project permissions. - -You can even have multiple owners for a group, greatly simplifying administration. - -## 0. Backup & prepare for update - -It's useful to make a backup just in case things go south: -(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following can help you have a more smooth upgrade. - -### Find projects with invalid project names - -#### MySQL -Login to MySQL: - - mysql -u root -p - -Find projects with invalid names: - -```bash -mysql> use gitlabhq_production; - -# find projects with invalid first char, projects must start with letter -mysql> select name from projects where name REGEXP '^[^A-Za-z]'; - -# find projects with other invalid chars -## names must only contain alphanumeric chars, underscores, spaces, periods, and dashes -mysql> select name from projects where name REGEXP '[^a-zA-Z0-9_ .-]+'; -``` - -If any projects have invalid names try correcting them from the web interface before starting the upgrade. -If correcting them from the web interface fails you can correct them using MySQL: - -```bash -# e.g. replace invalid / with allowed _ -mysql> update projects set name = REPLACE(name,'/','_'); -# repeat for all invalid chars found in project names -``` - -#### PostgreSQL -Make sure all project names start with a letter and only contain alphanumeric chars, underscores, spaces, periods, and dashes (a-zA-Z0-9_ .-). - -### Find other common errors - -``` -cd /home/git/gitlab -# Start rails console -sudo -u git -H bin/rails console production - -# Make sure none of the following rails commands return results - -# All project owners should have an owner: -Project.all.select { |project| project.owner.blank? } - -# Every user should have a namespace: -User.all.select { |u| u.namespace.blank? } - -# Projects in the global namespace should not conflict with projects in the owner namespace: -Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? } -``` - -If any of the above rails commands returned results other than `=> []` try correcting the issue from the web interface. - -If you find projects without an owner (first rails command above), correct it. For MySQL setups: - -```bash -# get your user id -mysql> select id, name from users order by name; - -# set yourself as owner of project -# replace your_user_id with your user id and bad_project_id with the project id from the rails command -mysql> update projects set creator_id=your_user_id where id=bad_project_id; -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 6-0-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 -``` - -## 4. Install additional packages - -```bash -# For reStructuredText markup language support install required package: -sudo apt-get install python-docutils -``` - -## 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_groups RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_global_projects RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production - -# Clear redis cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production - -# Clear and precompile assets -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production - -#Add dealing with newlines for editor -sudo -u git -H git config --global core.autocrlf input -``` - -## 6. Update config files - -Note: We switched from Puma in GitLab 5.x to unicorn in GitLab 6.0. - -- Make `/home/git/gitlab/config/gitlab.yml` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-0-stable/config/unicorn.rb.example> but with your settings. - -## 7. Update Init script - -```bash -cd /home/git/gitlab -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 8. Create uploads directory - -```bash -cd /home/git/gitlab -sudo -u git -H mkdir -p public/uploads -sudo chmod -R u+rwX public/uploads -``` - -## 9. Start application - - sudo service gitlab start - sudo service nginx restart - -## 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.0 to 5.1](5.0-to-5.1.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.2-to-5.3.md b/doc/update/5.2-to-5.3.md index c378d2798f4..8514aa13f48 100644 --- a/doc/update/5.2-to-5.3.md +++ b/doc/update/5.2-to-5.3.md @@ -1,106 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.2 to 5.3 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.2-to-5.3.md) for the most up to date instructions.* - -## Warning - -GitLab 5.3 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-3-stable -``` - -## 3. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 4. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-3-stable/config/puma.rb.example> but with your settings. - -## 5. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo curl --location --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlabhq/5-3-stable/lib/support/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 6. Start application - - sudo service gitlab start - sudo service nginx restart - -## 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.1 to 5.2](5.1-to-5.2.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.3-to-5.4.md b/doc/update/5.3-to-5.4.md index 77b1e9e5329..8514aa13f48 100644 --- a/doc/update/5.3-to-5.4.md +++ b/doc/update/5.3-to-5.4.md @@ -1,110 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.3 to 5.4 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.3-to-5.4.md) for the most up to date instructions.* - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 5-4-stable # Latest version of 5-4-stable addresses CVE-2013-4489 -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/puma.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/5-4-stable/config/puma.rb.example> but with your settings. - -## 6. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo curl --location --output /etc/init.d/gitlab https://raw.github.com/gitlabhq/gitlabhq/5-4-stable/lib/support/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 7. Start application - - sudo service gitlab start - sudo service nginx restart - -## 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (5.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.2 to 5.3](5.2-to-5.3.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/5.4-to-6.0.md b/doc/update/5.4-to-6.0.md index 2d2da769b89..8514aa13f48 100644 --- a/doc/update/5.4-to-6.0.md +++ b/doc/update/5.4-to-6.0.md @@ -1,169 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 5.4 to 6.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/5.4-to-6.0.md) for the most up to date instructions.* - -## Warning - -GitLab 6.0 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -**You need to follow this guide first, before updating past 6.0, as it contains critical migration steps that are only present -in the `6-0-stable` branch** - -## Deprecations - -### Global projects - -The root (global) namespace for projects is deprecated. - -So you need to move all your global projects under groups or users manually before update or they will be automatically moved to the project owner namespace during the update. When a project is moved all its members will receive an email with instructions how to update their git remote URL. Please make sure you disable sending email when you do a test of the upgrade. - -### Teams - -We introduce group membership in 6.0 as a replacement for teams. - -The old combination of groups and teams was confusing for a lot of people. - -And when the members of a team where changed this wasn't reflected in the project permissions. - -In GitLab 6.0 you will be able to add members to a group with a permission level for each member. - -These group members will have access to the projects in that group. - -Any changes to group members will immediately be reflected in the project permissions. - -You can even have multiple owners for a group, greatly simplifying administration. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch -sudo -u git -H git checkout 6-0-stable -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 -``` - -## 4. Install additional packages - -```bash -# For reStructuredText markup language support install required package: -sudo apt-get install python-docutils -``` - -## 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_groups RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_global_projects RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production -sudo -u git -H bundle exec rake gitlab:satellites:create RAILS_ENV=production - -# Clear redis cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production - -# Clear and precompile assets -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -``` - -## 6. Update config files - -Note: We switched from Puma in GitLab 5.4 to unicorn in GitLab 6.0. - -- Make `/home/git/gitlab/config/gitlab.yml` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/unicorn.rb.example> but with your settings. - -## 7. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -sudo chmod +x /etc/init.d/gitlab -``` - -## 8. Start application - - sudo service gitlab start - sudo service nginx restart - -## 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Troubleshooting - -The migrations in this update are very sensitive to incomplete or inconsistent data. If you have a long-running GitLab installation and some of the previous upgrades did not work out 100% correct this may bite you now. The following commands can be run in the rails console to look for 'bad' data. - -All project owners should have an owner: - -``` -Project.all.select { |project| project.owner.blank? } -``` - -Every user should have a namespace: - -``` -User.all.select { |u| u.namespace.blank? } -``` - -Projects in the global namespace should not conflict with projects in the owner namespace: - -``` -Project.where(namespace_id: nil).select { |p| Project.where(path: p.path, namespace_id: p.owner.try(:namespace).try(:id)).present? } -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.0-to-6.1.md b/doc/update/6.0-to-6.1.md index dd409175c27..8514aa13f48 100644 --- a/doc/update/6.0-to-6.1.md +++ b/doc/update/6.0-to-6.1.md @@ -1,127 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.0 to 6.1 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.0-to-6.1.md) for the most up to date instructions.* - -## Warning - -GitLab 6.1 is affected by critical security vulnerabilities CVE-2013-4490 and CVE-2013-4489. - -**In 6.1 we remove a lot of deprecated code.** - -**You should update to 6.0 before installing 6.1 so all the necessary conversions are run.** - -## Deprecations - -### Global issue numbers - -In 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their URL. If you use an old issue number URL and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects. - -## 0. Backup - -It's useful to make a backup just in case things go south (with MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version): - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-1-stable -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-1-stable-ee -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake migrate_iids RAILS_ENV=production -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -## 5. Update config files - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-1-stable/config/unicorn.rb.example> but with your settings. - -## 6. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 7. Start application - - sudo service gitlab start - sudo service nginx restart - -## 8. Check application status - -Check if GitLab and its environment are configured correctly: - - cd /home/git/gitlab - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 5.4 to 6.0](5.4-to-6.0.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.1-to-6.2.md b/doc/update/6.1-to-6.2.md index cace80c99b7..8514aa13f48 100644 --- a/doc/update/6.1-to-6.2.md +++ b/doc/update/6.1-to-6.2.md @@ -1,141 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.1 to 6.2 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.1-to-6.2.md) for the most up to date instructions.* - -**You should update to 6.1 before installing 6.2 so all the necessary conversions are run.** - -## 0. Backup - -It's useful to make a backup just in case things go south: (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version). - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-2-stable # Latest version of 6-2-stable addresses CVE-2013-4489 -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-2-stable-ee -``` - -## 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -## 4. Install additional packages - -```bash -# Add support for logrotate for better log file handling -sudo apt-get install logrotate -``` - -## 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production -sudo -u git -H bundle exec rake assets:clean RAILS_ENV=production -sudo -u git -H bundle exec rake assets:precompile RAILS_ENV=production -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -## 6. Update config files - -TIP: to see what changed in `gitlab.yml.example` in this release use next command: - -``` -git diff 6-1-stable:config/gitlab.yml.example 6-2-stable:config/gitlab.yml.example -``` - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/gitlab.yml.example> but with your settings. - -- Make `/home/git/gitlab/config/unicorn.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-2-stable/config/unicorn.rb.example> but with your settings. - -- Copy rack attack middleware config: - - ```bash - sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb - ``` - -- Uncomment `config.middleware.use Rack::Attack` in `/home/git/gitlab/config/application.rb` - -- Set up logrotate. - -```bash -sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab -``` - -## 7. Update Init script - -```bash -sudo rm /etc/init.d/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 8. Start application - - sudo service gitlab start - sudo service nginx restart - -## 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.0 to 6.1](6.0-to-6.1.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.2-to-6.3.md b/doc/update/6.2-to-6.3.md index 7205575942a..8514aa13f48 100644 --- a/doc/update/6.2-to-6.3.md +++ b/doc/update/6.2-to-6.3.md @@ -1,127 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.2 to 6.3 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.2-to-6.3.md) for the most up to date instructions.* - -**Requires version: 6.1 or 6.2.** - -## 0. Backup - -It's useful to make a backup just in case things go south: (With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-3-stable -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-3-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.7.9 # Addresses multiple critical security vulnerabilities -``` - -The gitlab-shell config changed recently, so check for config file changes and make `/home/git/gitlab-shell/config.yml` the same as <https://github.com/gitlabhq/gitlab-shell/blob/master/config.yml.example> - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -## 5. Update config files - -TIP: to see what changed in gitlab.yml.example in this release use next command: - -``` -git diff 6-2-stable:config/gitlab.yml.example 6-3-stable:config/gitlab.yml.example -``` - -- Make `/home/git/gitlab/config/gitlab.yml` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/6-3-stable/config/unicorn.rb.example> but with your settings. - -```bash -# Copy rack attack middleware config -cd /home/git/gitlab -sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb -``` - -## 6. Update Init script - -```bash -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 7. Start application - - sudo service gitlab start - sudo service nginx restart - -## 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.1 to 6.2](6.1-to-6.2.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.3-to-6.4.md b/doc/update/6.3-to-6.4.md index 285ed06bdad..8514aa13f48 100644 --- a/doc/update/6.3-to-6.4.md +++ b/doc/update/6.3-to-6.4.md @@ -1,109 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.3 to 6.4 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.3-to-6.4.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - -```bash -sudo service gitlab stop -```` - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout 6-4-stable -# For GitLab Enterprise Edition: sudo -u git -H git checkout 6-4-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.8.0 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 5. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -## 6. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check with: - -```bash -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations upgrade complete! - -## Things went south? Revert to previous version (6.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.2 to 6.3](6.2-to-6.3.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.4-to-6.5.md b/doc/update/6.4-to-6.5.md index e07c98a5ad4..8514aa13f48 100644 --- a/doc/update/6.4-to-6.5.md +++ b/doc/update/6.4-to-6.5.md @@ -1,115 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.4 to 6.5 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.4-to-6.5.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-5-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.8.0 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 5. Start application - - sudo service gitlab start - sudo service nginx restart - -## 6. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.4) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.3 to 6.4](6.3-to-6.4.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.5-to-6.6.md b/doc/update/6.5-to-6.6.md index 3f79b19644e..8514aa13f48 100644 --- a/doc/update/6.5-to-6.6.md +++ b/doc/update/6.5-to-6.6.md @@ -1,117 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.5 to 6.6 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.5-to-6.6.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-6-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.8.0 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# The Modernizr gem was yanked from RubyGems. It is required for GitLab >= 2.8.0 -# Edit `Gemfile` and change `gem "modernizr", "2.5.3"` to -# `gem "modernizr-rails", "2.7.1"`` -sudo -u git -H vim Gemfile - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 5. Start application - - sudo service gitlab start - sudo service nginx restart - -## 6. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.5) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.4 to 6.5](6.4-to-6.5.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.6-to-6.7.md b/doc/update/6.6-to-6.7.md index a0542d20d49..8514aa13f48 100644 --- a/doc/update/6.6-to-6.7.md +++ b/doc/update/6.6-to-6.7.md @@ -1,123 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.6 to 6.7 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.6-to-6.7.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - - sudo service gitlab stop - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-7-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.1 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test postgres --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL - -# Run a bundle install without deployment to generate the new Gemfile -sudo -u git -H bundle install --without development test mysql --no-deployment - -# Install libs (with deployment this time) -sudo -u git -H bundle install --without development test mysql --deployment - -# Both MySQL and PostgreSQL -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -# Update the logrotate configuration (keep logs for 90 days instead of 52 weeks) -sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab - -# Compress existing .log.1 files because we turned off delaycompress in logrotate -sudo -u git -H gzip /home/git/gitlab/log/*.log.1 -sudo -u git -H gzip /home/git/gitlab-shell/gitlab-shell.log.1 - -# Close access to gitlab-satellites for others -sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites - -# Add directory for uploads -sudo -u git -H mkdir -p /home/git/gitlab/public/uploads -``` - -## 5. Start application - - sudo service gitlab start - sudo service nginx restart - -## 6. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.6) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.5 to 6.6](6.5-to-6.6.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.7-to-6.8.md b/doc/update/6.7-to-6.8.md index acf004577f1..8514aa13f48 100644 --- a/doc/update/6.7-to-6.8.md +++ b/doc/update/6.7-to-6.8.md @@ -1,126 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.7 to 6.8 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.7-to-6.8.md) for the most up to date instructions.* - -## 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 1. Stop server - -```bash -sudo service gitlab stop -``` - -## 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-8-stable-ee -``` - -## 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.3 -``` - -## 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -# Close access to gitlab-satellites for others -sudo chmod u+rwx,g=rx,o-rwx /home/git/gitlab-satellites -``` - -## 5. Update config files - -### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff 6-7-stable:config/gitlab.yml.example 6-8-stable:config/gitlab.yml.example -``` - -### MySQL? Remove reaping frequency - -If you are using MySQL as a database, remove `reaping_frequency` from you database.yml to prevent crashes. [Relevant commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/5163a8fcb9cfd63435560fda00173b76df2ccc93). - -### HTTPS? Disable gzip - -If you are using HTTPS, disable gzip as in [this commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/563fec734912d81cd7caea6fa8ec2b397fb72a9b) to prevent BREACH attacks. - -### Turn on asset compression - -To improve performance, enable gzip asset compression as seen [in this commit](https://gitlab.com/gitlab-org/gitlab-ce/commit/8af94ed75505f0253823b9b2d44320fecea5b5fb). - -## 6. Start application - - sudo service gitlab start - sudo service nginx restart - -## 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.7) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.6 to 6.7](6.6-to-6.7.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.8-to-6.9.md b/doc/update/6.8-to-6.9.md index 3d7b1e5346b..8514aa13f48 100644 --- a/doc/update/6.8-to-6.9.md +++ b/doc/update/6.8-to-6.9.md @@ -1,107 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.8 to 6.9 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.8-to-6.9.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 6-9-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 6-9-stable-ee -``` - -### 3. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.4 -``` - -### 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -### 5. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff 6-8-stable:config/gitlab.yml.example 6-9-stable:config/gitlab.yml.example -``` - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.8) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 6.7 to 6.8](6.7-to-6.8.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.9-to-7.0.md b/doc/update/6.9-to-7.0.md index e1ca34305b4..8514aa13f48 100644 --- a/doc/update/6.9-to-7.0.md +++ b/doc/update/6.9-to-7.0.md @@ -1,145 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.9 to 7.0 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.9-to-7.0.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Update Ruby - -If you are still using Ruby 1.9.3 or below, you will need to update Ruby. -You can check which version you are running with `ruby -v`. - -If you are you running Ruby 2.0.x, you do not need to upgrade ruby, but can consider doing so for performance reasons. - -If you are running Ruby 2.1.1 consider upgrading to 2.1.2, because of the high memory usage of Ruby 2.1.1. - -Install, update dependencies: - -```bash -sudo apt-get install build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl -``` - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --location --progress ftp://ftp.ruby-lang.org/pub/ruby/2.1/ruby-2.1.2.tar.gz | tar xz -cd ruby-2.1.2 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 3. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-0-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-0-stable-ee -``` - -### 4. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.6 -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff origin/6-9-stable:config/gitlab.yml.example origin/7-0-stable:config/gitlab.yml.example -``` - -- HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab> but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl> but with your setting. - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (6.9) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 6.8 to 6.9](6.8-to-6.9.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/6.x-or-7.x-to-7.14.md b/doc/update/6.x-or-7.x-to-7.14.md index 674163091be..8514aa13f48 100644 --- a/doc/update/6.x-or-7.x-to-7.14.md +++ b/doc/update/6.x-or-7.x-to-7.14.md @@ -1,317 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 6.x or 7.x to 7.14 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/6.x-or-7.x-to-7.14.md) for the most up to date instructions.* - -This allows you to upgrade any version of GitLab from 6.0 and up (including 7.0 and up) to 7.14. - -## Global issue numbers - -As of 6.1 issue numbers are project specific. This means all issues are renumbered and get a new number in their URL. If you use an old issue number URL and the issue number does not exist yet you are redirected to the new one. This conversion does not trigger if the old number already exists for this project, this is unlikely but will happen with old issues and large projects. - -## Editable labels - -In GitLab 7.2 we replace Issue and Merge Request tags with labels, making it -possible to edit the label text and color. The characters `?`, `&` and `,` are -no longer allowed however so those will be removed from your tags during the -database migrations for GitLab 7.2. - -## Stash changes - -If you deleted the vendors folder during your original installation, [you will get an error](https://gitlab.com/gitlab-org/gitlab-ce/issues/1494) when you attempt to rebuild the assets in step 7. To avoid this, stash the changes in your GitLab working copy before starting: - - git stash - -## 0. Stop server - - sudo service gitlab stop - -## 1. Backup - -It's useful to make a backup just in case things go south: -(With MySQL, this may require granting "LOCK TABLES" privileges to the GitLab user on the database version) - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -## 2. Update Ruby - -If you are still using Ruby 1.9.3 or below, you will need to update Ruby. -You can check which version you are running with `ruby -v`. - -If you are you running Ruby 2.0.x, you do not need to upgrade ruby, but can consider doing so for performance reasons. - -If you are running Ruby 2.1.1 consider upgrading to 2.1.6, because of the high memory usage of Ruby 2.1.1. - -Install, update dependencies: - -```bash -sudo apt-get install build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl -``` - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --progress https://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.6.tar.gz | tar xz -cd ruby-2.1.6 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -## 3. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-14-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-14-stable-ee -``` - -## 4. Install additional packages - -```bash -# Add support for logrotate for better log file handling -sudo apt-get install logrotate - -# Install pkg-config and cmake, which is needed for the latest versions of rugged -sudo apt-get install pkg-config cmake - -# If you want to use Kerberos with GitLab EE for user authentication, install Kerberos header files -# If you don't know what Kerberos is, you can assume you don't need it. -sudo apt-get install libkrb5-dev - -# Install nodejs, javascript runtime required for assets -sudo apt-get install nodejs -``` - -## 5. Configure Redis to use sockets - - # Configure redis to use sockets - sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig - # Disable Redis listening on TCP by setting 'port' to 0 - sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf - # Enable Redis socket for default Debian / Ubuntu path - echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf - # Be sure redis group can write to the socket, enable only if supported (>= redis 2.4.0). - sudo sed -i '/# unixsocketperm/ s/^# unixsocketperm.*/unixsocketperm 0775/' /etc/redis/redis.conf - # Activate the changes to redis.conf - sudo service redis-server restart - # Add git to the redis group - sudo usermod -aG redis git - - # Configure Redis connection settings - sudo -u git -H cp config/resque.yml.example config/resque.yml - # Change the Redis socket path if you are not using the default Debian / Ubuntu configuration - sudo -u git -H editor config/resque.yml - - # Configure gitlab-shell to use Redis sockets - sudo -u git -H sed -i 's|^ # socket.*| socket: /var/run/redis/redis.sock|' /home/git/gitlab-shell/config.yml - -## 6. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.5 -``` - -## 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations from 6.0 to 6.1 -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production VERSION=20130909132950 - -# Enable internal issue IDs (introduced in GitLab 6.1) -sudo -u git -H bundle exec rake migrate_iids RAILS_ENV=production - -# Run left database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Close access to gitlab-satellites for others -sudo chmod u+rwx,g+rx,o-rwx /home/git/gitlab-satellites - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -## 8. Update config files - -TIP: to see what changed in `gitlab.yml.example` in this release use next command: - -``` -git diff 6-0-stable:config/gitlab.yml.example 7-14-stable:config/gitlab.yml.example -``` - -- Make `/home/git/gitlab/config/gitlab.yml` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/gitlab.yml.example> but with your settings. -- Make `/home/git/gitlab/config/unicorn.rb` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/unicorn.rb.example> but with your settings. -- Make `/home/git/gitlab-shell/config.yml` the same as <https://gitlab.com/gitlab-org/gitlab-shell/blob/v2.6.5/config.yml.example> but with your settings. -- Copy rack attack middleware config. - -```bash -sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb -``` - -- Set up logrotate - -```bash -sudo cp lib/support/logrotate/gitlab /etc/logrotate.d/gitlab -``` - -### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/lib/support/nginx/gitlab> but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/lib/support/nginx/gitlab-ssl> but with your settings. -- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. - -### Check the version of /usr/local/bin/git - -If you installed Git from source into /usr/local/bin/git then please [check -your version](7.13-to-7.14.md). - -## 9. Start application - - sudo service gitlab start - sudo service nginx restart - -## 10. Check application status - -Check if GitLab and its environment are configured correctly: - - cd /home/git/gitlab - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade complete! - -## 11. Update OmniAuth configuration - -When using Google omniauth login, changes of the Google account required. -Ensure that `Contacts API` and the `Google+ API` are enabled in the [Google Developers Console](https://console.developers.google.com/). -More details can be found at the [integration documentation](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/integration/google.md). - -## 12. Optional optimizations for GitLab setups with MySQL databases - -Only applies if running MySQL database created with GitLab 6.7 or earlier. If you are not experiencing any issues you may not need the following instructions however following them will bring your database in line with the latest recommended installation configuration and help avoid future issues. Be sure to follow these directions exactly. These directions should be safe for any MySQL instance but to be sure make a current MySQL database backup beforehand. - -``` -# Stop GitLab -sudo service gitlab stop - -# Secure your MySQL installation (added in GitLab 6.2) -sudo mysql_secure_installation - -# Login to MySQL -mysql -u root -p - -# do not type the 'mysql>', this is part of the prompt - -# Convert all tables to use the InnoDB storage engine (added in GitLab 6.8) -SELECT CONCAT('ALTER TABLE gitlabhq_production.', table_name, ' ENGINE=InnoDB;') AS 'Copy & run these SQL statements:' FROM information_schema.tables WHERE table_schema = 'gitlabhq_production' AND `ENGINE` <> 'InnoDB' AND `TABLE_TYPE` = 'BASE TABLE'; - -# If previous query returned results, copy & run all shown SQL statements - -# Convert all tables to correct character set -SET foreign_key_checks = 0; -SELECT CONCAT('ALTER TABLE gitlabhq_production.', table_name, ' CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;') AS 'Copy & run these SQL statements:' FROM information_schema.tables WHERE table_schema = 'gitlabhq_production' AND `TABLE_COLLATION` <> 'utf8_unicode_ci' AND `TABLE_TYPE` = 'BASE TABLE'; - -# If previous query returned results, copy & run all shown SQL statements - -# turn foreign key checks back on -SET foreign_key_checks = 1; - -# Find MySQL users -mysql> SELECT user FROM mysql.user WHERE user LIKE '%git%'; - -# If git user exists and gitlab user does not exist -# you are done with the database cleanup tasks -mysql> \q - -# If both users exist skip to Delete gitlab user - -# Create new user for GitLab (changed in GitLab 6.4) -# change $password in the command below to a real password you pick -mysql> CREATE USER 'git'@'localhost' IDENTIFIED BY '$password'; - -# Grant the git user necessary permissions on the database -mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, LOCK TABLES ON `gitlabhq_production`.* TO 'git'@'localhost'; - -# Delete the old gitlab user -mysql> DELETE FROM mysql.user WHERE user='gitlab'; - -# 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 - -# Update database configuration details -# See config/database.yml.mysql for latest recommended configuration details -# Remove the reaping_frequency setting line if it exists (removed in GitLab 6.8) -# Set production -> pool: 10 (updated in GitLab 5.3) -# Set production -> username: git -# Set production -> password: the password your replaced $password with earlier -sudo -u git -H editor /home/git/gitlab/config/database.yml -``` - -## Things went south? Revert to previous version (7.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 6.9 to 7.0](6.9-to-7.0.md), except for the database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -## Login issues after upgrade? - -If running in HTTPS mode, be sure to read [Can't Verify CSRF token authenticity](https://github.com/gitlabhq/gitlab-public-wiki/wiki/Trouble-Shooting-Guide#cant-verify-csrf-token-authenticitycant-get-past-login-pageredirected-to-login-page) +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.0-to-7.1.md b/doc/update/7.0-to-7.1.md index 8b69431dee1..8514aa13f48 100644 --- a/doc/update/7.0-to-7.1.md +++ b/doc/update/7.0-to-7.1.md @@ -1,144 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.0 to 7.1 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.0-to-7.1.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Update Ruby - -If you are still using Ruby 1.9.3 or below, you will need to update Ruby. -You can check which version you are running with `ruby -v`. - -If you are you running Ruby 2.0.x, you do not need to upgrade ruby, but can consider doing so for performance reasons. - -If you are running Ruby 2.1.1 consider upgrading to 2.1.2, because of the high memory usage of Ruby 2.1.1. - -Install, update dependencies: - -```bash -sudo apt-get install build-essential zlib1g-dev libyaml-dev libssl-dev libgdbm-dev libreadline-dev libncurses5-dev libffi-dev curl -``` - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --location --progress ftp://ftp.ruby-lang.org/pub/ruby/2.1/ruby-2.1.2.tar.gz | tar xz -cd ruby-2.1.2 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 3. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-1-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-1-stable-ee -``` - -### 4. Update gitlab-shell (and its config) - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.6 -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml if desired. - -``` -git diff 7-0-stable:config/gitlab.yml.example 7-1-stable:config/gitlab.yml.example -``` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (7.0) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 6.9 to 7.0](6.9-to-7.0.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-1-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.1-to-7.2.md b/doc/update/7.1-to-7.2.md index 44e5fc676b3..8514aa13f48 100644 --- a/doc/update/7.1-to-7.2.md +++ b/doc/update/7.1-to-7.2.md @@ -1,143 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.1 to 7.2 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.1-to-7.2.md) for the most up to date instructions.* - -## Editable labels - -In GitLab 7.2 we replace Issue and Merge Request tags with labels, making it -possible to edit the label text and color. The characters `?`, `&` and `,` are -no longer allowed however so those will be removed from your tags during the -database migrations for GitLab 7.2. - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-2-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-2-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v1.9.8 -``` - -### 4. Install new system dependencies - -The latest version of the 'rugged' gem requires `pkg-config` and `cmake` to -build its native extensions. - -```bash -sudo apt-get install pkg-config cmake -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for `gitlab.yml`. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff 7-1-stable:config/gitlab.yml.example 7-2-stable:config/gitlab.yml.example -``` - -- HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab> but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-0-stable/lib/support/nginx/gitlab-ssl> but with your setting. - -Update rack attack middleware config - -``` -sudo -u git -H cp config/initializers/rack_attack.rb.example config/initializers/rack_attack.rb -``` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 9. Update OmniAuth configuration - -When using Google omniauth login, changes of the Google account required. -Ensure that `Contacts API` and the `Google+ API` are enabled in the [Google Developers Console](https://console.developers.google.com/). -More details can be found at the [integration documentation](../integration/google.md). - -## Things went south? Revert to previous version (7.1) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.0 to 7.1](7.0-to-7.1.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-2-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.10-to-7.11.md b/doc/update/7.10-to-7.11.md index 39eeefc0e32..8514aa13f48 100644 --- a/doc/update/7.10-to-7.11.md +++ b/doc/update/7.10-to-7.11.md @@ -1,109 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.10 to 7.11 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-11-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-11-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.3 -``` - -### 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-10-stable:config/gitlab.yml.example origin/7-11-stable:config/gitlab.yml.example -`````` - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (7.10) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.9 to 7.10](7.9-to-7.10.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-11-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.11-to-7.12.md b/doc/update/7.11-to-7.12.md index 530066e5fdb..8514aa13f48 100644 --- a/doc/update/7.11-to-7.12.md +++ b/doc/update/7.11-to-7.12.md @@ -1,135 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.11 to 7.12 - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version. - -``` -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source -installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-12-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-12-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.3 -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-11-stable:config/gitlab.yml.example origin/7-12-stable:config/gitlab.yml.example -`````` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (7.11) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.10 to 7.11](7.10-to-7.11.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-12-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.12-to-7.13.md b/doc/update/7.12-to-7.13.md index 8f413a2079a..8514aa13f48 100644 --- a/doc/update/7.12-to-7.13.md +++ b/doc/update/7.12-to-7.13.md @@ -1,135 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.12 to 7.13 - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version. - -``` -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source -installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-13-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-13-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.3 -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-12-stable:config/gitlab.yml.example origin/7-13-stable:config/gitlab.yml.example -`````` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (7.12) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.11 to 7.12](7.11-to-7.12.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-13-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.13-to-7.14.md b/doc/update/7.13-to-7.14.md index a8980662855..8514aa13f48 100644 --- a/doc/update/7.13-to-7.14.md +++ b/doc/update/7.13-to-7.14.md @@ -1,135 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.13 to 7.14 - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version. - -``` -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source -installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-14-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-14-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.5 -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 6. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-13-stable:config/gitlab.yml.example origin/7-14-stable:config/gitlab.yml.example -`````` - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (7.13) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.12 to 7.13](7.12-to-7.13.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-14-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.14-to-8.0.md b/doc/update/7.14-to-8.0.md index 513afccff50..8514aa13f48 100644 --- a/doc/update/7.14-to-8.0.md +++ b/doc/update/7.14-to-8.0.md @@ -1,235 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.14 to 8.0 - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version: - -```sh -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source -installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-0-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-0-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.5 -``` - -### 5. Install gitlab-git-http-server - -First we download Go 1.5 and install it into `/usr/local/go`: - -```bash -curl --remote-name --progress https://storage.googleapis.com/golang/go1.5.linux-amd64.tar.gz -echo '5817fa4b2252afdb02e11e8b9dc1d9173ef3bd5a go1.5.linux-amd64.tar.gz' | shasum -c - && \ - sudo tar -C /usr/local -xzf go1.5.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.5.linux-amd64.tar.gz -``` - -Now we download `gitlab-git-http-server` and install it in `/home/git/gitlab-git-http-server`: - -```bash -cd /home/git -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-git-http-server.git -cd gitlab-git-http-server -sudo -u git -H git checkout 0.2.14 -sudo -u git -H make -``` - -Make sure your unicorn.rb file contains a 'listen' line for -'127.0.0.1:8080' and that this line is not commented out. - -``` -cd /home/git/gitlab -grep ^listen config/unicorn.rb - -# If there is no 'listen' line for 127.0.0.1:8080, add it: -sudo -u git tee -a config/unicorn.rb <<EOF -listen "127.0.0.1:8080", :tcp_nopush => true -EOF -``` - -If your Git repositories are in a directory other than `/home/git/repositories`, -you need to tell `gitlab-git-http-server` about it via `/etc/default/gitlab`. -See `lib/support/init.d/gitlab.default.example` for the options. - -### 6. Copy secrets - -The `secrets.yml` file is used to store keys to encrypt sessions and encrypt secure variables. -When you run migrations make sure to store it someplace safe. -Don't store it in the same place as your database backups, -otherwise your secrets are exposed if one of your backups is compromised. - -``` -cd /home/git/gitlab -sudo -u git -H cp config/secrets.yml.example config/secrets.yml -sudo -u git -H chmod 0600 config/secrets.yml -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 8. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/7-14-stable:config/gitlab.yml.example origin/8-0-stable:config/gitlab.yml.example -``` - -The new options include configuration of GitLab CI that are now being part of GitLab CE and EE. - -#### New Nginx configuration - -Because of the new `gitlab-git-http-server` you need to update your Nginx -configuration. If you skip this step 'git clone' and 'git push' over HTTP(S) -will stop working. - -View changes between the previous recommended Nginx configuration and the -current one: - -```sh -# For HTTPS configurations -git diff origin/7-14-stable:lib/support/nginx/gitlab-ssl origin/8-0-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/7-14-stable:lib/support/nginx/gitlab origin/8-0-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). -Also note that because Apache does not support upstreams behind Unix sockets you will need to let gitlab-git-http-server listen on a TCP port. You can do this via [/etc/default/gitlab](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-0-stable/lib/support/init.d/gitlab.default.example#L34). - -### 9. Migrate GitLab CI to GitLab CE/EE - -Now, GitLab CE and EE has CI integrated. However, migrations don't happen automatically and you need to do it manually. -Please follow the following guide [to migrate](../migrate_ci_to_ce/README.md) your GitLab CI instance to GitLab CE/EE. - -### 10. Use Redis v2.4.0+ - -Previous versions of GitLab allowed Redis versions >= 2.0 to be used, but -Sidekiq jobs could fail due to lack of support for the SREM command. GitLab -8.0 now checks that Redis >= 2.4.0 is used. You can check your Redis version -with the following command: - - redis-cli info | grep redis_version - -### 11. Start application - - sudo service gitlab start - sudo service nginx restart - -### 12. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (7.14) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 7.13 to 7.14](7.13-to-7.14.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -## Troubleshooting - -### "You appear to have cloned an empty repository." - -If you see this message when attempting to clone a repository hosted by GitLab, -this is likely due to an outdated Nginx or Apache configuration, or a missing or -misconfigured `gitlab-git-http-server` instance. Double-check that you correctly -completed [Step 5](#5-install-gitlab-git-http-server) to install the daemon and -[Step 8](#new-nginx-configuration) to reconfigure Nginx. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-0-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.2-to-7.3.md b/doc/update/7.2-to-7.3.md index 2625df2def8..8514aa13f48 100644 --- a/doc/update/7.2-to-7.3.md +++ b/doc/update/7.2-to-7.3.md @@ -1,151 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.2 to 7.3 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.2-to-7.3.md) for the most up to date instructions.* - -### 0. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Get latest code - -```bash -cd /home/git/gitlab -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-3-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-3-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.0.1 -``` - -### 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - - -### 5. Configure Redis to use sockets - - # Configure redis to use sockets - sudo cp /etc/redis/redis.conf /etc/redis/redis.conf.orig - # Disable Redis listening on TCP by setting 'port' to 0 - sed 's/^port .*/port 0/' /etc/redis/redis.conf.orig | sudo tee /etc/redis/redis.conf - # Enable Redis socket for default Debian / Ubuntu path - echo 'unixsocket /var/run/redis/redis.sock' | sudo tee -a /etc/redis/redis.conf - # Be sure redis group can write to the socket, enable only if supported (>= redis 2.4.0). - sudo sed -i '/# unixsocketperm/ s/^# unixsocketperm.*/unixsocketperm 0775/' /etc/redis/redis.conf - # Activate the changes to redis.conf - sudo service redis-server restart - # Add git to the redis group - sudo usermod -aG redis git - - # Configure Redis connection settings - sudo -u git -H cp config/resque.yml.example config/resque.yml - # Change the Redis socket path if you are not using the default Debian / Ubuntu configuration - sudo -u git -H editor config/resque.yml - - # Configure gitlab-shell to use Redis sockets - sudo -u git -H sed -i 's|^ # socket.*| socket: /var/run/redis/redis.sock|' /home/git/gitlab-shell/config.yml - -### 6. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml. - -``` -git diff origin/7-2-stable:config/gitlab.yml.example origin/7-3-stable:config/gitlab.yml.example -``` - -``` -# Use the default Unicorn socket backlog value of 1024 -sudo -u git -H sed -i 's/:backlog => 64/:backlog => 1024/' config/unicorn.rb -``` - -- HTTP setups: Make `/etc/nginx/sites-available/nginx` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab> but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/nginx-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/lib/support/nginx/gitlab-ssl> but with your setting. - -### 7. Start application - - sudo service gitlab start - sudo service nginx restart - -### 8. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 9. Update OmniAuth configuration - -When using Google omniauth login, changes of the Google account required. -Ensure that `Contacts API` and the `Google+ API` are enabled in the [Google Developers Console](https://console.developers.google.com/). -More details can be found at the [integration documentation](../integration/google.md). - -## Things went south? Revert to previous version (7.2) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.1 to 7.2](7.1-to-7.2.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-3-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.3-to-7.4.md b/doc/update/7.3-to-7.4.md index ad7930e8728..8514aa13f48 100644 --- a/doc/update/7.3-to-7.4.md +++ b/doc/update/7.3-to-7.4.md @@ -1,200 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.3 to 7.4 -*Make sure you view this [upgrade guide from the `master` branch](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update/7.3-to-7.4.md) for the most up to date instructions.* - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-4-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-4-stable-ee -``` - -### 3. Install libs, migrations, etc. - -```bash -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 4. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml. - -``` -git diff origin/7-3-stable:config/gitlab.yml.example origin/7-4-stable:config/gitlab.yml.example -``` - -#### Change timeout for unicorn - -``` -# set timeout to 60 -sudo -u git -H editor config/unicorn.rb -``` - -#### Change Nginx HTTPS settings - -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as <https://gitlab.com/gitlab-org/gitlab-ce/blob/7-4-stable/lib/support/nginx/gitlab-ssl> but with your setting. - -#### MySQL Databases: Update database.yml config file - -- Add `collation: utf8_general_ci` to `config/database.yml` as seen in [config/database.yml.mysql][mysql]: - -``` -sudo -u git -H editor config/database.yml -``` - -### 5. Start application - - sudo service gitlab start - sudo service nginx restart - -### 6. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - - -### 7. Optional optimizations for GitLab setups with MySQL databases - -Only applies if running MySQL database created with GitLab 6.7 or earlier. If you are not experiencing any issues you may not need the following instructions however following them will bring your database in line with the latest recommended installation configuration and help avoid future issues. Be sure to follow these directions exactly. These directions should be safe for any MySQL instance but to be sure make a current MySQL database backup beforehand. - -``` -# Stop GitLab -sudo service gitlab stop - -# Secure your MySQL installation (added in GitLab 6.2) -sudo mysql_secure_installation - -# Login to MySQL -mysql -u root -p - -# do not type the 'mysql>', this is part of the prompt - -# Convert all tables to use the InnoDB storage engine (added in GitLab 6.8) -SELECT CONCAT('ALTER TABLE gitlabhq_production.', table_name, ' ENGINE=InnoDB;') AS 'Copy & run these SQL statements:' FROM information_schema.tables WHERE table_schema = 'gitlabhq_production' AND `ENGINE` <> 'InnoDB' AND `TABLE_TYPE` = 'BASE TABLE'; - -# If previous query returned results, copy & run all shown SQL statements - -# Convert all tables to correct character set -SET foreign_key_checks = 0; -SELECT CONCAT('ALTER TABLE gitlabhq_production.', table_name, ' CONVERT TO CHARACTER SET utf8 COLLATE utf8_general_ci;') AS 'Copy & run these SQL statements:' FROM information_schema.tables WHERE table_schema = 'gitlabhq_production' AND `TABLE_COLLATION` <> 'utf8_unicode_ci' AND `TABLE_TYPE` = 'BASE TABLE'; - -# If previous query returned results, copy & run all shown SQL statements - -# turn foreign key checks back on -SET foreign_key_checks = 1; - -# Find MySQL users -mysql> SELECT user FROM mysql.user WHERE user LIKE '%git%'; - -# If git user exists and gitlab user does not exist -# you are done with the database cleanup tasks -mysql> \q - -# If both users exist skip to Delete gitlab user - -# Create new user for GitLab (changed in GitLab 6.4) -# change $password in the command below to a real password you pick -mysql> CREATE USER 'git'@'localhost' IDENTIFIED BY '$password'; - -# Grant the git user necessary permissions on the database -mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER, LOCK TABLES ON `gitlabhq_production`.* TO 'git'@'localhost'; - -# Delete the old gitlab user -mysql> DELETE FROM mysql.user WHERE user='gitlab'; - -# 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 - -# Update database configuration details -# See config/database.yml.mysql for latest recommended configuration details -# Remove the reaping_frequency setting line if it exists (removed in GitLab 6.8) -# Set production -> pool: 10 (updated in GitLab 5.3) -# Set production -> username: git -# Set production -> password: the password your replaced $password with earlier -sudo -u git -H editor /home/git/gitlab/config/database.yml - -# Start GitLab -sudo service gitlab start -sudo service nginx restart - -# Run thorough check -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - - -## Things went south? Revert to previous version (7.3) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.2 to 7.3](7.2-to-7.3.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-4-stable/config/gitlab.yml.example -[mysql]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-4-stable/config/database.yml.mysql +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.4-to-7.5.md b/doc/update/7.4-to-7.5.md index d93d32d1b60..8514aa13f48 100644 --- a/doc/update/7.4-to-7.5.md +++ b/doc/update/7.4-to-7.5.md @@ -1,116 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.4 to 7.5 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-5-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.2.0 -``` - -### 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for gitlab.yml - -There are new configuration options available for gitlab.yml. View them with the command below and apply them to your current gitlab.yml. - -``` -git diff origin/7-4-stable:config/gitlab.yml.example origin/7-5-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (7.4) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.3 to 7.4](7.3-to-7.4.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-5-stable/config/gitlab.yml.example -[nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-5-stable/lib/support/nginx/gitlab -[nginx-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-5-stable/lib/support/nginx/gitlab-ssl +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.5-to-7.6.md b/doc/update/7.5-to-7.6.md index 0e87918c8c0..8514aa13f48 100644 --- a/doc/update/7.5-to-7.6.md +++ b/doc/update/7.5-to-7.6.md @@ -1,123 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.5 to 7.6 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-6-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.4.0 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install libkrb5-dev - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-5-stable:config/gitlab.yml.example origin/7-6-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting. - -#### Set up time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -## Things went south? Revert to previous version (7.5) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.4 to 7.5](7.4-to-7.5.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-6-stable/config/gitlab.yml.example -[app]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-6-stable/config/application.rb -[nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-6-stable/lib/support/nginx/gitlab -[nginx-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-6-stable/lib/support/nginx/gitlab-ssl +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.6-to-7.7.md b/doc/update/7.6-to-7.7.md index c24b5647f21..8514aa13f48 100644 --- a/doc/update/7.6-to-7.7.md +++ b/doc/update/7.6-to-7.7.md @@ -1,128 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.6 to 7.7 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-7-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.4.2 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install libkrb5-dev - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-6-stable:config/gitlab.yml.example origin/7-7-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your setting. - -#### Set up time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.6) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.5 to 7.6](7.5-to-7.6.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-7-stable/config/gitlab.yml.example -[app]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-7-stable/config/application.rb -[nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-7-stable/lib/support/nginx/gitlab -[nginx-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-7-stable/lib/support/nginx/gitlab-ssl +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.7-to-7.8.md b/doc/update/7.7-to-7.8.md index 61bd5fb1298..8514aa13f48 100644 --- a/doc/update/7.7-to-7.8.md +++ b/doc/update/7.7-to-7.8.md @@ -1,129 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.7 to 7.8 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-8-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.5.4 -``` - -### 4. Install libs, migrations, etc. - -```bash -sudo apt-get install libkrb5-dev - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-7-stable:config/gitlab.yml.example origin/7-8-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. -- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. - -#### Set up time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.7) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.6 to 7.7](7.6-to-7.7.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-8-stable/config/gitlab.yml.example -[app]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-8-stable/config/application.rb -[nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-8-stable/lib/support/nginx/gitlab -[nginx-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-8-stable/lib/support/nginx/gitlab-ssl +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.8-to-7.9.md b/doc/update/7.8-to-7.9.md index c13dd5b60e6..8514aa13f48 100644 --- a/doc/update/7.8-to-7.9.md +++ b/doc/update/7.8-to-7.9.md @@ -1,131 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.8 to 7.9 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-9-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-9-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.0 -``` - -### 4. Install libs, migrations, etc. - -Please refer to the [Node.js setup documentation](https://github.com/joyent/node/wiki/installing-node.js-via-package-manager#debian-and-ubuntu-based-linux-distributions) if you aren't running default GitLab server setup. - -```bash -sudo apt-get install nodejs - -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-8-stable:config/gitlab.yml.example origin/7-9-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. -- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. - -#### Set up time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.8) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.7 to 7.8](7.7-to-7.8.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-9-stable/config/gitlab.yml.example -[app]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-9-stable/config/application.rb -[nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-9-stable/lib/support/nginx/gitlab -[nginx-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-9-stable/lib/support/nginx/gitlab-ssl +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/7.9-to-7.10.md b/doc/update/7.9-to-7.10.md index 4dece93652e..8514aa13f48 100644 --- a/doc/update/7.9-to-7.10.md +++ b/doc/update/7.9-to-7.10.md @@ -1,127 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 7.9 to 7.10 - -### 0. Stop server - - sudo service gitlab stop - -### 1. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 2. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 7-10-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 7-10-stable-ee -``` - -### 3. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.2 -``` - -### 4. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without ... postgres') -sudo -u git -H bundle install --without development test postgres --deployment - -# PostgreSQL installations (note: the line below states '--without ... mysql') -sudo -u git -H bundle install --without development test mysql --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -### 5. Update config files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them to your current `gitlab.yml`. - -``` -git diff origin/7-9-stable:config/gitlab.yml.example origin/7-10-stable:config/gitlab.yml.example -``` - -#### Change Nginx settings - -- HTTP setups: Make `/etc/nginx/sites-available/gitlab` the same as [`lib/support/nginx/gitlab`][nginx] but with your settings. -- HTTPS setups: Make `/etc/nginx/sites-available/gitlab-ssl` the same as [`lib/support/nginx/gitlab-ssl`][nginx-ssl] but with your settings. -- A new `location /uploads/` section has been added that needs to have the same content as the existing `location @gitlab` section. - -#### Set up time zone (optional) - -Consider setting the time zone in `gitlab.yml` otherwise GitLab will default to UTC. If you set a time zone previously in [`application.rb`][app] (unlikely), unset it. - -### 6. Start application - - sudo service gitlab start - sudo service nginx restart - -### 7. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check with: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations upgrade is complete! - -### 8. GitHub settings (if applicable) - -If you are using GitHub as an OAuth provider for authentication, you should change the callback URL so that it -only contains a root URL (ex. `https://gitlab.example.com/`) - -## Things went south? Revert to previous version (7.9) - -### 1. Revert the code to the previous version -Follow the [upgrade guide from 7.8 to 7.9](7.8-to-7.9.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup: - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` -If you have more than one backup *.tar file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-10-stable/config/gitlab.yml.example -[app]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-10-stable/config/application.rb -[nginx]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-10-stable/lib/support/nginx/gitlab -[nginx-ssl]: https://gitlab.com/gitlab-org/gitlab-ce/blob/7-10-stable/lib/support/nginx/gitlab-ssl +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.0-to-8.1.md b/doc/update/8.0-to-8.1.md index f612606af68..8514aa13f48 100644 --- a/doc/update/8.0-to-8.1.md +++ b/doc/update/8.0-to-8.1.md @@ -1,181 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.0 to 8.1 - -**NOTE:** GitLab 8.0 introduced several significant changes related to -installation and configuration which *are not duplicated here*. Be sure you're -already running a working version of 8.0 before proceeding with this guide. - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version: - -```sh -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source -installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-1-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-1-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.5 -``` - -### 5. Update gitlab-git-http-server - -```bash -cd /home/git/gitlab-git-http-server -sudo -u git -H git fetch origin -sudo -u git -H git checkout 0.3.0 -sudo -u git -H make -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-0-stable:config/gitlab.yml.example origin/8-1-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -View changes between the previous recommended Nginx configuration and the -current one: - -```sh -# For HTTPS configurations -git diff origin/8-0-stable:lib/support/nginx/gitlab-ssl origin/8-1-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-0-stable:lib/support/nginx/gitlab origin/8-1-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-git-http-server listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-1-stable/lib/support/init.d/gitlab.default.example#L34 - -### 8. Start application - - sudo service gitlab start - sudo service nginx restart - -### 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 7.14 to 8.0](7.14-to-8.0.md), except for the database migration -(The backup is already migrated to the previous version) - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -## Troubleshooting - -### "You appear to have cloned an empty repository." - -See the [7.14 to 8.0 update guide](7.14-to-8.0.md#troubleshooting). - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-1-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.1-to-8.2.md b/doc/update/8.1-to-8.2.md index 2d0b19abd74..8514aa13f48 100644 --- a/doc/update/8.1-to-8.2.md +++ b/doc/update/8.1-to-8.2.md @@ -1,198 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.1 to 8.2 - -**NOTE:** GitLab 8.0 introduced several significant changes related to -installation and configuration which *are not duplicated here*. Be sure you're -already running a working version of at least 8.0 before proceeding with this -guide. - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version: - -```sh -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source -installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-2-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-2-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch -sudo -u git -H git checkout v2.6.8 -``` - -### 5. Replace gitlab-git-http-server with gitlab-workhorse - -Install and compile gitlab-workhorse. This requires [Go -1.5](https://golang.org/dl) which should already be on your system -from GitLab 8.1. - -```bash -cd /home/git -sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-workhorse.git -cd gitlab-workhorse -sudo -u git -H git checkout 0.4.2 -sudo -u git -H make -``` - -Update the GitLab 'default' file. - -``` -cd /home/git/gitlab -test -e /etc/default/gitlab && \ - sudo sed -i.pre-8.2 's/^\([^=]*\)gitlab_git_http_server/\1gitlab_workhorse/' /etc/default/gitlab -``` - -Make sure that you also update your **NGINX configuration** to use -the new gitlab-workhorse.socket file. - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -# Update init.d script -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-1-stable:config/gitlab.yml.example origin/8-2-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -View changes between the previous recommended Nginx configuration and the -current one: - -```sh -# For HTTPS configurations -git diff origin/8-1-stable:lib/support/nginx/gitlab-ssl origin/8-2-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-1-stable:lib/support/nginx/gitlab origin/8-2-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-2-stable/lib/support/init.d/gitlab.default.example#L34 - -### 8. Start application - - sudo service gitlab start - sudo service nginx restart - -### 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.0 to 8.1](8.0-to-8.1.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -## Troubleshooting - -### "You appear to have cloned an empty repository." - -See the [7.14 to 8.0 update guide](7.14-to-8.0.md#troubleshooting). - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-2-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.10-to-8.11.md b/doc/update/8.10-to-8.11.md index f8415b5159b..8514aa13f48 100644 --- a/doc/update/8.10-to-8.11.md +++ b/doc/update/8.10-to-8.11.md @@ -1,205 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.10 to 8.11 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz -echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz -cd ruby-2.3.1 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-11-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-11-stable-ee -``` - -### 5. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v3.4.0 -``` - -### 6. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.7.11 -sudo -u git -H make -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-10-stable:config/gitlab.yml.example origin/8-11-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-10-stable:lib/support/nginx/gitlab-ssl origin/8-11-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-10-stable:lib/support/nginx/gitlab origin/8-11-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-11-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-11-stable/config/initializers/smtp_settings.rb.sample#L13? - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.10) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.9 to 8.10](8.9-to-8.10.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-11-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.11-to-8.12.md b/doc/update/8.11-to-8.12.md index 07ac8129b4f..8514aa13f48 100644 --- a/doc/update/8.11-to-8.12.md +++ b/doc/update/8.11-to-8.12.md @@ -1,213 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.11 to 8.12 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz -echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz -cd ruby-2.3.1 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-12-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-12-stable-ee -``` - -### 5. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v3.6.1 -``` - -### 6. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.8.2 -sudo -u git -H make -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-11-stable:config/gitlab.yml.example origin/8-12-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-11-stable:lib/support/nginx/gitlab-ssl origin/8-12-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-11-stable:lib/support/nginx/gitlab origin/8-12-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-12-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-12-stable/config/initializers/smtp_settings.rb.sample#L13? - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.11) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.10 to 8.11](8.10-to-8.11.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-12-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.12-to-8.13.md b/doc/update/8.12-to-8.13.md index bf622deaba8..8514aa13f48 100644 --- a/doc/update/8.12-to-8.13.md +++ b/doc/update/8.12-to-8.13.md @@ -1,213 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.12 to 8.13 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz -echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz -cd ruby-2.3.1 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-13-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-13-stable-ee -``` - -### 5. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v3.6.7 -``` - -### 6. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.8.5 -sudo -u git -H make -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-12-stable:config/gitlab.yml.example origin/8-13-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-12-stable:lib/support/nginx/gitlab-ssl origin/8-13-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-12-stable:lib/support/nginx/gitlab origin/8-13-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.12) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.11 to 8.12](8.11-to-8.12.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-13-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.13-to-8.14.md b/doc/update/8.13-to-8.14.md index 43b636ea958..8514aa13f48 100644 --- a/doc/update/8.13-to-8.14.md +++ b/doc/update/8.13-to-8.14.md @@ -1,213 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.13 to 8.14 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz -echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz -cd ruby-2.3.1 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-14-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-14-stable-ee -``` - -### 5. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v4.1.1 -``` - -### 6. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v1.0.1 -sudo -u git -H make -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-13-stable:config/gitlab.yml.example origin/8-14-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-13-stable:lib/support/nginx/gitlab-ssl origin/8-14-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-13-stable:lib/support/nginx/gitlab origin/8-14-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-14-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-14-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.13) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.12 to 8.13](8.12-to-8.13.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-14-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.14-to-8.15.md b/doc/update/8.14-to-8.15.md index eadf1743597..8514aa13f48 100644 --- a/doc/update/8.14-to-8.15.md +++ b/doc/update/8.14-to-8.15.md @@ -1,243 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.14 to 8.15 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.1.tar.gz -echo 'c39b4001f7acb4e334cb60a0f4df72d434bef711 ruby-2.3.1.tar.gz' | shasum --check - && tar xzf ruby-2.3.1.tar.gz -cd ruby-2.3.1 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 8-15-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 8-15-stable-ee -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -### 6. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v4.1.1 -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/8-14-stable:config/gitlab.yml.example origin/8-15-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -cd /home/git/gitlab - -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/8-14-stable:lib/support/nginx/gitlab-ssl origin/8-15-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-14-stable:lib/support/nginx/gitlab origin/8-15-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 9. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.14) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.13 to 8.14](8.13-to-8.14.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-15-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.15-to-8.16.md b/doc/update/8.15-to-8.16.md index 4e8d54d5010..8514aa13f48 100644 --- a/doc/update/8.15-to-8.16.md +++ b/doc/update/8.15-to-8.16.md @@ -1,245 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.15 to 8.16 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 8-16-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 8-16-stable-ee -``` - -### 5. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 6. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v4.1.1 -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/8-15-stable:config/gitlab.yml.example origin/8-16-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -cd /home/git/gitlab - -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/8-15-stable:lib/support/nginx/gitlab-ssl origin/8-16-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-15-stable:lib/support/nginx/gitlab origin/8-16-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 9. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.15) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.14 to 8.15](8.14-to-8.15.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.16-to-8.17.md b/doc/update/8.16-to-8.17.md index cab28a4d1c6..8514aa13f48 100644 --- a/doc/update/8.16-to-8.17.md +++ b/doc/update/8.16-to-8.17.md @@ -1,272 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.16 to 8.17 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -We will continue supporting Ruby < 2.3 for the time being but we recommend you -upgrade to Ruby 2.3 if you're running a source installation, as this is the same -version that ships with our Omnibus package. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - -### 5. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 8-17-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 8-17-stable-ee -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Install/update frontend asset dependencies -sudo -u git -H npm install --production - -# Clean up assets and cache -sudo -u git -H bundle exec rake gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 7. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production -``` - -### 8. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v4.1.1 -``` - -### 9. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/8-16-stable:config/gitlab.yml.example origin/8-17-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -cd /home/git/gitlab - -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/8-16-stable:lib/support/nginx/gitlab-ssl origin/8-17-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-16-stable:lib/support/nginx/gitlab origin/8-17-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. -You need to update this file if you want to [enable GitLab Pages][pages-admin]. -View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/8-16-stable:lib/support/init.d/gitlab.default.example origin/8-17-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 10. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 11. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.16) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.15 to 8.16](8.15-to-8.16.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-17-stable/lib/support/init.d/gitlab.default.example -[pages-admin]: ../administration/pages/source.md +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.17-to-9.0.md b/doc/update/8.17-to-9.0.md index 55cf0842df4..8514aa13f48 100644 --- a/doc/update/8.17-to-9.0.md +++ b/doc/update/8.17-to-9.0.md @@ -1,358 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.17 to 9.0 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 only supports Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-0-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-0-stable-ee -``` - -### 6. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -``` - -### 7. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/8-17-stable:config/gitlab.yml.example origin/9-0-stable:config/gitlab.yml.example -``` - -#### Configuration changes for repository storages - -This version introduces a new configuration structure for repository storages. -Update your current configuration as follows, replacing with your storages names and paths: - -**For installations from source** - -1. Update your `gitlab.yml`, from - - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: /home/git/repositories - nfs: /mnt/nfs/repositories - cephfs: /mnt/cephfs/repositories - ``` - - to - - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: - path: /home/git/repositories - nfs: - path: /mnt/nfs/repositories - cephfs: - path: /mnt/cephfs/repositories - ``` - -**For Omnibus installations** - -1. Update your `/etc/gitlab/gitlab.rb`, from - - ```ruby - git_data_dirs({ - "default" => "/var/opt/gitlab/git-data", - "nfs" => "/mnt/nfs/git-data", - "cephfs" => "/mnt/cephfs/git-data" - }) - ``` - - to - - ```ruby - git_data_dirs({ - "default" => { "path" => "/var/opt/gitlab/git-data" }, - "nfs" => { "path" => "/mnt/nfs/git-data" }, - "cephfs" => { "path" => "/mnt/cephfs/git-data" } - }) - ``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -cd /home/git/gitlab - -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/8-17-stable:lib/support/nginx/gitlab-ssl origin/9-0-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-17-stable:lib/support/nginx/gitlab origin/9-0-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/8-17-stable:lib/support/init.d/gitlab.default.example origin/9-0-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 9. Install libs, migrations, etc. - -GitLab 9.0.11 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on the `re2` regular expression library. To install this dependency: - -```bash -sudo apt-get install libre2-dev -``` - -Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but -you can [install re2 manually](https://github.com/google/re2/wiki/Install). - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 10. Optional: install Gitaly - -Gitaly is still an optional component of GitLab. If you want to save time -during your 9.0 upgrade **you can skip this step**. - -If you do want to set up Gitaly in GitLab 9.0 then follow [Gitaly section of the installation -guide](../install/installation.md#install-gitaly). - -### 11. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 12. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.17) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.16 to 8.17](8.16-to-8.17.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-0-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.2-to-8.3.md b/doc/update/8.2-to-8.3.md index 3a0d647cbfe..8514aa13f48 100644 --- a/doc/update/8.2-to-8.3.md +++ b/doc/update/8.2-to-8.3.md @@ -1,227 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.2 to 8.3 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -**NOTE:** GitLab 8.0 introduced several significant changes related to -installation and configuration which *are not duplicated here*. Be sure you're -already running a working version of at least 8.0 before proceeding with this -guide. - -### 0. Double-check your Git version - -**This notice applies only to /usr/local/bin/git** - -If you compiled Git from source on your GitLab server then please double-check -that you are using a version that protects against CVE-2014-9390. For six -months after this vulnerability became known the GitLab installation guide -still contained instructions that would install the outdated, 'vulnerable' Git -version 2.1.2. - -Run the following command to get your current Git version: - -```sh -/usr/local/bin/git --version -``` - -If you see 'No such file or directory' then you did not install Git according -to the outdated instructions from the GitLab installation guide and you can go -to the next step 'Stop server' below. - -If you see a version string then it should be v1.8.5.6, v1.9.5, v2.0.5, v2.1.4, -v2.2.1 or newer. You can use the [instructions in the GitLab source installation -guide](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/install/installation.md#1-packages-dependencies) -to install a newer version of Git. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-3-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-3-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all -sudo -u git -H git checkout v2.6.9 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires [Go 1.5](https://golang.org/dl) -which should already be on your system from GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout 0.5.4 -sudo -u git -H make -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-2-stable:config/gitlab.yml.example origin/8-3-stable:config/gitlab.yml.example -``` - -#### GitLab default file - -The value of the `gitlab_workhorse_options` variable should be updated within the default gitlab file (`/etc/default/gitlab`) according to the following diff: - -```sh -git diff origin/8-2-stable:lib/support/init.d/gitlab.default.example origin/8-3-stable:lib/support/init.d/gitlab.default.example -``` - -#### Nginx configuration - -GitLab 8.3 introduces major changes in the NGINX configuration. -Because all HTTP requests pass through gitlab-workhorse now a lot of -directives need to be removed from NGINX. During future upgrades there -should be much less changes in the NGINX configuration because of -this. - -View changes between the previous recommended Nginx configuration and the -current one: - -```sh -# For HTTPS configurations -git diff origin/8-2-stable:lib/support/nginx/gitlab-ssl origin/8-3-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-2-stable:lib/support/nginx/gitlab origin/8-3-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-3-stable/lib/support/init.d/gitlab.default.example#L34 - -#### Init script - -We updated the init script for GitLab in order to pass new -configuration options to gitlab-workhorse. We let gitlab-workhorse -connect to the Rails application via a Unix domain socket and we tell -it where the 'public' directory of GitLab is. - -``` -cd /home/git/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 8. Use Redis v2.8.0+ - -Previous versions of GitLab allowed Redis versions >= 2.0 to be used, but -GitLab 8.3 uses Sidekiq 4.0, which requires Redis 2.8. You can check your Redis version -with the following command: - - redis-cli info | grep redis_version - -If you need to upgrade, see the [installation guide for Redis](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-3-stable/doc/install/installation.md#6-redis). - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.1 to 8.2](8.1-to-8.2.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -## Troubleshooting - -### "You appear to have cloned an empty repository." - -See the [7.14 to 8.0 update guide](7.14-to-8.0.md#troubleshooting). - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-3-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.3-to-8.4.md b/doc/update/8.3-to-8.4.md index f5162dd5ff5..8514aa13f48 100644 --- a/doc/update/8.3-to-8.4.md +++ b/doc/update/8.3-to-8.4.md @@ -1,143 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.3 to 8.4 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-4-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-4-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all -sudo -u git -H git checkout v2.6.10 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires [Go 1.5](https://golang.org/dl) -which should already be on your system from GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout 0.6.2 -sudo -u git -H make -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-3-stable:config/gitlab.yml.example origin/8-4-stable:config/gitlab.yml.example -``` - -#### Init script - -We updated the init script for GitLab in order to set a specific PATH for gitlab-workhorse. - -``` -cd /home/git/gitlab -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 8. Start application - - sudo service gitlab start - sudo service nginx restart - -### 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.2 to 8.3](8.2-to-8.3.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-4-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.4-to-8.5.md b/doc/update/8.4-to-8.5.md index 9e2f98add8d..8514aa13f48 100644 --- a/doc/update/8.4-to-8.5.md +++ b/doc/update/8.4-to-8.5.md @@ -1,164 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.4 to 8.5 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-5-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all -sudo -u git -H git checkout v2.6.10 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout 0.6.4 -sudo -u git -H make -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-4-stable:config/gitlab.yml.example origin/8-5-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-4-stable:lib/support/nginx/gitlab-ssl origin/8-5-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-4-stable:lib/support/nginx/gitlab origin/8-5-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-5-stable/lib/support/init.d/gitlab.default.example#L37 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 8. Start application - - sudo service gitlab start - sudo service nginx restart - -### 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.4) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.3 to 8.4](8.3-to-8.4.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-5-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.5-to-8.6.md b/doc/update/8.5-to-8.6.md index 55d8178c407..8514aa13f48 100644 --- a/doc/update/8.5-to-8.6.md +++ b/doc/update/8.5-to-8.6.md @@ -1,183 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.5 to 8.6 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-6-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-6-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all -sudo -u git -H git checkout v2.6.12 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.7.1 -sudo -u git -H make -``` - -### 6. Updates for PostgreSQL Users - -Starting with 8.6 users using GitLab in combination with PostgreSQL are required -to have the `pg_trgm` extension enabled for all GitLab databases. If you're -using GitLab's Omnibus packages there's nothing you'll need to do manually as -this extension is enabled automatically. Users who install GitLab without using -Omnibus (e.g. by building from source) have to enable this extension manually. -To enable this extension run the following SQL command as a PostgreSQL super -user for _every_ GitLab database: - -```sql -CREATE EXTENSION IF NOT EXISTS pg_trgm; -``` - -Certain operating systems might require the installation of extra packages for -this extension to be available. For example, users using Ubuntu will have to -install the `postgresql-contrib` package in order for this extension to be -available. - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-5-stable:config/gitlab.yml.example origin/8-6-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-5-stable:lib/support/nginx/gitlab-ssl origin/8-6-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-5-stable:lib/support/nginx/gitlab origin/8-6-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-6-stable/lib/support/init.d/gitlab.default.example#L37 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.5) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.4 to 8.5](8.4-to-8.5.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-6-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.6-to-8.7.md b/doc/update/8.6-to-8.7.md index 49db6f2967c..8514aa13f48 100644 --- a/doc/update/8.6-to-8.7.md +++ b/doc/update/8.6-to-8.7.md @@ -1,172 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.6 to 8.7 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-7-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-7-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --tags -sudo -u git -H git checkout v2.7.2 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.7.1 -sudo -u git -H make -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-6-stable:config/gitlab.yml.example origin/8-7-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Disable `git gc --auto` because GitLab runs `git gc` for us already. - -```sh -sudo -u git -H git config --global gc.auto 0 -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-6-stable:lib/support/nginx/gitlab-ssl origin/8-7-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-6-stable:lib/support/nginx/gitlab origin/8-7-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-7-stable/lib/support/init.d/gitlab.default.example#L37 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 8. Start application - - sudo service gitlab start - sudo service nginx restart - -### 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.6) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.5 to 8.6](8.5-to-8.6.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-7-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.7-to-8.8.md b/doc/update/8.7-to-8.8.md index ee7ec6f7614..8514aa13f48 100644 --- a/doc/update/8.7-to-8.8.md +++ b/doc/update/8.7-to-8.8.md @@ -1,172 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.7 to 8.8 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-8-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-8-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v2.7.2 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.7.1 -sudo -u git -H make -``` - -### 6. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 7. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-7-stable:config/gitlab.yml.example origin/8-8-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Disable `git gc --auto` because GitLab runs `git gc` for us already. - -```sh -sudo -u git -H git config --global gc.auto 0 -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-7-stable:lib/support/nginx/gitlab-ssl origin/8-8-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-7-stable:lib/support/nginx/gitlab origin/8-8-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-8-stable/lib/support/init.d/gitlab.default.example#L37 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 8. Start application - - sudo service gitlab start - sudo service nginx restart - -### 9. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.7) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.6 to 8.7](8.6-to-8.7.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-8-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.8-to-8.9.md b/doc/update/8.8-to-8.9.md index 7508443c30a..8514aa13f48 100644 --- a/doc/update/8.8-to-8.9.md +++ b/doc/update/8.8-to-8.9.md @@ -1,201 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.8 to 8.9 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-9-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-9-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v3.0.0 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.7.5 -sudo -u git -H make -``` - -### 6. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -# Login to MySQL -mysql -u root -p - -# Grant the GitLab user the REFERENCES permission on the database -GRANT REFERENCES ON `gitlabhq_production`.* TO 'git'@'localhost'; - -# Quit the database session -mysql> \q -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-8-stable:config/gitlab.yml.example origin/8-9-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Disable `git gc --auto` because GitLab runs `git gc` for us already. - -```sh -sudo -u git -H git config --global gc.auto 0 -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-8-stable:lib/support/nginx/gitlab-ssl origin/8-9-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-8-stable:lib/support/nginx/gitlab origin/8-9-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-9-stable/lib/support/init.d/gitlab.default.example#L37 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/v8.9.0/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.8) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.7 to 8.8](8.7-to-8.8.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-9-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/8.9-to-8.10.md b/doc/update/8.9-to-8.10.md index 915e7db819a..8514aa13f48 100644 --- a/doc/update/8.9-to-8.10.md +++ b/doc/update/8.9-to-8.10.md @@ -1,201 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 8.9 to 8.10 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - - sudo service gitlab stop - -### 2. Backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Get latest code - -```bash -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -sudo -u git -H git checkout 8-10-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -sudo -u git -H git checkout 8-10-stable-ee -``` - -### 4. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v3.2.1 -``` - -### 5. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. - -```bash -cd /home/git/gitlab-workhorse -sudo -u git -H git fetch --all -sudo -u git -H git checkout v0.7.8 -sudo -u git -H make -``` - -### 6. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -# Login to MySQL -mysql -u root -p - -# Grant the GitLab user the REFERENCES permission on the database -GRANT REFERENCES ON `gitlabhq_production`.* TO 'git'@'localhost'; - -# Quit the database session -mysql> \q -``` - -### 7. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Clean up assets and cache -sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production - -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There are new configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -git diff origin/8-9-stable:config/gitlab.yml.example origin/8-10-stable:config/gitlab.yml.example -``` - -#### Git configuration - -Disable `git gc --auto` because GitLab runs `git gc` for us already. - -```sh -sudo -u git -H git config --global gc.auto 0 -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -# For HTTPS configurations -git diff origin/8-9-stable:lib/support/nginx/gitlab-ssl origin/8-10-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/8-9-stable:lib/support/nginx/gitlab origin/8-10-stable:lib/support/nginx/gitlab -``` - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-10-stable/lib/support/init.d/gitlab.default.example#L37 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/v8.9.0/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -Ensure you're still up-to-date with the latest init script changes: - - sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab - -For Ubuntu 16.04.1 LTS: - - sudo systemctl daemon-reload - -### 9. Start application - - sudo service gitlab start - sudo service nginx restart - -### 10. Check application status - -Check if GitLab and its environment are configured correctly: - - sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production - -To make sure you didn't miss anything run a more thorough check: - - sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (8.9) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.8 to 8.9](8.8-to-8.9.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-10-stable/config/gitlab.yml.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/9.0-to-9.1.md b/doc/update/9.0-to-9.1.md index 10214fd8aca..8514aa13f48 100644 --- a/doc/update/9.0-to-9.1.md +++ b/doc/update/9.0-to-9.1.md @@ -1,407 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 9.0 to 9.1 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-1-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-1-stable-ee -``` - -### 6. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -``` - -### 7. Update gitlab-workhorse - -Install and compile gitlab-workhorse. This requires -[Go 1.5](https://golang.org/dl) which should already be on your system from -GitLab 8.1. GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 8. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/9-0-stable:config/gitlab.yml.example origin/9-1-stable:config/gitlab.yml.example -``` - -#### Configuration changes for repository storages - -This version introduces a new configuration structure for repository storages. -Update your current configuration as follows, replacing with your storages names and paths: - -**For installations from source** - -1. Update your `gitlab.yml`, from - - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: /home/git/repositories - nfs: /mnt/nfs/repositories - cephfs: /mnt/cephfs/repositories - ``` - - to - - ```yaml - repositories: - storages: # You must have at least a 'default' storage path. - default: - path: /home/git/repositories - nfs: - path: /mnt/nfs/repositories - cephfs: - path: /mnt/cephfs/repositories - ``` - -**For Omnibus installations** - -1. Update your `/etc/gitlab/gitlab.rb`, from - - ```ruby - git_data_dirs({ - "default" => "/var/opt/gitlab/git-data", - "nfs" => "/mnt/nfs/git-data", - "cephfs" => "/mnt/cephfs/git-data" - }) - ``` - - to - - ```ruby - git_data_dirs({ - "default" => { "path" => "/var/opt/gitlab/git-data" }, - "nfs" => { "path" => "/mnt/nfs/git-data" }, - "cephfs" => { "path" => "/mnt/cephfs/git-data" } - }) - ``` - -#### Git configuration - -Configure Git to generate packfile bitmaps (introduced in Git 2.0) on -the GitLab server during `git gc`. - -```sh -cd /home/git/gitlab - -sudo -u git -H git config --global repack.writeBitmaps true -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/9-0-stable:lib/support/nginx/gitlab-ssl origin/9-1-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/9-0-stable:lib/support/nginx/gitlab origin/9-1-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/9-0-stable:lib/support/init.d/gitlab.default.example origin/9-1-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 9. Install libs, migrations, etc. - -GitLab 9.1.8 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on the `re2` regular expression library. To install this dependency: - -```bash -sudo apt-get install libre2-dev -``` - -Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but -you can [install re2 manually](https://github.com/google/re2/wiki/Install). - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 10. Optional: install Gitaly - -Gitaly is still an optional component of GitLab. If you want to save time -during your 9.1 upgrade **you can skip this step**. - -If you have not yet set up Gitaly then follow [Gitaly section of the installation -guide](../install/installation.md#install-gitaly). - -If you installed Gitaly in GitLab 9.0 you need to make some changes in -gitlab.yml, and create a new config.toml file. - -#### Gitaly gitlab.yml changes - -Look for `socket_path:` the `gitaly:` section. Its value is usually -`/home/git/gitlab/tmp/sockets/private/gitaly.socket`. Note what socket -path your gitlab.yml is using. Now go to the `repositories:` section, -and for each entry under `storages:`, add a `gitaly_address:` based on -the socket path, but with `unix:` in front. - -```yaml - repositories: - storages: - default: - path: /home/git/repositories - gitaly_address: unix:/home/git/gitlab/tmp/sockets/private/gitaly.socket - other_storage: - path: /home/git/other-repositories - gitaly_address: unix:/home/git/gitlab/tmp/sockets/private/gitaly.socket -``` - -Each entry under `storages:` should use the same `gitaly_address`. - -#### Compile Gitaly - -This step will also create `config.toml.example` which you need below. - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -#### Gitaly config.toml - -In GitLab 9.1 we are replacing environment variables in Gitaly with a -TOML configuration file. - -```shell -cd /home/git/gitaly - -sudo mv env env.old -sudo -u git cp config.toml.example config.toml -# If you are using custom repository storage paths they need to be in config.toml -sudo -u git -H editor config.toml -``` - -### 11. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 12. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (9.0) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 8.17 to 9.0](8.17-to-9.0.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/9.1-to-9.2.md b/doc/update/9.1-to-9.2.md index 79d92f05257..8514aa13f48 100644 --- a/doc/update/9.1-to-9.2.md +++ b/doc/update/9.1-to-9.2.md @@ -1,330 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 9.1 to 9.2 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-2-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-2-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/9-1-stable:config/gitlab.yml.example origin/9-2-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/9-1-stable:lib/support/nginx/gitlab-ssl origin/9-2-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/9-1-stable:lib/support/nginx/gitlab origin/9-2-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-2-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-2-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/9-1-stable:lib/support/init.d/gitlab.default.example origin/9-2-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 10. Install libs, migrations, etc. - -GitLab 9.2.8 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on the `re2` regular expression library. To install this dependency: - -```bash -sudo apt-get install libre2-dev -``` - -Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but -you can [install re2 manually](https://github.com/google/re2/wiki/Install). - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:pack RAILS_ENV=production -sudo -u git -H bundle exec rake gettext:po_to_json RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 11. Optional: install Gitaly - -Gitaly is still an optional component of GitLab. If you want to save time -during your 9.2 upgrade **you can skip this step**. - -If you have not yet set up Gitaly then follow [Gitaly section of the installation -guide](../install/installation.md#install-gitaly). - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 12. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 13. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (9.1) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 9.0 to 9.1](9.0-to-9.1.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-2-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-2-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/9.2-to-9.3.md b/doc/update/9.2-to-9.3.md index 98443b8bfa6..8514aa13f48 100644 --- a/doc/update/9.2-to-9.3.md +++ b/doc/update/9.2-to-9.3.md @@ -1,348 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 9.2 to 9.3 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-3-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-3-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -If you have not yet set up Gitaly then follow [Gitaly section of the installation -guide](../install/installation.md#install-gitaly). - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/9-2-stable:config/gitlab.yml.example origin/9-3-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/9-2-stable:lib/support/nginx/gitlab-ssl origin/9-3-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/9-2-stable:lib/support/nginx/gitlab origin/9-3-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-3-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-3-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/9-2-stable:lib/support/init.d/gitlab.default.example origin/9-3-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -GitLab 9.3.8 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on the `re2` regular expression library. To install this dependency: - -```bash -sudo apt-get install libre2-dev -``` - -Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but -you can [install re2 manually](https://github.com/google/re2/wiki/Install). - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (9.2) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 9.1 to 9.2](9.1-to-9.2.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-3-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-3-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/9.3-to-9.4.md b/doc/update/9.3-to-9.4.md index 640b9c3997e..8514aa13f48 100644 --- a/doc/update/9.3-to-9.4.md +++ b/doc/update/9.3-to-9.4.md @@ -1,361 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 9.3 to 9.4 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-4-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-4-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -If you have not yet set up Gitaly then follow [Gitaly section of the installation -guide](../install/installation.md#install-gitaly). - -As of GitLab 9.4, Gitaly is a mandatory component of GitLab. - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-9.4 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/9-3-stable:config/gitlab.yml.example origin/9-4-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/9-3-stable:lib/support/nginx/gitlab-ssl origin/9-4-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/9-3-stable:lib/support/nginx/gitlab origin/9-4-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-4-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-4-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/9-3-stable:lib/support/init.d/gitlab.default.example origin/9-4-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -GitLab 9.4 [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24570) -a dependency on the `re2` regular expression library. To install this dependency: - -```bash -sudo apt-get install libre2-dev -``` - -Ubuntu 14.04 (Trusty Tahr) doesn't have the `libre2-dev` package available, but -you can [install re2 manually](https://github.com/google/re2/wiki/Install). - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (9.3) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 9.2 to 9.3](9.2-to-9.3.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-4-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-4-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/9.4-to-9.5.md b/doc/update/9.4-to-9.5.md index e6cfa70975e..8514aa13f48 100644 --- a/doc/update/9.4-to-9.5.md +++ b/doc/update/9.4-to-9.5.md @@ -1,360 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 9.4 to 9.5 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-5-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 9-5-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-9.5 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/9-4-stable:config/gitlab.yml.example origin/9-5-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/9-4-stable:lib/support/nginx/gitlab-ssl origin/9-5-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/9-4-stable:lib/support/nginx/gitlab origin/9-5-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-5-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-5-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/9-4-stable:lib/support/init.d/gitlab.default.example origin/9-5-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (9.4) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 9.3 to 9.4](9.3-to-9.4.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-5-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-5-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/9.5-to-10.0.md b/doc/update/9.5-to-10.0.md index 8b565f67cb1..8514aa13f48 100644 --- a/doc/update/9.5-to-10.0.md +++ b/doc/update/9.5-to-10.0.md @@ -1,360 +1,5 @@ --- -comments: false +redirect_to: upgrading_from_source.md --- -# From 9.5 to 10.0 - -Make sure you view this update guide from the tag (version) of GitLab you would -like to install. In most cases this should be the highest numbered production -tag (without rc in it). You can select the tag in the version dropdown at the -top left corner of GitLab (below the menu bar). - -If the highest number stable branch is unclear please check the -[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation -guide links by version. - -### 1. Stop server - -```bash -sudo service gitlab stop -``` - -### 2. Backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production -``` - -### 3. Update Ruby - -NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be -sure to upgrade your interpreter if necessary. - -You can check which version you are running with `ruby -v`. - -Download and compile Ruby: - -```bash -mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz -echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz -cd ruby-2.3.3 -./configure --disable-install-rdoc -make -sudo make install -``` - -Install Bundler: - -```bash -sudo gem install bundler --no-document --version '< 2' -``` - -### 4. Update Node - -GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and -it has a minimum requirement of node v4.3.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v4.3.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. - -<https://nodejs.org/en/download/> - - -Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage -JavaScript dependencies. - -```bash -curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -sudo apt-get update -sudo apt-get install yarn -``` - -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). - -### 5. Update Go - -NOTE: GitLab 9.2 and higher only supports Go 1.8.3 and dropped support for Go -1.5.x through 1.7.x. Be sure to upgrade your installation if necessary. - -You can check which version you are running with `go version`. - -Download and install Go: - -```bash -# Remove former Go installation folder -sudo rm -rf /usr/local/go - -curl --remote-name --progress https://storage.googleapis.com/golang/go1.8.3.linux-amd64.tar.gz -echo '1862f4c3d3907e59b04a757cfda0ea7aa9ef39274af99a784f5be843c80c6772 go1.8.3.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.8.3.linux-amd64.tar.gz -sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.8.3.linux-amd64.tar.gz -``` - -### 6. Get latest code - -```bash -cd /home/git/gitlab - -sudo -u git -H git fetch --all -sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically -sudo -u git -H git checkout -- locale -``` - -For GitLab Community Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-0-stable -``` - -OR - -For GitLab Enterprise Edition: - -```bash -cd /home/git/gitlab - -sudo -u git -H git checkout 10-0-stable-ee -``` - -### 7. Update gitlab-shell - -```bash -cd /home/git/gitlab-shell - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) -sudo -u git -H bin/compile -``` - -### 8. Update gitlab-workhorse - -Install and compile gitlab-workhorse. GitLab-Workhorse uses -[GNU Make](https://www.gnu.org/software/make/). -If you are not using Linux you may have to run `gmake` instead of -`make` below. - -```bash -cd /home/git/gitlab-workhorse - -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) -sudo -u git -H make -``` - -### 9. Update Gitaly - -#### New Gitaly configuration options required - -In order to function Gitaly needs some additional configuration information. Below we assume you installed Gitaly in `/home/git/gitaly` and GitLab Shell in `/home/git/gitlab-shell`. - -```shell -echo ' -[gitaly-ruby] -dir = "/home/git/gitaly/ruby" - -[gitlab-shell] -dir = "/home/git/gitlab-shell" -' | sudo -u git tee -a /home/git/gitaly/config.toml -``` - -#### Check Gitaly configuration - -Due to a bug in the `rake gitlab:gitaly:install` script your Gitaly -configuration file may contain syntax errors. The block name -`[[storages]]`, which may occur more than once in your `config.toml` -file, should be `[[storage]]` instead. - -```shell -sudo -u git -H sed -i.pre-10.0 's/\[\[storages\]\]/[[storage]]/' /home/git/gitaly/config.toml -``` - -#### Compile Gitaly - -```shell -cd /home/git/gitaly -sudo -u git -H git fetch --all --tags -sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) -sudo -u git -H make -``` - -### 10. Update MySQL permissions - -If you are using MySQL you need to grant the GitLab user the necessary -permissions on the database: - -```bash -mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" -``` - -If you use MySQL with replication, or just have MySQL configured with binary logging, -you will need to also run the following on all of your MySQL servers: - -```bash -mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" -``` - -You can make this setting permanent by adding it to your `my.cnf`: - -``` -log_bin_trust_function_creators=1 -``` - -### 11. Update configuration files - -#### New configuration options for `gitlab.yml` - -There might be configuration options available for [`gitlab.yml`][yaml]. View them with the command below and apply them manually to your current `gitlab.yml`: - -```sh -cd /home/git/gitlab - -git diff origin/9-5-stable:config/gitlab.yml.example origin/10-0-stable:config/gitlab.yml.example -``` - -#### Nginx configuration - -Ensure you're still up-to-date with the latest NGINX configuration changes: - -```sh -cd /home/git/gitlab - -# For HTTPS configurations -git diff origin/9-5-stable:lib/support/nginx/gitlab-ssl origin/10-0-stable:lib/support/nginx/gitlab-ssl - -# For HTTP configurations -git diff origin/9-5-stable:lib/support/nginx/gitlab origin/10-0-stable:lib/support/nginx/gitlab -``` - -If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your Nginx -configuration as GitLab application no longer handles setting it. - -If you are using Apache instead of NGINX please see the updated [Apache templates]. -Also note that because Apache does not support upstreams behind Unix sockets you -will need to let gitlab-workhorse listen on a TCP port. You can do this -via [/etc/default/gitlab]. - -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache -[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-0-stable/lib/support/init.d/gitlab.default.example#L38 - -#### SMTP configuration - -If you're installing from source and use SMTP to deliver mail, you will need to add the following line -to config/initializers/smtp_settings.rb: - -```ruby -ActionMailer::Base.delivery_method = :smtp -``` - -See [smtp_settings.rb.sample] as an example. - -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-0-stable/config/initializers/smtp_settings.rb.sample#L13 - -#### Init script - -There might be new configuration options available for [`gitlab.default.example`][gl-example]. View them with the command below and apply them manually to your current `/etc/default/gitlab`: - -```sh -cd /home/git/gitlab - -git diff origin/9-5-stable:lib/support/init.d/gitlab.default.example origin/10-0-stable:lib/support/init.d/gitlab.default.example -``` - -Ensure you're still up-to-date with the latest init script changes: - -```bash -cd /home/git/gitlab - -sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab -``` - -For Ubuntu 16.04.1 LTS: - -```bash -sudo systemctl daemon-reload -``` - -### 12. Install libs, migrations, etc. - -```bash -cd /home/git/gitlab - -# MySQL installations (note: the line below states '--without postgres') -sudo -u git -H bundle install --without postgres development test --deployment - -# PostgreSQL installations (note: the line below states '--without mysql') -sudo -u git -H bundle install --without mysql development test --deployment - -# Optional: clean up old gems -sudo -u git -H bundle clean - -# Run database migrations -sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production - -# Compile GetText PO files - -sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production - -# Update node dependencies and recompile assets -sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production - -# Clean up cache -sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production -``` - -**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). - -### 13. Start application - -```bash -sudo service gitlab start -sudo service nginx restart -``` - -### 14. Check application status - -Check if GitLab and its environment are configured correctly: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production -``` - -To make sure you didn't miss anything run a more thorough check: - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production -``` - -If all items are green, then congratulations, the upgrade is complete! - -## Things went south? Revert to previous version (9.5) - -### 1. Revert the code to the previous version - -Follow the [upgrade guide from 9.4 to 9.5](9.4-to-9.5.md), except for the -database migration (the backup is already migrated to the previous version). - -### 2. Restore from the backup - -```bash -cd /home/git/gitlab - -sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production -``` - -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-0-stable/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/10-0-stable/lib/support/init.d/gitlab.default.example +This document was moved to [another location](upgrading_from_source.md). diff --git a/doc/update/README.md b/doc/update/README.md index d4fc0cc91bf..e2fffadb1ea 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -5,32 +5,38 @@ update guides. There are currently 3 official ways to install GitLab: -- Omnibus packages -- Source installation -- Docker installation +- [Omnibus packages](#omnibus-packages) +- [Source installation](#installation-from-source) +- [Docker installation](#installation-using-docker) Based on your installation, choose a section below that fits your needs. ## Omnibus Packages -- The [Omnibus update guide](http://docs.gitlab.com/omnibus/update/README.html) +- The [Omnibus update guide][omni-update] contains the steps needed to update an Omnibus GitLab package. ## Installation from source -- [Upgrading Community Edition from source][source-ce] - The individual - upgrade guides are for those who have installed GitLab CE from source. -- [Upgrading Enterprise Edition from source][source-ee] - The individual - upgrade guides are for those who have installed GitLab EE from source. +- [Upgrading Community Edition and Enterprise Edition from + source](upgrading_from_source.md) - The guidelines for upgrading Community + Edition and Enterprise Edition from source. - [Patch versions](patch_versions.md) guide includes the steps needed for a patch version, eg. 6.2.0 to 6.2.1, and apply to both Community and Enterprise Editions. +In the past we used separate documents for the upgrading instructions, but we +have since switched to using a single document. The old upgrading guidelines +can still be found in the Git repository: + +- [Old upgrading guidelines for Community Edition][old-ce-upgrade-docs] +- [Old upgrading guidelines for Enterprise Edition][old-ee-upgrade-docs] + ## Installation using Docker GitLab provides official Docker images for both Community and Enterprise editions. They are based on the Omnibus package and instructions on how to -update them are in [a separate document][omnidocker]. +update them are in [a separate document][omni-docker]. ## Upgrading without downtime @@ -97,6 +103,10 @@ migrations this could potentially lead to hours of downtime, depending on the size of your database. To work around this you will have to use PostgreSQL and meet the other online upgrade requirements mentioned above. +### Steps + +Steps to [upgrade without downtime][omni-zero-downtime]. + ## Upgrading between editions GitLab comes in two flavors: [Community Edition][ce] which is MIT licensed, @@ -113,11 +123,10 @@ The following guides are for subscribers of the Enterprise Edition only. If you wish to upgrade your GitLab installation from Community to Enterprise Edition, follow the guides below based on the installation method: -- [Source CE to EE update guides][source-ee] - Find your version, and follow the - `-ce-to-ee.md` guide. The steps are very similar to a version upgrade: stop - the server, get the code, update config files for the new functionality, - install libraries and do migrations, update the init script, start the - application and check its status. +- [Source CE to EE update guides][source-ce-to-ee] - The steps are very similar + to a version upgrade: stop the server, get the code, update config files for + the new functionality, install libraries and do migrations, update the init + script, start the application and check its status. - [Omnibus CE to EE][omni-ce-ee] - Follow this guide to update your Omnibus GitLab Community Edition to the Enterprise Edition. @@ -138,9 +147,13 @@ possible. upgrading a PostgreSQL database with minimal downtime. [omnidocker]: http://docs.gitlab.com/omnibus/docker/README.html -[source-ee]: https://gitlab.com/gitlab-org/gitlab-ee/tree/master/doc/update -[source-ce]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/update +[old-ee-upgrade-docs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/11-8-stable-ee/doc/update +[old-ce-upgrade-docs]: https://gitlab.com/gitlab-org/gitlab-ce/tree/11-8-stable/doc/update +[source-ce-to-ee]: upgrading_from_ce_to_ee.md [ee-ce]: ../downgrade_ee_to_ce/README.md [ce]: https://about.gitlab.com/features/#community [ee]: https://about.gitlab.com/features/#enterprise [omni-ce-ee]: https://docs.gitlab.com/omnibus/update/README.html#updating-community-edition-to-enterprise-edition +[omni-docker]: https://docs.gitlab.com/omnibus/docker/README.html +[omni-update]: https://docs.gitlab.com/omnibus/update/README.html +[omni-zero-downtime]: https://docs.gitlab.com/omnibus/update/README.html#zero-downtime-updates diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index 7c6a14cb104..1f4b5fbffa7 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -97,7 +97,6 @@ Now, you can use pgloader to migrate the data from MySQL to PostgreSQL: 1. Once the migration finishes, you should see a summary table that looks like the following: - ``` table name read imported errors total time ----------------------------------------------- --------- --------- --------- -------------- @@ -245,7 +244,6 @@ Now, you can use pgloader to migrate the data from MySQL to PostgreSQL: 1. Once the migration finishes, you should see a summary table that looks like the following: - ``` table name read imported errors total time ----------------------------------------------- --------- --------- --------- -------------- @@ -286,4 +284,3 @@ If you experience 500 errors after the migration, try to clear the cache: ``` bash sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ``` - diff --git a/doc/update/restore_after_failure.md b/doc/update/restore_after_failure.md index 01c52aae7f5..faa3a6e65cb 100644 --- a/doc/update/restore_after_failure.md +++ b/doc/update/restore_after_failure.md @@ -80,4 +80,3 @@ exit Once the migration is successfully marked, run the rake `db:migrate` task again. You will likely have to repeat this process several times until all failed migrations are marked complete. - diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md new file mode 100644 index 00000000000..0d1ecab5f8e --- /dev/null +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -0,0 +1,132 @@ +--- +comments: false +--- + +# Upgrading from Community Edition to Enterprise Edition from source + +NOTE: **NOTE** In the past we used separate documents for upgrading from +Community Edition to Enterprise Edition. These documents can be found in the +[`doc/update` directory of Enterprise Edition's source +code][old-ee-upgrade-docs]. + +## General upgrading steps + +This guide assumes you have a correctly configured and tested installation of +GitLab Community Edition. If you run into any trouble or if you have any +questions please contact us at [support@gitlab.com]. + +In all examples, replace `EE_BRANCH` with the Enterprise Edition branch for the +version you are using, and `CE_BRANCH` with the Community Edition branch. +Branch names use the format `major-minor-stable-ee` for Enterprise Edition, and +`major-minor-stable` for Community Edition. For example, for 11.8.0 you would +use the following branches: + +* Enterprise Edition: `11-8-stable-ee` +* Community Edition: `11-8-stable` + +### 0. Backup + +Make a backup just in case something goes wrong: + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +For installations using MySQL, this may require granting "LOCK TABLES" +privileges to the GitLab user on the database version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Get the EE code + +```bash +cd /home/git/gitlab +sudo -u git -H git remote add -f ee https://gitlab.com/gitlab-org/gitlab-ee.git +sudo -u git -H git checkout EE_BRANCH +``` + +### 3. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Clean up assets and cache +sudo -u git -H bundle exec rake assets:clean assets:precompile cache:clear RAILS_ENV=production +``` + +### 4. Install `gitlab-elasticsearch-indexer` (optional) **[STARTER ONLY]** + +If you're interested in using GitLab's new [elasticsearch repository +indexer][indexer-beta] (currently in beta) please follow the instructions on the +document linked above and enable the indexer usage in the GitLab admin settings. + +### 5. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 6. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check with: + +```bash +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations upgrade complete! + +## Things went south? Revert to previous version (Community Edition) + +### 1. Revert the code to the previous version + +```bash +cd /home/git/gitlab +sudo -u git -H git checkout CE_BRANCH +``` + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +## Version specific steps + +Certain versions of GitLab may require you to perform additional steps when +upgrading from Community Edition to Enterprise Edition. Should such steps be +necessary, they will listed per version below. + +<!-- +Example: + +### 11.8.0 + +Additional instructions here. +--> + +[support@gitlab.com]: mailto:support@gitlab.com +[old-ee-upgrade-docs]: https://gitlab.com/gitlab-org/gitlab-ee/tree/11-8-stable-ee/doc/update +[indexer-beta]: https://docs.gitlab.com/ee/integration/elasticsearch.html diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md new file mode 100644 index 00000000000..20d8ebecc0a --- /dev/null +++ b/doc/update/upgrading_from_source.md @@ -0,0 +1,390 @@ +--- +comments: false +--- + +# Upgrading Community Edition and Enterprise Edition from source + +Make sure you view this update guide from the branch (version) of GitLab you +would like to install (e.g., `11.8`. You can select the version in the version +dropdown at the top left corner of GitLab (below the menu bar). + +In all examples, replace `BRANCH` with the branch for the version you uprading +to (e.g. `11-8-stable` for `11.8`), and replace `PREVIOUS_BRANCH` with the +branch for the version you are upgrading from (e.g. `11-7-stable` for `11.7`). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +## Guidelines for all versions + +This section contains all the steps necessary to upgrade Community Edition or +Enterprise Edition, regardless of the version you are upgrading to. Version +specific guidelines (should there be any) are covered separately. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +NOTE: If you installed GitLab from source, make sure `rsync` is installed. + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: Beginning in GitLab 11.0, we only support Ruby 2.4 or higher, and dropped +support for Ruby 2.3. Be sure to upgrade if necessary. + +You can check which version you are running with `ruby -v`. + +Download Ruby and compile it: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.5/ruby-2.5.3.tar.gz +echo 'f919a9fbcdb7abecd887157b49833663c5c15fda ruby-2.5.3.tar.gz' | shasum -c - && tar xzf ruby-2.5.3.tar.gz +cd ruby-2.5.3 + +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-document --version '< 2' +``` + +### 4. Update Node + +NOTE: Beginning in GitLab 11.8, we only support node 8 or higher, and dropped +support for node 6. Be sure to upgrade if necessary. + +GitLab utilizes [webpack](http://webpack.js.org) to compile frontend assets. +This requires a minimum version of node v8.10.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v8.10.0` you will need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the nodejs.org website. + +<https://nodejs.org/en/download/> + +GitLab also requires the use of yarn `>= v1.10.0` to manage JavaScript +dependencies. + +```bash +curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +sudo apt-get update +sudo apt-get install yarn +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Update Go + +NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go +1.9.x. Be sure to upgrade your installation if necessary. + +You can check which version you are running with `go version`. + +Download and install Go: + +```bash +# Remove former Go installation folder +sudo rm -rf /usr/local/go + +curl --remote-name --progress https://dl.google.com/go/go1.10.5.linux-amd64.tar.gz +echo 'a035d9beda8341b645d3f45a1b620cf2d8fb0c5eb409be36b389c0fd384ecc3a go1.10.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.10.5.linux-amd64.tar.gz +sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ +rm go1.10.5.linux-amd64.tar.gz +``` + +### 6. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all --prune +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +sudo -u git -H git checkout -- locale +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout BRANCH +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout BRANCH-ee +``` + +### 7. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 8. Update gitlab-workhorse + +Install and compile gitlab-workhorse. GitLab-Workhorse uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 9. Update Gitaly + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +### 10. Update gitlab-pages + +#### Only needed if you use GitLab Pages + +Install and compile gitlab-pages. GitLab-Pages uses +[GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-pages + +sudo -u git -H git fetch --all --tags --prune +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) +sudo -u git -H make +``` + +### 11. Update MySQL permissions + +If you are using MySQL you need to grant the GitLab user the necessary +permissions on the database: + +```bash +mysql -u root -p -e "GRANT TRIGGER ON \`gitlabhq_production\`.* TO 'git'@'localhost';" +``` + +If you use MySQL with replication, or just have MySQL configured with binary logging, +you will need to also run the following on all of your MySQL servers: + +```bash +mysql -u root -p -e "SET GLOBAL log_bin_trust_function_creators = 1;" +``` + +You can make this setting permanent by adding it to your `my.cnf`: + +``` +log_bin_trust_function_creators=1 +``` + +### 12. Update configuration files + +#### New configuration options for `gitlab.yml` + +There might be configuration options available for [`gitlab.yml`][yaml]. View +them with the command below and apply them manually to your current +`gitlab.yml`: + +```sh +cd /home/git/gitlab + +git diff origin/PREVIOUS_BRANCH:config/gitlab.yml.example origin/BRANCH:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab-ssl origin/BRANCH:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/PREVIOUS_BRANCH:lib/support/nginx/gitlab origin/BRANCH:lib/support/nginx/gitlab +``` + +If you are using Strict-Transport-Security in your installation to continue +using it you must enable it in your Nginx configuration as GitLab application no +longer handles setting it. + +If you are using Apache instead of NGINX please see the updated [Apache templates]. +Also note that because Apache does not support upstreams behind Unix sockets you +will need to let gitlab-workhorse listen on a TCP port. You can do this +via [/etc/default/gitlab]. + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to +add the following line to `config/initializers/smtp_settings.rb`: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +#### Init script + +There might be new configuration options available for +[`gitlab.default.example`][gl-example]. View them with the command below and +apply them manually to your current `/etc/default/gitlab`: + +```sh +cd /home/git/gitlab + +git diff origin/PREVIOUS_BRANCH:lib/support/init.d/gitlab.default.example origin/BRANCH:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 13. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --deployment --without development test mysql aws kerberos + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --deployment --without development test postgres aws kerberos + + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Compile GetText PO files + +sudo -u git -H bundle exec rake gettext:compile RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and +data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 14. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 15. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Version specific upgrading instructions + +This section contains upgrading instructions for specific versions. When +present, first follow the upgrading guidelines for all versions. If the version +you are upgrading to is not listed here, then no additional steps are required. + +<!-- +Example: + +### 11.8.0 + +Additional instructions here. +--> + +## Things went south? Revert to previous version + +### 1. Revert the code to the previous version + +To revert to a previous version, you'll need to following the upgrading guides +for the previous version. If you upgraded to 11.8 and want to revert back to +11.7, you'll need to follow the guides for upgrading from 11.6 to 11.7. You can +use the version dropdown at the top of the page to select the right version. + +When reverting, you should _not_ follow the database migration guides, as the +backup is already migrated to the previous version. + +### 2. Restore from the backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production +``` + +If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. + +[yaml]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/initializers/smtp_settings.rb.sample#L13 +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/support/init.d/gitlab.default.example#L38 diff --git a/doc/update/upgrading_postgresql_using_slony.md b/doc/update/upgrading_postgresql_using_slony.md index d2e2cf439b5..835166837a8 100644 --- a/doc/update/upgrading_postgresql_using_slony.md +++ b/doc/update/upgrading_postgresql_using_slony.md @@ -270,7 +270,6 @@ sudo -u gitlab-psql /opt/gitlab/embedded/bin/slon_start 1 --conf /var/opt/gitlab If all went well this will produce output such as: - ``` Invoke slon for node 1 - /opt/gitlab/embedded/bin/slon -p /var/run/slony1/slony_replication_node1.pid -s 1000 -d2 slony_replication 'host=192.168.0.7 dbname=gitlabhq_production user=slony port=5432 password=hieng8ezohHuCeiqu0leeghai4aeyahp' > /var/log/gitlab/slony/node1/gitlabhq_production-2016-10-06.log 2>&1 & Slon successfully started for cluster slony_replication, node node1 diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md index 1f4f598b121..41ee7e62b2c 100644 --- a/doc/user/abuse_reports.md +++ b/doc/user/abuse_reports.md @@ -25,7 +25,6 @@ To report abuse from a user's comment: 1. Complete an abuse report. 1. Click the **Send report** button. - NOTE: **Note:** A URL to the reported user's comment will be pre-filled in the abuse report's **Message** field. diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 43b1190fb48..c22982ac190 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -28,7 +28,6 @@ With default whitelist settings, the probes can be accessed from localhost: - `http://localhost/-/readiness` - `http://localhost/-/liveness` - The first endpoint, `/-/health/`, only checks whether the application server is running. It does -not verify the database or other services are running. A successful response will return a 200 status code with the following message: diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index d4853a5842e..12aa6f27444 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -20,7 +20,7 @@ From now on, every existing project and newly created ones that don't have a `.gitlab-ci.yml`, will use the Auto DevOps pipelines. If you want to disable it for a specific project, you can do so in -[its settings](../../../topics/autodevops/index.md#enabling-auto-devops). +[its settings](../../../topics/autodevops/index.md##enablingdisabling-auto-devops). ## Maximum artifacts size **[CORE ONLY]** diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 93767aefb51..8358fe64f18 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -14,6 +14,10 @@ include: - [Usage statistics](usage_statistics.md) - [Visibility and access controls](visibility_and_access_controls.md) +NOTE: **Note:** +You can change the [first day of the week](../../profile/preferences.md) for the entire GitLab instance +in the **Localization** section of **Admin area > Settings > Preferences**. + ## GitLab.com admin area settings Most of the settings under the admin area change the behavior of the whole diff --git a/doc/user/admin_area/settings/third_party_offers.md b/doc/user/admin_area/settings/third_party_offers.md index 177251b52b9..23311801790 100644 --- a/doc/user/admin_area/settings/third_party_offers.md +++ b/doc/user/admin_area/settings/third_party_offers.md @@ -3,4 +3,7 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20379) > in [GitLab Core](https://about.gitlab.com/pricing/) 11.1 -The display of third party offers can be controlled in the Admin Area -> Settings page. +Within GitLab, we inform users of available third-party offers they might find valuable in order to enhance the development of their projects. +An example is the Google Cloud Platform free credit for using [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine/). + +The display of third-party offers can be toggled in the Admin area on the Settings page. diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index 84f4b0b3922..d202b1260ad 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -253,8 +253,9 @@ to newer issues or merge requests. - The people participating in the discussion are trolling, abusive, or otherwise being unproductive. -In these cases, a user with Maintainer permissions or higher in the project can lock (and unlock) -an issue or a merge request, using the "Lock" section in the sidebar: +In these cases, a user with Developer permissions or higher in the project can lock (and unlock) +an issue or a merge request, using the "Lock" section in the sidebar. For issues, +a user with Reporter permissions can lock (and unlock). | Unlock | Lock | | :-----------: | :----------: | diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 9fc50741407..8d223d1c5f0 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -95,7 +95,6 @@ For example, let's say we have the following Kubernetes clusters: | Test | `test` | Group | | Development| `*` | Group | - And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md): ```yaml diff --git a/doc/user/index.md b/doc/user/index.md index 36aba5e01c6..22506b30498 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -65,7 +65,9 @@ and [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board. - View the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) - Leverage continuous delivery method with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) -You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more. +You can also [integrate](project/integrations/project_services.md) GitLab with +numerous third-party applications, such as Mattermost, Microsoft Teams, Trello, +Slack, Bamboo CI, JIRA, and a lot more. ## Projects diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 9a01625f3ff..a7a87773eec 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -288,7 +288,6 @@ On Linux, you can download [Noto Color Emoji](https://www.google.com/get/noto/he Ubuntu 18.04 (like many modern Linux distros) has this font installed by default. ``` - Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/monkey.png" width="20px" height="20px"> around a bit and add some <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/star2.png" width="20px" height="20px"> to your <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/speech_balloon.png" width="20px" height="20px">. Well we have a gift for you: <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/zap.png" width="20px" height="20px">You can use emoji anywhere GFM is supported. <img src="https://gitlab.com/gitlab-org/gitlab-ce/raw/master/app/assets/images/emoji/v.png" width="20px" height="20px"> @@ -453,14 +452,14 @@ Color written inside backticks will be followed by a color "chip". Examples: - `#F00` - `#F00A` - `#FF0000` - `#FF0000AA` - `RGB(0,255,0)` - `RGB(0%,100%,0%)` - `RGBA(0,255,0,0.7)` - `HSL(540,70%,50%)` + `#F00` + `#F00A` + `#FF0000` + `#FF0000AA` + `RGB(0,255,0)` + `RGB(0%,100%,0%)` + `RGBA(0,255,0,0.7)` + `HSL(540,70%,50%)` `HSLA(540,70%,50%,0.7)` Becomes: @@ -987,7 +986,6 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>. The formula for water is H<sub>2</sub>O while the equation for the theory of relativity is E = mc<sup>2</sup>. - ## Wiki-specific Markdown The following examples show how links inside wikis behave. diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 4976284aea4..74a966f3a17 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -61,6 +61,7 @@ The following table depicts the various user permission levels in a project. | Manage related issues **[STARTER]** | | ✓ | ✓ | ✓ | ✓ | | Lock issue discussions | | ✓ | ✓ | ✓ | ✓ | | Create issue from vulnerability **[ULTIMATE]** | | ✓ | ✓ | ✓ | ✓ | +| View Error Tracking list | | ✓ | ✓ | ✓ | ✓ | | Lock merge request discussions | | | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | | Stop environments | | | ✓ | ✓ | ✓ | @@ -101,6 +102,7 @@ The following table depicts the various user permission levels in a project. | Manage clusters | | | | ✓ | ✓ | | Manage license policy **[ULTIMATE]** | | | | ✓ | ✓ | | Edit comments (posted by any user) | | | | ✓ | ✓ | +| Manage Error Tracking | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Remove project | | | | | ✓ | diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 83bc79925e1..0a7c5832a2d 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -18,7 +18,7 @@ the second factor of authentication. Once enabled, in addition to supplying your password to login, you'll be prompted to activate your U2F device (usually by pressing a button on it), and it will perform secure authentication on your behalf. -The U2F workflow is only supported by Google Chrome at this point, so we _strongly_ recommend +The U2F workflow is only [supported by](https://caniuse.com/#search=U2F) Google Chrome, Opera and Firefox at this point, so we _strongly_ recommend that you set up both methods of two-factor authentication, so you can still access your account from other browsers. diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index efb031b8239..ba756c4b793 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -89,7 +89,6 @@ To enable private profile: 1. Check the "Private profile" option. 1. Hit **Update profile settings**. - NOTE: **Note:** You and GitLab admins can see your the abovementioned information on your profile even if it is private. diff --git a/doc/user/profile/preferences.md b/doc/user/profile/preferences.md index 363d3db8db1..7387d1810ca 100644 --- a/doc/user/profile/preferences.md +++ b/doc/user/profile/preferences.md @@ -57,7 +57,10 @@ and default views of your dashboard and the projects' landing pages. ### Layout width GitLab can be set up to use different widths depending on your liking. Choose -between the fixed (max. 1200px) and the fluid (100%) application layout. +between the fixed (max. `1280px`) and the fluid (`100%`) application layout. + +NOTE: **Note:** +While `1280px` is the standard max width when using fixed layout, some pages still use 100% width, depending on the content. ### Default dashboard diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index 0e6d4bce153..ea09f9f1547 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -253,7 +253,7 @@ With RBAC disabled and services deployed, [Auto DevOps](../../../../topics/autodevops/index.md) can now be leveraged to build, test, and deploy the app. -[Enable Auto DevOps](../../../../topics/autodevops/index.md##enablingdisabling-auto-devops-at-the-project-level) +[Enable Auto DevOps](../../../../topics/autodevops/index.md#enablingdisabling-auto-devops-at-the-project-level) if not already enabled. If a wildcard DNS entry was created resolving to the Load Balancer, enter it in the `domain` field under the Auto DevOps settings. Otherwise, the deployed app will not be externally available outside of the cluster. diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index aa1e165e3a2..fc3a4a757d0 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -138,7 +138,6 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ FUNCTION: echo ``` - The `serverless.yml` file references both an `echo` directory (under `buildargs`) and an `echo` file (under `handler`), which is a reference to `echo.js` in the [repository](https://gitlab.com/knative-examples/functions). Additionally, it contains three sections with distinct parameters: @@ -150,7 +149,6 @@ contains three sections with distinct parameters: | `service` | Name for the Knative service which will serve the function. | | `description` | A short description of the `service`. | - ### `provider` | Parameter | Description | diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 638b73bfcb6..dec6eac2508 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -47,7 +47,6 @@ to enable it. > - To move or rename a repository with a container registry you will have to > delete all existing images. - If you visit the **Registry** link under your project's menu, you can see the explicit instructions to login to the Container Registry using your GitLab credentials. diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index b98221bea61..529a82ded9e 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -46,7 +46,7 @@ You can see that there are seven stages in total: ## How the data is measured Cycle Analytics records cycle time and data based on the project issues with the -exception of the staging and production stages, where only data deployed to +exception of the staging and production stages, where only data deployed to production are measured. Specifically, if your CI is not set up and you have not defined a `production` @@ -86,7 +86,6 @@ So, the Cycle Analytics dashboard won't present any data: - For staging and production stages, if the project has no `production` or `production/*` environment. - ## Example workflow Below is a simple fictional workflow of a single cycle that happens in a @@ -159,7 +158,6 @@ Learn more about Cycle Analytics in the following resources: - [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/) - [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/) - [board]: issue_board.md#creating-a-new-list [ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986 [ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975 diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index 7c94f4ef4d8..08647caaf07 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -93,4 +93,3 @@ Possible fixes [ce-4981]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4981 [gitlab-ce-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab - diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index 48aabd02438..3206a39dc08 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -59,4 +59,3 @@ Bamboo under 'Trigger IP addresses'. > **Note:** > - Starting with GitLab 8.14.0, builds are triggered on push events. - diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md deleted file mode 100644 index 0fd847d415f..00000000000 --- a/doc/user/project/integrations/hipchat.md +++ /dev/null @@ -1,53 +0,0 @@ -# Atlassian HipChat - -GitLab provides a way to send HipChat notifications upon a number of events, -such as when a user pushes code, creates a branch or tag, adds a comment, and -creates a merge request. - -## Setup - -GitLab requires the use of a HipChat v2 API token to work. v1 tokens are -not supported at this time. Note the differences between v1 and v2 tokens: - -HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 -token is allowed to send messages to *any* room. - -HipChat v2 API has tokens that are can be created using the Integrations tab -in the Group or Room admin page. By design, these are lightweight tokens that -allow GitLab to send messages only to *one* room. - -### Complete these steps in HipChat - -1. Go to: <https://admin.hipchat.com/admin> -1. Click on "Group Admin" -> "Integrations". -1. Find "Build Your Own!" and click "Create". -1. Select the desired room, name the integration "GitLab", and click "Create". -1. In the "Send messages to this room by posting this URL" column, you should -see a URL in the format: - -``` -https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> -``` - -HipChat is now ready to accept messages from GitLab. Next, set up the HipChat -service in GitLab. - -### Complete these steps in GitLab - -1. Navigate to the project you want to configure for notifications. -1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) -1. Click "HipChat". -1. Select the "Active" checkbox. -1. Insert the `token` field from the URL into the `Token` field on the Web page. -1. Insert the `room` field from the URL into the `Room` field on the Web page. -1. Save or optionally click "Test Settings". - -## Troubleshooting - -If you do not see notifications, make sure you are using a HipChat v2 API -token, not a v1 token. - -Note that the v2 token is tied to a specific room. If you want to be able to -specify arbitrary rooms, you can create an API token for a specific user in -HipChat under "Account settings" and "API access". Use the `XXX` value under -`auth_token=XXX`. diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index be45ce46dfd..cec9018b67f 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -36,7 +36,6 @@ Click on the service links to see further configuration instructions and details | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | | Flowdock | Flowdock is a collaboration web app for technical teams | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | -| [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | | [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index a4698fd172a..ed289b0c4eb 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -89,7 +89,7 @@ to integrate with. Once configured, GitLab will attempt to retrieve performance metrics for any environment which has had a successful deployment. -GitLab will automatically scan the Prometheus server for metrics from known serves like Kubernetes and NGINX, and attempt to identify individual environment. The supported metrics and scan process is detailed in our [Prometheus Metrics Library documentation](prometheus_library/index.md). +GitLab will automatically scan the Prometheus server for metrics from known servers like Kubernetes and NGINX, and attempt to identify individual environment. The supported metrics and scan process is detailed in our [Prometheus Metrics Library documentation](prometheus_library/index.md). You can view the performance dashboard for an environment by [clicking on the monitoring button](../../../ci/environments.md#monitoring-environments). diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index 4d1d95da6f0..cbf08a4f30a 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -22,12 +22,37 @@ a new issue is created. You can configure webhooks to listen for specific events like pushes, issues or merge requests. GitLab will send a POST request with data to the webhook URL. +In most cases, you'll need to set up your own [webhook receiver](#example-webhook-receiver) +to receive information from GitLab, and send it to another app, according to your needs. +We already have a [built-in receiver](http://docs.gitlab.com/ce/project_services/slack.html) +for sending [Slack](https://api.slack.com/incoming-webhooks) notifications _per project_. + +## Overview + +[Webhooks](https://en.wikipedia.org/wiki/Webhook) are "_user-defined HTTP +callbacks_". They are usually triggered by some +event, such as pushing code to a repository or a comment being posted to a blog. +When that event occurs, the source app makes an HTTP request to the URI +configured for the webhook. The action taken may be anything. +Common uses are to trigger builds with continuous integration systems or to +notify bug tracking systems. + Webhooks can be used to update an external issue tracker, trigger CI jobs, update a backup mirror, or even deploy to your production server. +They are available **per project** for GitLab Community Edition, +and **per project and per group** for **GitLab Enterprise Edition**. Navigate to the webhooks page by going to your project's **Settings ➔ Integrations**. +## Use-cases + +- You can set up a webhook in GitLab to send a notification to +[Slack](https://api.slack.com/incoming-webhooks) every time a build fails, for example +- You can [integrate with Twilio to be notified via SMS](https://www.datadoghq.com/blog/send-alerts-sms-customizable-webhooks-twilio/) +every time an issue is created for a specific project or group within GitLab +- You can use them to [automatically assign labels to merge requests](https://about.gitlab.com/2016/08/19/applying-gitlab-labels-automatically/). + ## Webhook endpoint tips If you are writing your own endpoint (web server) that will receive @@ -1203,6 +1228,15 @@ by uncommenting or adding the following setting to your `/etc/gitlab/gitlab.rb`: gitlab_rails['webhook_timeout'] = 10 ``` +### Troubleshooting: "Unable to get local issuer certificate" + +When SSL verification is enabled, this error indicates that GitLab isn't able to verify the SSL certificate of the webhook endpoint. +Typically, this is because the root certificate isn't issued by a trusted certification authority as +determined by [CAcert.org](http://www.cacert.org/). + +Should that not be the case, consider using [SSL Checker](https://www.sslshopper.com/ssl-checker.html) to identify faults. +Missing intermediate certificates are a common point of verification failure. + ## Example webhook receiver If you want to see GitLab's webhooks in action for testing purposes you can use diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md index d78721f8658..e4a3ff52e07 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issues_functionalities.md @@ -4,7 +4,7 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview o ## Issues Functionalities -The image bellow illustrates how an issue looks like: +The image below illustrates what an issue looks like:  @@ -13,7 +13,7 @@ You can find all the information on that issue on one screen. ### Issue screen An issue starts with its status (open or closed), followed by its author, -and includes many other functionalities, numbered on the image above to +and includes many other functionalities, numbered in the image above to explain what they mean, one by one. Many of the elements of the issue screen refresh automatically, such as the title and description, when they are changed by another user. @@ -27,7 +27,7 @@ Comments and system notes also appear automatically in response to various actio #### 2. Todos -- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.html) list +- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.md) list - Mark todo as done: mark that issue as done (reflects on the Todo list) #### 3. Assignee @@ -43,14 +43,14 @@ assigned to them if they created the issue themselves. ##### 3.1. Multiple Assignees **[STARTER]** -Often multiple people likely work on the same issue together, -which can especially be difficult to track in large teams +Often multiple people work on the same issue together, +which can be especially difficult to track in large teams where there is shared ownership of an issue. -In [GitLab Starter](https://about.gitlab.com/pricing/), you can also -select multiple assignees to an issue. +In [GitLab Starter](https://about.gitlab.com/pricing/), you can +assign multiple people to an issue. -Learn more on the [Multiple Assignees documentation](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html). +Learn more in the [Multiple Assignees documentation](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html). #### 4. Milestone @@ -58,40 +58,39 @@ Learn more on the [Multiple Assignees documentation](https://docs.gitlab.com/ee/ #### 5. Time Tracking -- Estimate time: add an estimate time in which the issue will be implemented -- Spend: add the time spent on the implementation of that issue +- Estimate time: add an estimate of the time it will take to resolve the issue. +- Spend: add the time spent on the resolution of the issue > **Note:** Both estimate and spend times are set via [GitLab Quick Actions](../quick_actions.md). -Learn more on the [Time Tracking documentation](../../../workflow/time_tracking.md). +Learn more in the [Time Tracking documentation](../../../workflow/time_tracking.md). #### 6. Due date -When you work on a tight schedule, and it's important to -have a way to set up a deadline for implementations and for solving -problems. This can be facilitated by the [due date](due_dates.md)). Due dates +When you work on a tight schedule, it's important to +have a way to set a deadline for implementations and for solving +problems. This can be done in the [due date](due_dates.md) element. Due dates can be changed as many times as needed. #### 7. Labels Categorize issues by giving them [labels](../labels.md). They help to -organize team's workflows, once they enable you to work with the -[GitLab Issue Board](index.md#gitlab-issue-board). +organize workflows, and they enable you to work with the +[GitLab Issue Board](index.md#issue-board). -Group Labels, which allow you to use the same labels per +Group Labels, which allow you to use the same labels for a group of projects, can be also given to issues. They work exactly the same, but they are immediately available to all projects in the group. > **Tip:** -if the label doesn't exist yet, when you click **Edit**, it opens a dropdown menu from which you can select **Create new label**. +If a label doesn't exist yet, you can click **Edit**, and it opens a dropdown menu from which you can select **Create new label**. #### 8. Weight **[STARTER]** -- Attribute a weight (in a 0 to 9 range) to that issue. Easy to complete -should weight 1 and very hard to complete should weight 9. +- Assign a weight. Larger values are used to indicate more effort is required to complete the issue. Only positive values or zero are allowed. -Learn more on the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html). +Learn more in the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html). #### 9. Participants @@ -102,32 +101,33 @@ Learn more on the [Issue Weight documentation](https://docs.gitlab.com/ee/workfl - Subscribe: if you are not a participant of the discussion on that issue, but want to receive notifications on each new input, subscribe to it. - Unsubscribe: if you are receiving notifications on that issue but no -longer want to receive them, unsubscribe to it. +longer want to receive them, unsubscribe from it. -Read more on the [notifications documentation](../../../workflow/notifications.md#issue-merge-request-events). +Read more in the [notifications documentation](../../../workflow/notifications.md#issue--merge-request-events). #### 11. Reference -- A quick "copy to clipboard" button to that issue's reference, `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` +- A quick "copy to clipboard" button for that issue's reference, `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` is the `project-name`, and `xxx` is the issue number. #### 12. Title and description -- Title: a plain text title describing the issue's subject. -- Description: a text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). +- Title: a plain text title for describing the subject of the issue. +- Description: a large text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm), + to describe all the details of the issue. -#### 13. @mentions +#### 13. Mentions -- You can either `@mention` a user or a group present in your - GitLab instance and they will be notified via todos and email, unless that - person has disabled all notifications in their profile settings. -- Mentions for yourself (the current logged in user),will be distinctly highlighted +- You can mention a user or a group present in your GitLab instance with + `@username` or `@groupname` and they will be notified via todos and email, unless + they have disabled all notifications in their profile settings. +- Mentions for yourself (the current logged in user), will be highlighted in a different color, allowing you to easily see which comments involve you, helping you focus on them quickly. -To change your [notification settings](../../../workflow/notifications.md) navigate to +To change your [notification settings](../../../workflow/notifications.md), navigate to **Profile Settings** > **Notifications** > **Global notification level** -and choose your preferences from the dropdown menu. +and choose your preference from the dropdown menu. > **Tip:** Avoid mentioning `@all` in issues and merge requests, @@ -138,14 +138,14 @@ interpreted as spam. #### 14. Related Merge Requests - Any merge requests mentioned in that issue's description -or in the issue thread. +or in the issue discussion thread. #### 15. Award emoji - Award an emoji to that issue. > **Tip:** -Posting "+1" as comments in threads spam all +Posting "+1" as a comment in a thread spams all subscribed participants of that issue. Awarding an emoji is a way to let them know you like it without spamming them. @@ -157,7 +157,7 @@ These text fields also fully support #### 17. Comment, start a discussion, or comment and close -Once you wrote your comment, you can either: +Once you write a comment, you can either: - Click "Comment" and your comment will be published. - Click "Start discussion": start a thread within that issue's thread to discuss specific points. @@ -167,6 +167,6 @@ Once you wrote your comment, you can either: - Create a new merge request (with a new source branch named after the issue) in one action. The merge request will automatically inherit the milestone and labels of the issue. The merge -request will automatically close that issue as soon as merged. +request will automatically close that issue when it is merged. - Optionally, you can just create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) named after that issue. diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index ac58a0b5c18..e6033ca8655 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -28,8 +28,9 @@ the milestone to the issue. ## Project milestones and group milestones -- **Project milestones** can be assigned to issues or merge requests in that project only. -- **Group milestones** can be assigned to any issue or merge request of any project in that group. +- **Project milestones** can be assigned to issues or merge requests in that project only. Navigate to **Issues > Milestones** in a project to view the project milestone list. +- **Group milestones** can be assigned to any issue or merge request of any project in that group. Navigate to **Issues > Milestones** in a group to view the group milestone list. +- All milestones you have access to can also be viewed in the dashboard milestones list. Click on **Milestones** on the top navigation bar to view both project milestones and group milestones you have access to. ## Creating milestones diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index fe4b36062f7..90bb92d2062 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -14,10 +14,14 @@ You may sign up to the cloud hosted <https://sentry.io> or deploy your own [on-p ### Enabling Sentry +NOTE: **Note:** +You will need at least Maintainer [permissions](../../permissions.md) to enable the Sentry integration. + GitLab provides an easy way to connect Sentry to your project: 1. Sign up to Sentry.io or [deploy your own](#deploying-sentry) Sentry instance. 1. [Find or generate](https://docs.sentry.io/api/auth/) a Sentry auth token for your Sentry project. +Make sure to give the token at least the following scopes: `event:read` and `project:read`. 1. Navigate to your project’s **Settings > Operations** and provide the Sentry API URL and auth token. 1. Ensure that the 'Active' checkbox is set. 1. Click **Save changes** for the changes to take effect. @@ -25,6 +29,9 @@ GitLab provides an easy way to connect Sentry to your project: ## Error Tracking List +NOTE: **Note:** +You will need at least Reporter [permissions](../../permissions.md) to view the Error Tracking list. + The Error Tracking list may be found at **Operations > Error Tracking** in your project's sidebar.  diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 11f6165fcb4..2de3fb7e080 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -66,7 +66,7 @@ publish any website written directly in plain HTML, CSS, and JavaScript.</p> If you're using GitLab.com, your website will be publicly available to the internet. If you're using self-managed instances (Core, Starter, Premium, or Ultimate), your websites will be published on your own server, according to the -[Pages admin settings](../../../administration/pages/index.md) chosen by your sysdamin, +[Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, who can opt for making them public or internal to your server. ### How it works diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index cebff38ba88..fa65a206273 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -348,8 +348,8 @@ This can be achieved by including a `script:` command like this in your pages: # Other directives script: - - # build the public/ directory first - - find public -type f -iregex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -execdir gzip -f --keep {} \; + # Build the public/ directory first + - find public -type f -regex '.*\.\(htm\|html\|txt\|text\|js\|css\)$' -exec gzip -f -k {} \; ``` By pre-compressing the files and including both versions in the artifact, Pages diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 0d0575b1ab4..4ab66063dcf 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -191,5 +191,9 @@ artifacts and the job's trace. 1. Click the trash icon at the top right of the job's trace. 1. Confirm the deletion. +## Retrieve artifacts of private projects when using GitLab CI + +In order to retrieve a job artifact of a different project, you might need to use a private token in order to [authenticate and download](../../../api/jobs.md#get-job-artifacts) the artifacts. + [expiry date]: ../../../ci/yaml/README.md#artifacts-expire_in -[ce-14399]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399 +[ce-14399]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14399
\ No newline at end of file diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md index ec8b8444d99..58a0fbc97cd 100644 --- a/doc/user/project/pipelines/schedules.md +++ b/doc/user/project/pipelines/schedules.md @@ -1,4 +1,4 @@ -# Pipeline Schedules +# Pipeline schedules > **Notes**: > - This feature was introduced in 9.1 as [Trigger Schedule][ce-10533]. diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index bb9b4238ee9..cce330aecc7 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -23,6 +23,7 @@ in `.gitlab-ci.yml`. ## Timeout Timeout defines the maximum amount of time in minutes that a job is able run. +This is configureable under your project's **Settings > CI/CD > General pipelines settings**. The default value is 60 minutes. Decrease the time limit if you want to impose a hard limit on your jobs' running time or increase it otherwise. In any case, if the job surpasses the threshold, it is marked as failed. diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md index 3d8fff9f733..26bec323f02 100644 --- a/doc/user/project/protected_tags.md +++ b/doc/user/project/protected_tags.md @@ -10,7 +10,6 @@ This feature evolved out of [Protected Branches](protected_branches.md) Protected tags will prevent anyone from updating or deleting the tag, as and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Maintainer permission will be prevented from creating tags. - ## Configuring protected tags To protect a tag, you need to have at least Maintainer permission level. @@ -43,7 +42,6 @@ matching the wildcard. For example: | `*gitlab*` | `gitlab`, `gitlab/v1` | | `*` | `v1.0.1rc2`, `accidental-tag` | - Two different wildcards can potentially match the same tag. For example, `*-stable` and `production-*` would both match a `production-stable` tag. In that case, if _any_ of these protected tags have a setting like @@ -54,7 +52,6 @@ all matching tags:  - --- [ce-10356]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10356 "Protected Tags" diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 85a03d125dd..392e72dcc5c 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -55,7 +55,6 @@ discussions, and descriptions: | `/merge` | Merge (when pipeline succeeds) | | âś“ | | `/create_merge_request <branch name>` | Create a new merge request starting from the current issue | âś“ | | - ## Quick actions for commit messages The following quick actions are applicable for commit messages: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index c7e20f01a75..6495ede42e0 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -190,7 +190,6 @@ key to use. Replace `30F2B65B9246B6CA` with your GPG key ID. - 1. (Optional) If Git is using `gpg` and you get errors like `secret key not available` or `gpg: signing failed: secret key not available`, run the following command to change to `gpg2`: @@ -266,3 +265,7 @@ To remove a GPG key from your account: You can configure your project to reject commits that aren't GPG-signed via [push rules](https://docs.gitlab.com/ee/push_rules/push_rules.html). + +## GPG signing API + +Learn how to [get the GPG signature from a commit via API](../../../../api/commits.md#get-gpg-signature-of-a-commit). diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 035028c9266..ce9d23bf911 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -33,13 +33,13 @@ easy for you.  -When clicking on either `LICENSE` or `.gitignore`, a dropdown will be displayed +When clicking on either `LICENSE` or `.gitignore`, etc., a dropdown will be displayed to provide you with a template which might be suitable for your project.  The license, changelog, contribution guide, or `.gitlab-ci.yml` file could also -be added through a button on the project page. In the example below the license +be added through a button on the project page. In the example below, the license has already been created, which creates a link to the license itself.  @@ -112,7 +112,6 @@ screenshot above will yield a branch named Since GitLab 9.0, when you click the `New branch` in an empty repository project, GitLab automatically creates the master branch, commits a blank `README.md` file to it and creates and redirects you to a new branch based on the issue title. If your [project is already configured with a deployment service][project-services-doc] (e.g. Kubernetes), GitLab takes one step further and prompts you to set up [auto deploy][auto-deploy-doc] by helping you create a `.gitlab-ci.yml` file. - After the branch is created, you can edit files in the repository to fix the issue. When a merge request is created based on the newly created branch, the description field will automatically display the [issue closing pattern] diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index b09a3f927d1..d5f4a7fd4ac 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -121,7 +121,7 @@ NOTE: **Note:** GitLab administrators can use the admin interface to move any project to any namespace if needed. -[permissions]: ../../permissions.md##project-members-permissions +[permissions]: ../../permissions.md#project-members-permissions ## Operations settings diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index 55e53b865af..3e85e97d7a5 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -3,8 +3,8 @@ > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4539) in [GitLab Ultimate][ee] 10.4. > [Brought to GitLab Core](https://gitlab.com/gitlab-org/gitlab-ce/issues/44157) in 10.7. -The Web IDE makes it faster and easier to contribute changes to your projects -by providing an advanced editor with commit staging. +The Web IDE editor makes it faster and easier to contribute changes to your +projects by providing an advanced editor with commit staging. ## Open the Web IDE @@ -22,7 +22,7 @@ searching. The file finder is launched using the keyboard shortcut `Command-p`, `Control-p`, or `t` (when editor is not in focus). Type the filename or file path fragments to start seeing results. -## Syntax highligting +## Syntax highlighting As expected from an IDE, syntax highlighting for many languages within the Web IDE will make your direct editing even easier. @@ -47,10 +47,10 @@ Single file editing is based on the [Ace Editor](https://ace.c9.io). After making your changes, click the Commit button in the bottom left to review the list of changed files. Click on each file to review the changes and -click the tick icon to stage the file. +click the tick icon to stage the file. Once you have staged some changes, you can add a commit message and commit the -staged changes. Unstaged changes will not be commited. +staged changes. Unstaged changes will not be committed.  @@ -80,7 +80,7 @@ left. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/19318) in [GitLab Core][ce] 11.0. Switching between your authored and assigned merge requests can be done without -leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list +leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list of merge requests. You will need to commit or discard all your changes before switching to a different merge request. @@ -89,7 +89,7 @@ switching to a different merge request. > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/20850) in [GitLab Core][ce] 11.2. Switching between branches of the current project repository can be done without -leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list +leaving the Web IDE. Click the dropdown in the top of the sidebar to open a list of branches. You will need to commit or discard all your changes before switching to a different branch. diff --git a/doc/user/reserved_names.md b/doc/user/reserved_names.md index 45c306f5988..a14df6c8402 100644 --- a/doc/user/reserved_names.md +++ b/doc/user/reserved_names.md @@ -61,8 +61,6 @@ Currently the following names are reserved as top level groups: - favicon.ico - favicon.png - groups -- header_logo_dark.png -- header_logo_light.png - health_check - help - import diff --git a/doc/workflow/forking_workflow.md b/doc/workflow/forking_workflow.md index 733d079bd4a..02be0ad191d 100644 --- a/doc/workflow/forking_workflow.md +++ b/doc/workflow/forking_workflow.md @@ -10,7 +10,6 @@ document more information about using branches to work together. Forking a project is in most cases a two-step process. - 1. Click on the fork button located in the middle of the page or a project's home page right next to the stars button. diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md index a7313082fac..1b9fb504b15 100644 --- a/doc/workflow/gitlab_flow.md +++ b/doc/workflow/gitlab_flow.md @@ -2,314 +2,324 @@ # Introduction to GitLab Flow -Version management with git makes branching and merging much easier than older versioning systems such as SVN. -This allows a wide variety of branching strategies and workflows. -Almost all of these are an improvement over the methods used before git. -But many organizations end up with a workflow that is not clearly defined, overly complex or not integrated with issue tracking systems. -Therefore we propose the GitLab flow as clearly defined set of best practices. -It combines [feature driven development](https://en.wikipedia.org/wiki/Feature-driven_development) and [feature branches](http://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. +Git allows a wide variety of branching strategies and workflows. +Because of this, many organizations end up with workflows that are too complicated, not clearly defined, or not integrated with issue tracking systems. +Therefore, we propose GitLab flow as a clearly defined set of best practices. +It combines [feature-driven development](https://en.wikipedia.org/wiki/Feature-driven_development) and [feature branches](https://martinfowler.com/bliki/FeatureBranch.html) with issue tracking. -Organizations coming to git from other version control systems frequently find it hard to develop an effective workflow. -This article describes the GitLab flow that integrates the git workflow with an issue tracking system. -It offers a simple, transparent and effective way to work with git. +Organizations coming to Git from other version control systems frequently find it hard to develop a productive workflow. +This article describes GitLab flow, which integrates the Git workflow with an issue tracking system. +It offers a simple, transparent, and effective way to work with Git.  -When converting to git you have to get used to the fact that there are three steps before a commit is shared with colleagues. -Most version control systems have only one step, committing from the working copy to a shared server. -In git you add files from the working copy to the staging area. After that you commit them to the local repo. +When converting to Git, you have to get used to the fact that it takes three steps to share a commit with colleagues. +Most version control systems have only one step: committing from the working copy to a shared server. +In Git, you add files from the working copy to the staging area. After that, you commit them to your local repo. The third step is pushing to a shared remote repository. -After getting used to these three steps the branching model becomes the challenge. +After getting used to these three steps, the next challenge is the branching model. - + -Since many organizations new to git have no conventions how to work with it, it can quickly become a mess. -The biggest problem they run into is that many long running branches that each contain part of the changes are around. -People have a hard time figuring out which branch they should develop on or deploy to production. -Frequently the reaction to this problem is to adopt a standardized pattern such as [git flow](http://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). -We think there is still room for improvement and will detail a set of practices we call GitLab flow. +Since many organizations new to Git have no conventions for how to work with it, their repositories can quickly become messy. +The biggest problem is that many long-running branches emerge that all contain part of the changes. +People have a hard time figuring out which branch has the latest code, or which branch to deploy to production. +Frequently, the reaction to this problem is to adopt a standardized pattern such as [Git flow](https://nvie.com/posts/a-successful-git-branching-model/) and [GitHub flow](http://scottchacon.com/2011/08/31/github-flow.html). +We think there is still room for improvement. In this document, we describe a set of practices we call GitLab flow. ## Git flow and its problems  -Git flow was one of the first proposals to use git branches and it has gotten a lot of attention. -It advocates a master branch and a separate develop branch as well as supporting branches for features, releases and hotfixes. -The development happens on the develop branch, moves to a release branch and is finally merged into the master branch. -Git flow is a well defined standard but its complexity introduces two problems. -The first problem is that developers must use the develop branch and not master, master is reserved for code that is released to production. -It is a convention to call your default branch master and to mostly branch from and merge to this. -Since most tools automatically make the master branch the default one and display that one by default it is annoying to have to switch to another one. -The second problem of git flow is the complexity introduced by the hotfix and release branches. +Git flow was one of the first proposals to use Git branches, and it has received a lot of attention. +It suggests a `master` branch and a separate `develop` branch, as well as supporting branches for features, releases, and hotfixes. +The development happens on the `develop` branch, moves to a release branch, and is finally merged into the `master` branch. + +Git flow is a well-defined standard, but its complexity introduces two problems. +The first problem is that developers must use the `develop` branch and not `master`. `master` is reserved for code that is released to production. +It is a convention to call your default branch `master` and to mostly branch from and merge to this. +Since most tools automatically use the `master` branch as the default, it is annoying to have to switch to another branch. + +The second problem of Git flow is the complexity introduced by the hotfix and release branches. These branches can be a good idea for some organizations but are overkill for the vast majority of them. -Nowadays most organizations practice continuous delivery which means that your default branch can be deployed. -This means that hotfix and release branches can be prevented including all the ceremony they introduce. +Nowadays, most organizations practice continuous delivery, which means that your default branch can be deployed. +Continuous delivery removes the need for hotfix and release branches, including all the ceremony they introduce. An example of this ceremony is the merging back of release branches. Though specialized tools do exist to solve this, they require documentation and add complexity. -Frequently developers make a mistake and for example changes are only merged into master and not into the develop branch. -The root cause of these errors is that git flow is too complex for most of the use cases. -And doing releases doesn't automatically mean also doing hotfixes. +Frequently, developers make mistakes such as merging changes only into `master` and not into the `develop` branch. +The reason for these errors is that Git flow is too complicated for most use cases. +For example, many projects do releases but don't need to do hotfixes. ## GitHub flow as a simpler alternative  -In reaction to git flow a simpler alternative was detailed, [GitHub flow](https://guides.github.com/introduction/flow/index.html). -This flow has only feature branches and a master branch. -This is very simple and clean, many organizations have adopted it with great success. -Atlassian recommends [a similar strategy](http://blogs.atlassian.com/2014/01/simple-git-workflow-simple/) although they rebase feature branches. -Merging everything into the master branch and deploying often means you minimize the amount of code in 'inventory' which is in line with the lean and continuous delivery best practices. -But this flow still leaves a lot of questions unanswered regarding deployments, environments, releases and integrations with issues. -With GitLab flow we offer additional guidance for these questions. +In reaction to Git flow, GitHub created a simpler alternative. +[GitHub flow](https://guides.github.com/introduction/flow/index.html) has only feature branches and a `master` branch. +This flow is clean and straightforward, and many organizations have adopted it with great success. +Atlassian recommends [a similar strategy](https://www.atlassian.com/blog/archives/simple-git-workflow-simple), although they rebase feature branches. +Merging everything into the `master` branch and frequently deploying means you minimize the amount of unreleased code, which is in line with lean and continuous delivery best practices. +However, this flow still leaves a lot of questions unanswered regarding deployments, environments, releases, and integrations with issues. +With GitLab flow, we offer additional guidance for these questions. ## Production branch with GitLab flow - + -GitHub flow does assume you are able to deploy to production every time you merge a feature branch. -This is possible for e.g. SaaS applications, but there are many cases where this is not possible. -One would be a situation where you are not in control of the exact release moment, for example an iOS application that needs to pass App Store validation. -Another example is when you have deployment windows (workdays from 10am to 4pm when the operations team is at full capacity) but you also merge code at other times. -In these cases you can make a production branch that reflects the deployed code. -You can deploy a new version by merging in master to the production branch. -If you need to know what code is in production you can just checkout the production branch to see. +GitHub flow assumes you can deploy to production every time you merge a feature branch. +While this is possible in some cases, such as SaaS applications, there are many cases where this is not possible. +One case is where you don't control the timing of a release, for example, an iOS application that is released when it passes App Store validation. +Another case is when you have deployment windows — for example, workdays from 10 AM to 4 PM when the operations team is at full capacity — but you also merge code at other times. +In these cases, you can make a production branch that reflects the deployed code. +You can deploy a new version by merging `master` into the production branch. +If you need to know what code is in production, you can just checkout the production branch to see. The approximate time of deployment is easily visible as the merge commit in the version control system. This time is pretty accurate if you automatically deploy your production branch. -If you need a more exact time you can have your deployment script create a tag on each deployment. -This flow prevents the overhead of releasing, tagging and merging that is common to git flow. +If you need a more exact time, you can have your deployment script create a tag on each deployment. +This flow prevents the overhead of releasing, tagging, and merging that happens with Git flow. ## Environment branches with GitLab flow  -It might be a good idea to have an environment that is automatically updated to the master branch. -Only in this case, the name of this environment might differ from the branch name. -Suppose you have a staging environment, a pre-production environment and a production environment. -In this case the master branch is deployed on staging. When someone wants to deploy to pre-production they create a merge request from the master branch to the pre-production branch. -And going live with code happens by merging the pre-production branch into the production branch. -This workflow where commits only flow downstream ensures that everything has been tested on all environments. -If you need to cherry-pick a commit with a hotfix it is common to develop it on a feature branch and merge it into master with a merge request, do not delete the feature branch. -If master is good to go (it should be if you are practicing [continuous delivery](http://martinfowler.com/bliki/ContinuousDelivery.html)) you then merge it to the other branches. -If this is not possible because more manual testing is required you can send merge requests from the feature branch to the downstream branches. +It might be a good idea to have an environment that is automatically updated to the `master` branch. +Only, in this case, the name of this environment might differ from the branch name. +Suppose you have a staging environment, a pre-production environment, and a production environment. +In this case, deploy the `master` branch to staging. +To deploy to pre-production, create a merge request from the `master` branch to the pre-production branch. +Go live by merging the pre-production branch into the production branch. +This workflow, where commits only flow downstream, ensures that everything is tested in all environments. +If you need to cherry-pick a commit with a hotfix, it is common to develop it on a feature branch and merge it into `master` with a merge request. +In this case, do not delete the feature branch yet. +If `master` passes automatic testing, you then merge the feature branch into the other branches. +If this is not possible because more manual testing is required, you can send merge requests from the feature branch to the downstream branches. ## Release branches with GitLab flow  -Only in case you need to release software to the outside world you need to work with release branches. -In this case, each branch contains a minor version (2-3-stable, 2-4-stable, etc.). -The stable branch uses master as a starting point and is created as late as possible. -By branching as late as possible you minimize the time you have to apply bug fixes to multiple branches. -After a release branch is announced, only serious bug fixes are included in the release branch. -If possible these bug fixes are first merged into master and then cherry-picked into the release branch. -This way you can't forget to cherry-pick them into master and encounter the same bug on subsequent releases. -This is called an 'upstream first' policy that is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/about/news/archive/2013/5/a-community-for-using-openstack-with-red-hat-rdo). -Every time a bug-fix is included in a release branch the patch version is raised (to comply with [Semantic Versioning](http://semver.org/)) by setting a new tag. +You only need to work with release branches if you need to release software to the outside world. +In this case, each branch contains a minor version, for example, 2-3-stable, 2-4-stable, etc. +Create stable branches using `master` as a starting point, and branch as late as possible. +By doing this, you minimize the length of time during which you have to apply bug fixes to multiple branches. +After announcing a release branch, only add serious bug fixes to the branch. +If possible, first merge these bug fixes into `master`, and then cherry-pick them into the release branch. +If you start by merging into the release branch, you might forget to cherry-pick them into `master`, and then you'd encounter the same bug in subsequent releases. +Merging into `master` and then cherry-picking into release is called an "upstream first" policy, which is also practiced by [Google](https://www.chromium.org/chromium-os/chromiumos-design-docs/upstream-first) and [Red Hat](https://www.redhat.com/en/blog/a-community-for-using-openstack-with-red-hat-rdo). +Every time you include a bug fix in a release branch, increase the patch version (to comply with [Semantic Versioning](https://semver.org/)) by setting a new tag. Some projects also have a stable branch that points to the same commit as the latest released branch. -In this flow it is not common to have a production branch (or git flow master branch). +In this flow, it is not common to have a production branch (or Git flow `master` branch). ## Merge/pull requests with GitLab flow - + -Merge or pull requests are created in a git management application and ask an assigned person to merge two branches. -Tools such as GitHub and Bitbucket choose the name pull request since the first manual action would be to pull the feature branch. -Tools such as GitLab and others choose the name merge request since that is the final action that is requested of the assignee. -In this article we'll refer to them as merge requests. +Merge or pull requests are created in a Git management application. They ask an assigned person to merge two branches. +Tools such as GitHub and Bitbucket choose the name "pull request" since the first manual action is to pull the feature branch. +Tools such as GitLab and others choose the name "merge request" since the final action is to merge the feature branch. +In this article, we'll refer to them as merge requests. -If you work on a feature branch for more than a few hours it is good to share the intermediate result with the rest of the team. -This can be done by creating a merge request without assigning it to anyone, instead you mention people in the description or a comment (/cc @mark @susan). -This means it is not ready to be merged but feedback is welcome. +If you work on a feature branch for more than a few hours, it is good to share the intermediate result with the rest of the team. +To do this, create a merge request without assigning it to anyone. +Instead, mention people in the description or a comment, for example, "/cc @mark @susan." +This indicates that the merge request is not ready to be merged yet, but feedback is welcome. Your team members can comment on the merge request in general or on specific lines with line comments. -The merge requests serves as a code review tool and no separate tools such as Gerrit and reviewboard should be needed. -If the review reveals shortcomings anyone can commit and push a fix. -Commonly the person to do this is the creator of the merge/pull request. -The diff in the merge/pull requests automatically updates when new commits are pushed on the branch. +The merge request serves as a code review tool, and no separate code review tools should be needed. +If the review reveals shortcomings, anyone can commit and push a fix. +Usually, the person to do this is the creator of the merge request. +The diff in the merge request automatically updates when new commits are pushed to the branch. + +When you are ready for your feature branch to be merged, assign the merge request to the person who knows most about the codebase you are changing. +Also, mention any other people from whom you would like feedback. +After the assigned person feels comfortable with the result, they can merge the branch. +If the assigned person does not feel comfortable, they can request more changes or close the merge request without merging. + +In GitLab, it is common to protect the long-lived branches, e.g., the `master` branch, so that [most developers can't modify them](../permissions/permissions.md). +So, if you want to merge into a protected branch, assign your merge request to someone with maintainer permissions. -When you feel comfortable with it to be merged you assign it to the person that knows most about the codebase you are changing and mention any other people you would like feedback from. -There is room for more feedback and after the assigned person feels comfortable with the result the branch is merged. -If the assigned person does not feel comfortable they can close the merge request without merging. +After you merge a feature branch, you should remove it from the source control software. +In GitLab, you can do this when merging. +Removing finished branches ensures that the list of branches shows only work in progress. +It also ensures that if someone reopens the issue, they can use the same branch name without causing problems. -In GitLab it is common to protect the long-lived branches (e.g. the master branch) so that normal developers [can't modify these protected branches](http://docs.gitlab.com/ce/permissions/permissions.html). -So if you want to merge it into a protected branch you assign it to someone with maintainer authorizations. +NOTE: **Note:** +When you reopen an issue you need to create a new merge request. + + ## Issue tracking with GitLab flow - + GitLab flow is a way to make the relation between the code and the issue tracker more transparent. -Any significant change to the code should start with an issue where the goal is described. -Having a reason for every code change is important to inform everyone on the team and to help people keep the scope of a feature branch small. -In GitLab each change to the codebase starts with an issue in the issue tracking system. -If there is no issue yet it should be created first provided there is significant work involved (more than 1 hour). -For many organizations this will be natural since the issue will have to be estimated for the sprint. -Issue titles should describe the desired state of the system, e.g. "As an administrator I want to remove users without receiving an error" instead of "Admin can't remove users.". - -When you are ready to code you start a branch for the issue from the master branch. -The name of this branch should start with the issue number, for example '15-require-a-password-to-change-it'. - -When you are done or want to discuss the code you open a merge request. -This is an online place to discuss the change and review the code. -Opening a merge request is a manual action since you do not always want to merge a new branch you push, it could be a long-running environment or release branch. -If you open the merge request but do not assign it to anyone it is a 'Work In Progress' merge request. -These are used to discuss the proposed implementation but are not ready for inclusion in the master branch yet. -_Pro tip:_ Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready. - -When the author thinks the code is ready the merge request is assigned to reviewer. -The reviewer presses the merge button when they think the code is ready for inclusion in the master branch. -In this case the code is merged and a merge commit is generated that makes this event easily visible later on. -Merge requests always create a merge commit even when the commit could be added without one. -This merge strategy is called 'no fast-forward' in git. -After the merge the feature branch is deleted since it is no longer needed, in GitLab this deletion is an option when merging. +Any significant change to the code should start with an issue that describes the goal. +Having a reason for every code change helps to inform the rest of the team and to keep the scope of a feature branch small. +In GitLab, each change to the codebase starts with an issue in the issue tracking system. +If there is no issue yet, create the issue, as long as the change will take a significant amount of work, i.e., more than 1 hour. +In many organizations, raising an issue is part of the development process because they are used in sprint planning. +The issue title should describe the desired state of the system. +For example, the issue title "As an administrator, I want to remove users without receiving an error" is better than "Admin can't remove users." + +When you are ready to code, create a branch for the issue from the `master` branch. +This branch is the place for any work related to this change. + +NOTE: **Note:** +The name of a branch might be dictated by organizational standards. +For example, in GitLab, any branches in GitLab EE that are equivalent to branches in GitLab CE [must end in `-ee`](https://docs.gitlab.com/ee/development/automatic_ce_ee_merge.html#cherry-picking-from-ce-to-ee). + +When you are done or want to discuss the code, open a merge request. +A merge request is an online place to discuss the change and review the code. + +If you open the merge request but do not assign it to anyone, it is a "Work In Progress" merge request. +These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet. +Start the title of the merge request with "[WIP]" or "WIP:" to prevent it from being merged before it's ready. + +When you think the code is ready, assign the merge request to a reviewer. +The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. +When they press the merge button, GitLab merges the code and creates a merge commit that makes this event easily visible later on. +Merge requests always create a merge commit, even when the branch could be merged without one. +This merge strategy is called "no fast-forward" in Git. +After the merge, delete the feature branch since it is no longer needed. +In GitLab, this deletion is an option when merging. Suppose that a branch is merged but a problem occurs and the issue is reopened. -In this case it is no problem to reuse the same branch name since it was deleted when the branch was merged. -At any time there is at most one branch for every issue. +In this case, it is no problem to reuse the same branch name since the first branch was deleted when it was merged. +At any time, there is at most one branch for every issue. It is possible that one feature branch solves more than one issue. ## Linking and closing issues from merge requests  -Linking to issues can happen by mentioning them in commit messages (fixes #14, closes #67, etc.) or in the merge request description. -GitLab then creates links to the mentioned issues and creates comments in the corresponding issues linking back to the merge request. +Link to issues by mentioning them in commit messages or the description of a merge request, for example, "Fixes #16" or "Duck typing is preferred. See #12." +GitLab then creates links to the mentioned issues and creates comments in the issues linking back to the merge request. -These issues are closed once code is merged into the default branch. +To automatically close linked issues, mention them with the words "fixes" or "closes," for example, "fixes #14" or "closes #67." GitLab closes these issues when the code is merged into the default branch. -If you only want to make the reference without closing the issue you can also just mention it: "Duck typing is preferred. #12". - -If you have an issue that spans across multiple repositories, the best thing is to create an issue for each repository and link all issues to a parent issue. +If you have an issue that spans across multiple repositories, create an issue for each repository and link all issues to a parent issue. ## Squashing commits with rebase  -With git you can use an interactive rebase (`rebase -i`) to squash multiple commits into one and reorder them. -In GitLab EE and .com you can also [rebase before merge](http://docs.gitlab.com/ee/workflow/rebase_before_merge.html) from the web interface. -This functionality is useful if you made a couple of commits for small changes during development and want to replace them with a single commit or if you want to make the order more logical. -However you should never rebase commits you have pushed to a remote server. -Somebody can have referred to the commits or cherry-picked them. -When you rebase you change the identifier (SHA-1) of the commit and this is confusing. -If you do that the same change will be known under multiple identifiers and this can cause much confusion. -If people already reviewed your code it will be hard for them to review only the improvements you made since then if you have rebased everything into one commit. -Another reasons not to rebase is that you lose authorship information, maybe someone created a merge request, another person pushed a commit on there to improve it and a third one merged it. -In this case rebasing all the commits into one prevent the other authors from being properly attributed and sharing part of the [git blame](https://git-scm.com/docs/git-blame). - -People are encouraged to commit often and to frequently push to the remote repository so other people are aware what everyone is working on. -This will lead to many commits per change which makes the history harder to understand. -But the advantages of having stable identifiers outweigh this drawback. -And to understand a change in context one can always look at the merge commit that groups all the commits together when the code is merged into the master branch. - -After you merge multiple commits from a feature branch into the master branch this is harder to undo. -If you had squashed all the commits into one you could have just reverted this commit but as we indicated you should not rebase commits after they are pushed. -Fortunately [reverting a merge made some time ago](https://git-scm.com/blog/2010/03/02/undoing-merges.html) can be done with git. -This however, requires having specific merge commits for the commits your want to revert. -If you revert a merge and you change your mind, revert the revert instead of merging again since git will not allow you to merge the code again otherwise. - -Being able to revert a merge is a good reason always to create a merge commit when you merge manually with the `--no-ff` option. -Git management software will always create a merge commit when you accept a merge request. - -## Do not order commits with rebase +With Git, you can use an interactive rebase (`rebase -i`) to squash multiple commits into one or reorder them. +This functionality is useful if you want to replace a couple of small commits with a single commit, or if you want to make the order more logical. + +However, you should never rebase commits you have pushed to a remote server. +Rebasing creates new commits for all your changes, which can cause confusion because the same change would have multiple identifiers. +It also causes merge errors for anyone working on the same branch because their history would not match with yours. +Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed since the last review. + +You should also never rebase commits authored by other people. +Not only does this rewrite history, but it also loses authorship information. +Rebasing prevents the other authors from being attributed and sharing part of the [`git blame`](https://git-scm.com/docs/git-blame). + +If a merge involves many commits, it may seem more difficult to undo. +You might think to solve this by squashing all the changes into one commit before merging, but as discussed earlier, it is a bad idea to rebase commits that you have already pushed. +Fortunately, there is an easy way to undo a merge with all its commits. +The way to do this is by reverting the merge commit. +Preserving this ability to revert a merge is a good reason to always use the "no fast-forward" (`--no-ff`) strategy when you merge manually. + +NOTE: **Note:** +If you revert a merge commit and then change your mind, revert the revert commit to redo the merge. +Git does not allow you to merge the code again otherwise. + +## Reducing merge commits in feature branches  -With git you can also rebase your feature branch commits to order them after the commits on the master branch. -This prevents creating a merge commit when merging master into your feature branch and creates a nice linear history. -However, just like with squashing you should never rebase commits you have pushed to a remote server. -This makes it impossible to rebase work in progress that you already shared with your team which is something we recommend. -When using rebase to keep your feature branch updated you [need to resolve similar conflicts again and again](https://blogs.atlassian.com/2013/10/git-team-workflows-merge-or-rebase/). -You can reuse recorded resolutions (rerere) sometimes, but without rebasing you only have to solve the conflicts one time and you’re set. -There has to be a better way to avoid many merge commits. - -The way to prevent creating many merge commits is to not frequently merge master into the feature branch. -We'll discuss the three reasons to merge in master: leveraging code, merge conflicts, and long running branches. -If you need to leverage some code that was introduced in master after you created the feature branch you can sometimes solve this by just cherry-picking a commit. -If your feature branch has a merge conflict, creating a merge commit is a normal way of solving this. -You can prevent some merge conflicts by using [gitattributes](http://git-scm.com/docs/gitattributes) for files that can be in a random order. -For example in GitLab our changelog file is specified in .gitattributes as `CHANGELOG.md merge=union` so that there are fewer merge conflicts in it. -The last reason for creating merge commits is having long lived branches that you want to keep up to date with the latest state of the project. -Martin Fowler, in [his article about feature branches](http://martinfowler.com/bliki/FeatureBranch.html) talks about this Continuous Integration (CI). -At GitLab we are guilty of confusing CI with branch testing. Quoting Martin Fowler: "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. -That's continuous building, and a Good Thing, but there's no integration, so it's not CI.". -The solution to prevent many merge commits is to keep your feature branches short-lived, the vast majority should take less than one day of work. -If your feature branches commonly take more than a day of work, look into ways to create smaller units of work and/or use [feature toggles](http://martinfowler.com/bliki/FeatureToggle.html). -As for the long running branches that take more than one day there are two strategies. -In a CI strategy you can merge in master at the start of the day to prevent painful merges at a later time. -In a synchronization point strategy you only merge in from well defined points in time, for example a tagged release. -This strategy is [advocated by Linus Torvalds](https://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html) because the state of the code at these points is better known. - -In conclusion, we can say that you should try to prevent merge commits, but not eliminate them. -Your codebase should be clean but your history should represent what actually happened. -Developing software happen in small messy steps and it is OK to have your history reflect this. -You can use tools to view the network graphs of commits and understand the messy history that created your code. -If you rebase code the history is incorrect, and there is no way for tools to remedy this because they can't deal with changing commit identifiers. +Having lots of merge commits can make your repository history messy. +Therefore, you should try to avoid merge commits in feature branches. +Often, people avoid merge commits by just using rebase to reorder their commits after the commits on the `master` branch. +Using rebase prevents a merge commit when merging `master` into your feature branch, and it creates a neat linear history. +However, as discussed in [the section about rebasing](#squashing-commits-with-rebase), you should never rebase commits you have pushed to a remote server. +This restriction makes it impossible to rebase work in progress that you already shared with your team, which is something we recommend. -## Award emojis on issues and merge requests +Rebasing also creates more work, since every time you rebase, you have to resolve similar conflicts. +Sometimes you can reuse recorded resolutions (`rerere`), but merging is better since you only have to resolve conflicts once. +Atlassian has a more thorough explanation of the tradeoffs between merging and rebasing [on their blog](https://www.atlassian.com/blog/git/git-team-workflows-merge-or-rebase). - +A good way to prevent creating many merge commits is to not frequently merge `master` into the feature branch. +There are three reasons to merge in `master`: utilizing new code, resolving merge conflicts, and updating long-running branches. -It is common to voice approval or disapproval by using +1 or -1. In GitLab you -can use emojis to give a virtual high five on issues and merge requests. +If you need to utilize some code that was introduced in `master` after you created the feature branch, you can often solve this by just cherry-picking a commit. -## Pushing and removing branches +If your feature branch has a merge conflict, creating a merge commit is a standard way of solving this. - +NOTE: **Note:** +Sometimes you can use .gitattributes to reduce merge conflicts. +For example, you can set your changelog file to use the [union merge driver](https://git-scm.com/docs/gitattributes#gitattributes-union) so that multiple new entries don't conflict with each other. -We recommend that people push their feature branches frequently, even when they are not ready for review yet. -By doing this you prevent team members from accidentally starting to work on the same issue. -Of course this situation should already be prevented by assigning someone to the issue in the issue tracking software. -However sometimes one of the two parties forgets to assign someone in the issue tracking software. -After a branch is merged it should be removed from the source control software. -In GitLab and similar systems this is an option when merging. -This ensures that the branch overview in the repository management software shows only work in progress. -This also ensures that when someone reopens the issue a new branch with the same name can be used without problem. -When you reopen an issue you need to create a new merge request. +The last reason for creating merge commits is to keep long-running feature branches up-to-date with the latest state of the project. +The solution here is to keep your feature branches short-lived. +Most feature branches should take less than one day of work. +If your feature branches often take more than a day of work, try to split your features into smaller units of work. + +If you need to keep a feature branch open for more than a day, there are a few strategies to keep it up-to-date. +One option is to use continuous integration (CI) to merge in `master` at the start of the day. +Another option is to only merge in from well-defined points in time, for example, a tagged release. +You could also use [feature toggles](https://martinfowler.com/bliki/FeatureToggle.html) to hide incomplete features so you can still merge back into `master` every day. + +> **Note:** Don't confuse automatic branch testing with continuous integration. +> Martin Fowler makes this distinction in [his article about feature branches](https://martinfowler.com/bliki/FeatureBranch.html): +> +> "I've heard people say they are doing CI because they are running builds, perhaps using a CI server, on every branch with every commit. +> That's continuous building, and a Good Thing, but there's no *integration*, so it's not CI." + +In conclusion, you should try to prevent merge commits, but not eliminate them. +Your codebase should be clean, but your history should represent what actually happened. +Developing software happens in small, messy steps, and it is OK to have your history reflect this. +You can use tools to view the network graphs of commits and understand the messy history that created your code. +If you rebase code, the history is incorrect, and there is no way for tools to remedy this because they can't deal with changing commit identifiers. + +## Commit often and push frequently + +Another way to make your development work easier is to commit often. +Every time you have a working set of tests and code, you should make a commit. +Splitting up work into individual commits provides context for developers looking at your code later. +Smaller commits make it clear how a feature was developed, and they make it easy to roll back to a specific good point in time or to revert one code change without reverting several unrelated changes. + +Committing often also makes it easy to share your work, which is important so that everyone is aware of what you are working on. +You should push your feature branch frequently, even when it is not yet ready for review. +By sharing your work in a feature branch or [a merge request](#mergepull-requests-with-gitlab-flow), you prevent your team members from duplicating work. +Sharing your work before it's complete also allows for discussion and feedback about the changes, which can help improve the code before it gets to review. -## Committing often and with the right message +## How to write a good commit message  -We recommend to commit early and often. -Each time you have a functioning set of tests and code a commit can be made. -The advantage is that when an extension or refactor goes wrong it is easy to revert to a working version. -This is quite a change for programmers that used SVN before, they used to commit when their work was ready to share. -The trick is to use the merge/pull request with multiple commits when your work is ready to share. -The commit message should reflect your intention, not the contents of the commit. -The contents of the commit can be easily seen anyway, the question is why you did it. -An example of a good commit message is: "Combine templates to dry up the user views.". -Some words that are bad commit messages because they don't contain much information are: change, improve and refactor. -The word fix or fixes is also a red flag, unless it comes after the commit sentence and references an issue number. -To see more information about the formatting of commit messages please see this great [blog post by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). +A commit message should reflect your intention, not just the contents of the commit. +It is easy to see the changes in a commit, so the commit message should explain why you made those changes. +An example of a good commit message is: "Combine templates to reduce duplicate code in the user views." +The words "change," "improve," "fix," and "refactor" don't add much information to a commit message. +For example, "Improve XML generation" could be better written as "Properly escape special characters in XML generation." +For more information about formatting commit messages, please see this excellent [blog post by Tim Pope](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html). ## Testing before merging - - -In old workflows the Continuous Integration (CI) server commonly ran tests on the master branch only. -Developers had to ensure their code did not break the master branch. -When using GitLab flow developers create their branches from this master branch so it is essential it is green. -Therefore each merge request must be tested before it is accepted. -CI software like Travis and GitLab CI show the build results right in the merge request itself to make this easy. -One drawback is that they are testing the feature branch itself and not the merged result. -What one can do to improve this is to test the merged result itself. -The problem is that the merge result changes every time something is merged into master. -Retesting on every commit to master is computationally expensive and means you are more frequently waiting for test results. -If there are no merge conflicts and the feature branches are short lived the risk is acceptable. -If there are merge conflicts you merge the master branch into the feature branch and the CI server will rerun the tests. -If you have long lived feature branches that last for more than a few days you should make your issues smaller. + -## Working with feature branches +In old workflows, the continuous integration (CI) server commonly ran tests on the `master` branch only. +Developers had to ensure their code did not break the `master` branch. +When using GitLab flow, developers create their branches from this `master` branch, so it is essential that it never breaks. +Therefore, each merge request must be tested before it is accepted. +CI software like Travis CI and GitLab CI show the build results right in the merge request itself to make this easy. - +There is one drawback to testing merge requests: the CI server only tests the feature branch itself, not the merged result. +Ideally, the server could also test the `master` branch after each change. +However, retesting on every commit to `master` is computationally expensive and means you are more frequently waiting for test results. +Since feature branches should be short-lived, testing just the branch is an acceptable risk. +If new commits in `master` cause merge conflicts with the feature branch, merge `master` back into the branch to make the CI server re-run the tests. +As said before, if you often have feature branches that last for more than a few days, you should make your issues smaller. -When initiating a feature branch, always start with an up to date master to branch off from. -If you know beforehand that your work absolutely depends on another branch you can also branch from there. -If you need to merge in another branch after starting explain the reason in the merge commit. -If you have not pushed your commits to a shared location yet you can also rebase on master or another feature branch. -Do not merge in upstream if your code will work and merge cleanly without doing so, Linus even says that [you should never merge in upstream at random points, only at major releases](https://lwn.net/Articles/328438/). -Merging only when needed prevents creating merge commits in your feature branch that later end up littering the master history. +## Working with feature branches -### References + -- [Git Flow by Vincent Driessen](http://nvie.com/posts/a-successful-git-branching-model/) +When creating a feature branch, always branch from an up-to-date `master`. +If you know before you start that your work depends on another branch, you can also branch from there. +If you need to merge in another branch after starting, explain the reason in the merge commit. +If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on `master` or another feature branch. +Do not merge from upstream again if your code can work and merge cleanly without doing so. +Merging only when needed prevents creating merge commits in your feature branch that later end up littering the `master` history. diff --git a/doc/workflow/time_tracking.md b/doc/workflow/time_tracking.md index 2bb140b99d0..ad43189148c 100644 --- a/doc/workflow/time_tracking.md +++ b/doc/workflow/time_tracking.md @@ -38,13 +38,14 @@ Adding time entries (time spent or estimates) is limited to project members. To enter an estimate, write `/estimate`, followed by the time. For example, if you need to enter an estimate of 3 days, 5 hours and 10 minutes, you would write -`/estimate 3d 5h 10m`. +`/estimate 3d 5h 10m`. Time units that we support are listed at the bottom of +this help page. Every time you enter a new time estimate, any previous time estimates will be overridden by this new value. There should only be one valid estimate in an issue or a merge request. -To remove an estimation entirely, use `/remove_estimation`. +To remove an estimation entirely, use `/remove_estimate`. ### Time spent @@ -72,5 +73,8 @@ The following time units are available: Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. -[landing]: https://about.gitlab.com/features/time-tracking +Other interesting links: + +- [Time Tracking landing page on about.gitlab.com](https://about.gitlab.com/features/time-tracking) + [quick actions]: ../user/project/quick_actions.md |
