Change location of Maven packages docs

doc/administration/maven_packages.md

@@ -7,14 +7,14 @@ in GitLab 11.3. To learn how to use
 When the GitLab Maven repository is enabled, every project in GitLab will have
 its own space to store [Maven](https://maven.apache.org/) packages.
 
-To learn how to use it, see the [user documentation](../user/project/maven_packages.md).
+To learn how to use it, see the [user documentation](../user/project/packages/maven.md).
 
 ## Enabling the Packages repository
 
 NOTE: **Note:**
 Once enabled, newly created projects will have the Packages feature enabled by
 default. Existing projects will need to
-[explicitly enabled it](../user/project/maven_packages.md#enabling-the-packages-repository).
+[explicitly enabled it](../user/project/packages/maven.md#enabling-the-packages-repository).
 
 To enable the Packages repository:
 
@@ -82,18 +82,14 @@ upload the maven packages:
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
    necessary):
 
-
-
-
-
     ```ruby
     gitlab_rails['packages_enabled'] = true
     gitlab_rails['packages_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/packages"
     gitlab_rails['packages_object_store_enabled'] = true
-    gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name
-    gitlab_rails['packages_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false)
-    gitlab_rails['packages_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true)
-    gitlab_rails['packages_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage
+    gitlab_rails['packages_object_store_remote_directory'] = "packages" # The bucket name.
+    gitlab_rails['packages_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
+    gitlab_rails['packages_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
+    gitlab_rails['packages_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
     gitlab_rails['packages_object_store_connection'] = {
       ##
       ## If the provider is AWS S3, uncomment the following
@@ -107,8 +103,8 @@ upload the maven packages:
       ##
       #'host' => 's3.amazonaws.com',
       #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
-      #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces
-      #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'
+      #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
+      #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
     }
     ```
 
@@ -116,7 +112,7 @@ upload the maven packages:
 
 **Installations from source**
 
-1. Edit the `packages` section in `config/gitlab.yml`:
+1. Edit the `packages` section in `config/gitlab.yml` (uncomment where necessary):
 
     ```yaml
       packages:
@@ -127,10 +123,10 @@ upload the maven packages:
         #storage_path: shared/packages
         object_store:
           enabled: false
-          remote_directory: packages # The bucket name
-          #direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false)
-          #background_upload: true   # Temporary option to limit automatic upload (Default: true)
-          #proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage
+          remote_directory: packages # The bucket name.
+          #direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
+          #background_upload: true   # Temporary option to limit automatic upload (Default: true).
+          #proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
           connection:
             ##
             ## If the provider is AWS S3, uncomment the following
@@ -142,9 +138,10 @@ upload the maven packages:
             ##
             ## If the provider is other than AWS (an S3-compatible one), uncomment the following
             ##
-            #host: 's3.amazonaws.com'             # default: s3.amazonaws.com
-            #endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces
-            #path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'
+            #host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
+            #aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
+            #endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
+            #path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
     ```
 
 1. [Restart GitLab] for the changes to take effect.

doc/user/project/index.md

@@ -86,7 +86,7 @@ website with GitLab Pages
 - [Syntax highlighting](highlighting.md): An alternative to customize
 your code blocks, overriding GitLab's default choice of language
 - [Badges](badges.md): Badges for the project overview
-- [Maven packages](maven_packages.md): Your private Maven repository in GitLab
+- [Maven packages](packages/maven.md): Your private Maven repository in GitLab **[PREMIUM]**
 - [Code owners](code_owners.md): Specify code owners for certain files **[STARTER]**
 
 ### Project's integrations

doc/user/project/maven_packages.md → doc/user/project/packages/maven.md

@@ -5,11 +5,13 @@
 With the GitLab [Maven](https://maven.apache.org) Packages repository, every
 project can have its own space to store its Maven artifacts.
 
+![GitLab Maven repository](img/maven_package_view.png)
+
 ## Enabling the Packages repository
 
 NOTE: **Note:**
 This option is available only if your GitLab administrator has
-[enabled the Packages repository](../../administration/maven_packages.md).
+[enabled the Packages repository](../../../administration/maven_packages.md).
 
 In order to use the GitLab Maven Packages repository, you must enable the
 Packages repository. To enable (or disable) it:
@@ -27,7 +29,7 @@ repository.
 If a project is private or you want to upload Maven artifacts to GitLab,
 credentials will need to be provided for authorization:
 
-1. Create a new [personal access token](../profile/personal_access_tokens.md)
+1. Create a new [personal access token](../../profile/personal_access_tokens.md)
    with the `api` scope.
 1. Add a corresponding section to your
    [`settings.xml`](https://maven.apache.org/settings.html) file:
@@ -54,8 +56,8 @@ You should now be able to upload Maven artifacts to your project.
 
 ## Configuring your project to use the GitLab Maven repository URL
 
-To download packages from GitLab, you need a `repository` section in your
-`pom.xml` file:
+To download and upload packages from GitLab, you need a `repository` and
+`distributionManagement` section respectively in your `pom.xml` file:
 
 ```xml
 <repositories>
@@ -64,12 +66,6 @@ To download packages from GitLab, you need a `repository` section in your
     <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
   </repository>
 </repositories>
-```
-
-Similarly, to upload packages to GitLab, you need a `distributionManagement`
-section in your `pom.xml` file:
-
-```xml
 <distributionManagement>
   <repository>
     <id>gitlab-maven</id>
@@ -88,9 +84,22 @@ The `id` must be the same with what you
 In both examples, replace `PROJECT_ID` with your project ID which can be found
 on the home page of your project.
 
-If you have a private GitLab installation, replace `gitlab.com` with your
+If you have a self-hosted GitLab installation, replace `gitlab.com` with your
 domain name.
 
+## Uploading packages
+
+Once you have set up the [authorization](#authorizing-with-the-gitlab-maven-repository)
+and [configuration](#configuring-your-project-to-use-the-gitlab-maven-repository-url),
+test to upload a Maven artifact from a project of yours:
+
+```sh
+mvn deploy
+```
+
+You can then navigate to your project's **Packages** page and see the uploaded
+artifacts or even delete them.
+
 ## Creating Maven packages with GitLab CI/CD
 
 Once you have your repository configured to use the GitLab Maven Packages repository,
@@ -120,6 +129,31 @@ shows how to create a new package each time the `master` branch is updated:
     </settings>
     ```
 
+1. Make sure your `pom.xml` file includes the following:
+
+    ```xml
+    <repositories>
+      <repository>
+        <id>gitlab-maven</id>
+        <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
+      </repository>
+    </repositories>
+    <distributionManagement>
+      <repository>
+        <id>gitlab-maven</id>
+        <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
+      </repository>
+      <snapshotRepository>
+        <id>gitlab-maven</id>
+        <url>https://gitlab.com/api/v4/projects/PROJECT_ID/packages/maven</url>
+      </snapshotRepository>
+    </distributionManagement>
+    ```
+
+    TIP: **Tip:**
+    You can either leave GitLab CI/CD to replace your project ID value while
+    the deploy job is running or hardcode your project's ID.
+
 1. Add a `deploy` job to your `.gitlab-ci.yml` file:
 
     ```yaml
@@ -128,6 +162,7 @@ shows how to create a new package each time the `master` branch is updated:
       script:
         - 'cp ci_settings.xml /root/.m2/settings.xml'
         - 'sed -i "s/CI_JOB_TOKEN/${CI_JOB_TOKEN}/g" /root/.m2/settings.xml'
+        - 'sed -i "s/PROJECT_ID/${CI_PROJECT_ID}/g" pom.xml'
         - 'mvn deploy'
       only:
         - master
@@ -137,6 +172,6 @@ shows how to create a new package each time the `master` branch is updated:
 
 The next time the `deploy` job runs, it will copy `ci_settings.xml` to the
 user's home location (in this case the user is `root` since it runs in a
-Docker container), and `sed` will replace the placeholder `CI_JOB_TOKEN`
-value with the contents of the actual [`CI_JOB_TOKEN`
-environment variable](../../ci/variables/README.md#predefined-variables-environment-variables).
+Docker container), and `sed` will replace the placeholder values with the
+contents of the actual
+[environment variables](../../../ci/variables/README.md#predefined-variables-environment-variables).

ee/app/helpers/ee/projects_helper.rb

@@ -39,7 +39,7 @@ module EE
     def project_permissions_panel_data(project)
       super.merge(
         packagesAvailable: ::Gitlab.config.packages.enabled,
-        packagesHelpPath: help_page_path('user/project/maven_packages')
+        packagesHelpPath: help_page_path('user/project/packages/maven')
       )
     end