BigW Consortium Gitlab

Skip to content

G
gitlab-ce
Commit 9eb39dde by Douwe Maan
Options

Merge branch 'storages-doc-update' into 'master'

Change repository storage paths location for clarity See merge request !8757
parents d391f743 57a76de9
Showing with 104 additions and 102 deletions
doc/README.md
......@@ -44,7 +44,7 @@
- [Operations](administration/operations.md) Keeping GitLab up and running.
- [Raketasks](raketasks/README.md) Backups, maintenance, automatic webhook setup and the importing of projects.
- [Repository checks](administration/repository_checks.md) Periodic Git repository checks.
- [Repository storages](administration/repository_storages.md) Manage the paths used to store repositories.
- [Repository storage paths](administration/repository_storage_paths.md) Manage the paths used to store repositories.
- [Security](security/README.md) Learn what you can do to further secure your GitLab instance.
- [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed.
- [Update](update/README.md) Update guides to upgrade your installation.
......@@ -61,7 +61,6 @@
- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs.
- [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability.
- [Container Registry](administration/container_registry.md) Configure Docker Registry with GitLab.
- [Multiple mountpoints for the repositories storage](administration/repository_storages.md) Define multiple repository storage paths to distribute the storage load.
## Contributor documentation
......
doc/administration/repository_storage_paths.md 0 → 100644
# Repository storage paths
> [Introduced][ce-4578] in GitLab 8.10.
GitLab allows you to define multiple repository storage paths to distribute the
storage load between several mount points.
>**Notes:**
>
- You must have at least one storage path called `default`.
- The paths are defined in key-value pairs. The key is an arbitrary name you
can pick to name the file path.
- The target directories and any of its subpaths must not be a symlink.
## Configure GitLab
>**Warning:**
In order for [backups] to work correctly, the storage path must **not** be a
mount point and the GitLab user should have correct permissions for the parent
directory of the path. In Omnibus GitLab this is taken care of automatically,
but for source installations you should be extra careful.
>
The thing is that for compatibility reasons `gitlab.yml` has a different
structure than Omnibus. In `gitlab.yml` you indicate the path for the
repositories, for example `/home/git/repositories`, while in Omnibus you
indicate `git_data_dirs`, which for the example above would be `/home/git`.
Then, Omnibus will create a `repositories` directory under that path to use with
`gitlab.yml`.
>
This little detail matters because while restoring a backup, the current
contents of `/home/git/repositories` [are moved to][raketask] `/home/git/repositories.old`,
so if `/home/git/repositories` is the mount point, then `mv` would be moving
things between mount points, and bad things could happen. Ideally,
`/home/git` would be the mount point, so then things would be moving within the
same mount point. This is guaranteed with Omnibus installations (because they
don't specify the full repository path but the parent path), but not for source
installations.
---
Now that you've read that big fat warning above, let's edit the configuration
files and add the full paths of the alternative repository storage paths. In
the example below, we add two more mountpoints that are named `nfs` and `cephfs`
respectively.
**For installations from source**
1. Edit `gitlab.yml` and add the storage paths:
```yaml
repositories:
# Paths where repositories can be stored. Give the canonicalized absolute pathname.
# NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
storages: # You must have at least a 'default' storage path.
default: /home/git/repositories
nfs: /mnt/nfs/repositories
cephfs: /mnt/cephfs/repositories
```
1. [Restart GitLab] for the changes to take effect.
>**Note:**
The [`gitlab_shell: repos_path` entry][repospath] in `gitlab.yml` will be
deprecated and replaced by `repositories: storages` in the future, so if you
are upgrading from a version prior to 8.10, make sure to add the configuration
as described in the step above. After you make the changes and confirm they are
working, you can remove the `repos_path` line.
---
**For Omnibus installations**
1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the
default one:
```ruby
git_data_dirs({
"default" => "/var/opt/gitlab/git-data",
"nfs" => "/mnt/nfs/git-data",
"cephfs" => "/mnt/cephfs/git-data"
})
```
Note that Omnibus stores the repositories in a `repositories` subdirectory
of the `git-data` directory.
## Choose where new project repositories will be stored
Once you set the multiple storage paths, you can choose where new projects will
be stored via the **Application Settings** in the Admin area.
![Choose repository storage path in Admin area](img/repository_storages_admin_ui.png)
Beginning with GitLab 8.13.4, multiple paths can be chosen. New projects will be
randomly placed on one of the selected paths.
[ce-4578]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4578
[restart gitlab]: restart_gitlab.md#installations-from-source
[reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure
[backups]: ../raketasks/backup_restore.md
[raketask]: https://gitlab.com/gitlab-org/gitlab-ce/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56
[repospath]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-9-stable/config/gitlab.yml.example#L457
doc/administration/repository_storages.md
# Repository storages
> [Introduced][ce-4578] in GitLab 8.10.
GitLab allows you to define multiple repository storage paths to distribute the
storage load between several mount points.
>**Notes:**
>
- You must have at least one storage path called `default`.
- The paths are defined in key-value pairs. The key is an arbitrary name you
can pick to name the file path.
- The target directories and any of its subpaths must not be a symlink.
## Configure GitLab
>**Warning:**
In order for [backups] to work correctly, the storage path must **not** be a
mount point and the GitLab user should have correct permissions for the parent
directory of the path. In Omnibus GitLab this is taken care of automatically,
but for source installations you should be extra careful.
>
The thing is that for compatibility reasons `gitlab.yml` has a different
structure than Omnibus. In `gitlab.yml` you indicate the path for the
repositories, for example `/home/git/repositories`, while in Omnibus you
indicate `git_data_dirs`, which for the example above would be `/home/git`.
Then, Omnibus will create a `repositories` directory under that path to use with
`gitlab.yml`.
>
This little detail matters because while restoring a backup, the current
contents of `/home/git/repositories` [are moved to][raketask] `/home/git/repositories.old`,
so if `/home/git/repositories` is the mount point, then `mv` would be moving
things between mount points, and bad things could happen. Ideally,
`/home/git` would be the mount point, so then things would be moving within the
same mount point. This is guaranteed with Omnibus installations (because they
don't specify the full repository path but the parent path), but not for source
installations.
---
Now that you've read that big fat warning above, let's edit the configuration
files and add the full paths of the alternative repository storage paths. In
the example below, we add two more mountpoints that are named `nfs` and `cephfs`
respectively.
**For installations from source**
1. Edit `gitlab.yml` and add the storage paths:
```yaml
repositories:
# Paths where repositories can be stored. Give the canonicalized absolute pathname.
# NOTE: REPOS PATHS MUST NOT CONTAIN ANY SYMLINK!!!
storages: # You must have at least a 'default' storage path.
default: /home/git/repositories
nfs: /mnt/nfs/repositories
cephfs: /mnt/cephfs/repositories
```
1. [Restart GitLab] for the changes to take effect.
>**Note:**
The [`gitlab_shell: repos_path` entry][repospath] in `gitlab.yml` will be
deprecated and replaced by `repositories: storages` in the future, so if you
are upgrading from a version prior to 8.10, make sure to add the configuration
as described in the step above. After you make the changes and confirm they are
working, you can remove the `repos_path` line.
---
**For Omnibus installations**
1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the
default one:
```ruby
git_data_dirs({
"default" => "/var/opt/gitlab/git-data",
"nfs" => "/mnt/nfs/git-data",
"cephfs" => "/mnt/cephfs/git-data"
})
```
Note that Omnibus stores the repositories in a `repositories` subdirectory
of the `git-data` directory.
## Choose where new project repositories will be stored
Once you set the multiple storage paths, you can choose where new projects will
be stored via the **Application Settings** in the Admin area.
![Choose repository storage path in Admin area](img/repository_storages_admin_ui.png)
Beginning with GitLab 8.13.4, multiple paths can be chosen. New projects will be
randomly placed on one of the selected paths.
[ce-4578]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4578
[restart gitlab]: restart_gitlab.md#installations-from-source
[reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure
[backups]: ../raketasks/backup_restore.md
[raketask]: https://gitlab.com/gitlab-org/gitlab-ce/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56
[repospath]: https://gitlab.com/gitlab-org/gitlab-ce/blob/8-9-stable/config/gitlab.yml.example#L457
This document was moved to a [new location](repository_storage_paths.md).
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment