1---
2stage: Enablement
3group: Distribution
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5---
6
7# Uploads administration **(FREE SELF)**
8
9Uploads represent all user data that may be sent to GitLab as a single file. As an example, avatars and notes' attachments are uploads. Uploads are integral to GitLab functionality, and therefore cannot be disabled.
10
11## Using local storage
12
13This is the default configuration. To change the location where the uploads are
14stored locally, use the steps in this section based on your installation method:
15
16NOTE:
17For historical reasons, instance level uploads (for example the [favicon](../user/admin_area/appearance.md#favicon)) are stored into a base directory,
18which by default is `uploads/-/system`. It is strongly discouraged to change the base
19directory on an existing GitLab installation.
20
21**In Omnibus GitLab installations:**
22
23_The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._
24
251. To change the storage path for example to `/mnt/storage/uploads`, edit
26   `/etc/gitlab/gitlab.rb` and add the following line:
27
28   ```ruby
29   gitlab_rails['uploads_directory'] = "/mnt/storage/uploads"
30   ```
31
32   This setting only applies if you haven't changed the `gitlab_rails['uploads_storage_path']` directory.
33
341. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
35
36**In installations from source:**
37
38_The uploads are stored by default in
39`/home/git/gitlab/public/uploads`._
40
411. To change the storage path for example to `/mnt/storage/uploads`, edit
42   `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines:
43
44   ```yaml
45   uploads:
46     storage_path: /mnt/storage
47     base_dir: uploads
48   ```
49
501. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
51
52## Using object storage **(FREE SELF)**
53
54If you don't want to use the local disk where GitLab is installed to store the
55uploads, you can use an object storage provider like AWS S3 instead.
56This configuration relies on valid AWS credentials to be configured already.
57
58[Read more about using object storage with GitLab](object_storage.md).
59
60We recommend using the [consolidated object storage settings](object_storage.md#consolidated-object-storage-configuration). The following instructions apply to the original configuration format.
61
62### Object Storage Settings
63
64For source installations the following settings are nested under `uploads:` and then `object_store:`. On Omnibus GitLab installs they are prefixed by `uploads_object_store_`.
65
66| Setting | Description | Default |
67|---------|-------------|---------|
68| `enabled` | Enable/disable object storage | `false` |
69| `remote_directory` | The bucket name where Uploads will be stored| |
70| `direct_upload` | Set to `true` to remove Puma from the Upload path. Workhorse handles the actual Artifact Upload to Object Storage while Puma does minimal processing to keep track of the upload. There is no need for local shared storage. The option may be removed if support for a single storage type for all files is introduced. Read more on [direct upload](../development/uploads.md#direct-upload). | `false` |
71| `background_upload` | Set to `false` to disable automatic upload. Option may be removed once upload is direct to S3 (if `direct_upload` is set to `true` it will override `background_upload`) | `true` |
72| `proxy_download` | Set to `true` to enable proxying all files served. Option allows to reduce egress traffic as this allows clients to download directly from remote storage instead of proxying all data | `false` |
73| `connection` | Various connection options described below | |
74
75#### Connection settings
76
77See [the available connection settings for different providers](object_storage.md#connection-settings).
78
79**In Omnibus installations:**
80
81_The uploads are stored by default in
82`/var/opt/gitlab/gitlab-rails/uploads`._
83
841. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
85   the values you want:
86
87   ```ruby
88   gitlab_rails['uploads_object_store_enabled'] = true
89   gitlab_rails['uploads_object_store_remote_directory'] = "uploads"
90   gitlab_rails['uploads_object_store_connection'] = {
91     'provider' => 'AWS',
92     'region' => 'eu-central-1',
93     'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
94     'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
95   }
96   ```
97
98   If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
99
100   ```ruby
101   gitlab_rails['uploads_object_store_connection'] = {
102     'provider' => 'AWS',
103     'region' => 'eu-central-1',
104     'use_iam_profile' => true
105   }
106   ```
107
1081. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
1091. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md).
110
111**In installations from source:**
112
113_The uploads are stored by default in
114`/home/git/gitlab/public/uploads`._
115
1161. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
117   lines:
118
119   ```yaml
120   uploads:
121     object_store:
122       enabled: true
123       remote_directory: "uploads" # The bucket name
124       connection:
125         provider: AWS # Only AWS supported at the moment
126         aws_access_key_id: AWS_ACCESS_KEY_ID
127         aws_secret_access_key: AWS_SECRET_ACCESS_KEY
128         region: eu-central-1
129   ```
130
1311. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
1321. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md).
133
134#### OpenStack example
135
136**In Omnibus installations:**
137
138_The uploads are stored by default in
139`/var/opt/gitlab/gitlab-rails/uploads`._
140
1411. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with
142   the values you want:
143
144   ```ruby
145   gitlab_rails['uploads_object_store_remote_directory'] = "OPENSTACK_OBJECT_CONTAINER_NAME"
146   gitlab_rails['uploads_object_store_connection'] = {
147    'provider' => 'OpenStack',
148    'openstack_username' => 'OPENSTACK_USERNAME',
149    'openstack_api_key' => 'OPENSTACK_PASSWORD',
150    'openstack_temp_url_key' => 'OPENSTACK_TEMP_URL_KEY',
151    'openstack_auth_url' => 'https://auth.cloud.ovh.net/v2.0/',
152    'openstack_region' => 'DE1',
153    'openstack_tenant' => 'TENANT_ID',
154   }
155   ```
156
1571. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
1581. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md).
159
160---
161
162**In installations from source:**
163
164_The uploads are stored by default in
165`/home/git/gitlab/public/uploads`._
166
1671. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following
168   lines:
169
170   ```yaml
171   uploads:
172     object_store:
173       enabled: true
174       direct_upload: false
175       background_upload: true
176       proxy_download: false
177       remote_directory: OPENSTACK_OBJECT_CONTAINER_NAME
178       connection:
179         provider: OpenStack
180         openstack_username: OPENSTACK_USERNAME
181         openstack_api_key: OPENSTACK_PASSWORD
182         openstack_temp_url_key: OPENSTACK_TEMP_URL_KEY
183         openstack_auth_url: 'https://auth.cloud.ovh.net/v2.0/'
184         openstack_region: DE1
185         openstack_tenant: 'TENANT_ID'
186   ```
187
1881. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
1891. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate:all` Rake task](raketasks/uploads/migrate.md).
190