address documentation issues

README.md

@@ -201,7 +201,7 @@ See [doc/common_installation_problems/README.md](doc/common_installation_problem
 See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#i-am-unable-to-install-omnibus-gitlab-without-root-access).
-##### gitlab-rake assets:precompile or gitlab:assets:compile fails with 'Permission denied'
+##### gitlab-rake assets:precompile fails with 'Permission denied'
 See [doc/common_installation_problems/README.md](doc/common_installation_problems/README.md#gitlab-rake-assetsprecompile-fails-with-permission-denied).

doc/README.md

@@ -75,7 +75,7 @@ Omnibus is a way to package different services and tools required to run GitLab,
 - [Reconfigure fails to create the git user](common_installation_problems/README.md#reconfigure-fails-to-create-the-git-user).
 - [Failed to modify kernel parameters with sysctl](common_installation_problems/README.md#failed-to-modify-kernel-parameters-with-sysctl).
 - [I am unable to install omnibus-gitlab without root access](common_installation_problems/README.md#i-am-unable-to-install-omnibus-gitlab-without-root-access).
-- [gitlab-rake gitlab:assets:compile fails with 'Permission denied'](common_installation_problems/README.md#gitlab-rake-gitlabassetscompile-fails-with-permission-denied).
+- [gitlab-rake assets:precompile fails with 'Permission denied'](common_installation_problems/README.md#gitlab-rake-assetsprecompile-fails-with-permission-denied).
 - ['Short read or OOM loading DB' error](common_installation_problems/README.md#short-read-or-oom-loading-db-error).
 - ['pg_dump: aborting because of server version mismatch'](settings/database.md#using-a-non-packaged-postgresql-database-management-server)
 - ['Errno::ENOMEM: Cannot allocate memory' during backup or upgrade](common_installation_problems/README.md#errnoenomem-cannot-allocate-memory-during-backup-or-upgrade)

doc/common_installation_problems/README.md

@@ -291,10 +291,10 @@ During 'gitlab-ctl reconfigure' we set and install several sysctl
 tweaks to improve Postgres performance and increase connection limits.
 This can only be done with root access.
-### gitlab-rake gitlab:assets:compile fails with 'Permission denied'
-Some users report that running `gitlab-rake gitlab:assets:compile` does not
-work with the omnibus packages. The short answer to this is: do not run that
+### gitlab-rake assets:precompile fails with 'Permission denied'
+Some users report that running `gitlab-rake assets:precompile` does not work
+with the omnibus packages. The short answer to this is: do not run that
 command, it is only for GitLab installations from source.
 The GitLab web interface uses CSS and JavaScript files, called 'assets' in Ruby
@@ -305,7 +305,7 @@ you are a normal user of GitLab, you do not want these files to be in the
 developer friendly format however because that makes GitLab slow. This is why
 part of the GitLab setup process is to convert the assets from a
 developer-friendly format to an end-user friendly (compact, fast) format; that
-is what the `rake gitlab:assets:compile` script is for.
+is what the `rake assets:precompile` script is for.
 When you install GitLab from source (which was the only way to do it before we
 had omnibus packages) you need to convert the assets on your GitLab server
@@ -315,11 +315,11 @@ each other to run `rake assets:precompile` (which has now been renamed
 `gitlab:assets:compile`). With the omnibus packages things are different: when
 we build the package [we compile the assets for you](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/1cfe925e0c015df7722bb85eddc0b4a3b59c1211/config/software/gitlab-rails.rb#L74).
 When you install GitLab with an omnibus package, the converted assets are
-already there! That is why you do not need to run `rake gitlab:assets:compile`
-when you install GitLab from a package.
-When `gitlab-rake gitlab:assets:compile` fails with a permission error it fails
-for a good reason from a security standpoint: the fact that the assets cannot
+already there! That is why you do not need to run `rake assets:precompile` when
+you install GitLab from a package.
+When `gitlab-rake assets:precompile` fails with a permission error it fails for
+a good reason from a security standpoint: the fact that the assets cannot
 easily be rewritten makes it harder for an attacker to use your GitLab server
 to serve evil JavaScript code to the visitors of your GitLab server.
@@ -327,7 +327,7 @@ If you want to run GitLab with custom JavaScript or CSS code you are probably
 better off running GitLab from source, or building your own packages.
 If you really know what you are doing,
-you can execute `gitlab-rake gitlab:assets:compile` like this
+you can execute `gitlab-rake gitlab:assets:compile` like this:
 ```shell
 sudo NO_PRIVILEGE_DROP=true USE_DB=false gitlab-rake gitlab:assets:clean gitlab:assets:compile

doc/settings/configuration.md

@@ -34,6 +34,17 @@ be installed under a relative URL, for example `https://example.com/gitlab`.
 Note that by changing the URL, all remote URLS will change, so you'll have to
 manually edit them in any local repository that points to your GitLab instance.
+### Relative URL requirements
+
+_Starting with 8.17 packages, there is **no need to recompile assets**._
+
+The Omnibus GitLab package is shipped with pre-compiled assets (CSS, JavaScript,
+fonts, etc.). If you are running a package _prior to 8.17_ and you configure
+Omnibus with a relative URL, the assets will need to be recompiled, which is a
+task which consumes a lot of CPU and memory resources. To avoid out-of-memory
+errors, you should have at least 2GB of RAM available on your system, while we
+recommend 4GB RAM, and 4 or 8 CPU cores.
+
 ### Enable relative URL in GitLab
 Follow the steps below to enable relative URL in GitLab:
@@ -83,6 +94,29 @@ sudo gitlab-ctl restart unicorn
 If you stumble upon any issues, see the [troubleshooting section]
 (#relative-url-troubleshooting).
+### Relative URL troubleshooting
+
+If you notice any issues with gitlab assets appearing broken after moving to a
+relative url configuration (like missing images or unresponsive components)
+please raise an issue in [GitLab CE](https://gitlab.com/gitlab-org/gitlab-ce)
+with the `Frontend` label.
+
+If you are running a version _prior to 8.17_ and for some reason the asset
+compilation step fails (i.e. the server runs out of memory), you can execute
+the task manually after you addressed the issue (e.g. add swap):
+
+```shell
+sudo NO_PRIVILEGE_DROP=true USE_DB=false gitlab-rake assets:clean assets:precompile
+sudo chown -R git:git /var/opt/gitlab/gitlab-rails/tmp/cache
+```
+
+User and path might be different if you changed the defaults of
+`user['username']`, `user['group']` and `gitlab_rails['dir']` in `gitlab.rb`.
+In that case, make sure that the `chown` command above is run with the right
+username and group.
+
+[590]: https://gitlab.com/gitlab-org/omnibus-gitlab/merge_requests/590 "Merge request - Relative url support for omnibus installations"
+
 ## Loading external configuration file from non-root user
 Omnibus-gitlab package loads all configuration from `/etc/gitlab/gitlab.rb` file.