GitLab Next

Description

Currently, creating a GitLab pages project would require a domain of the form name.example.io or name.pages.example.io. This setup forces admins to setup wildcard DNS records and SSL/TLS certificates (i.e. *.pages.example.io). Some services typically used by small structures or individuals (such as Let's Encrypt) disallow this.

Removing the requirement for wildcard certificates would allow using services like Let's Encrypt on the main GitLab pages domain, without the need to setup a custom domain. It would also allow for easy configuration of custom HTTP(S) proxies like Apache. Finally, IMHO having an exponential amount of off-the-radar subdomains is really bad when you try to keep your DNS space clean and tidy.

~"feature proposal" gitlab-ce~4107696

Proposal

In order to remove the need for wildcard dns, the namespace can be included in the URL path instead of the domain.

Thus, https://name.pages.example.io/index.html would become https://pages.example.io/name/index.html.

This could be done by setting a specific variable in /etc/gitlab/gitlab.rb, e.g.

gitlab_pages["namespace_in_path"] = true;

This variable would then change the URL parsing rule used by GitLab pages so that it will look for the namespace in the URL path instead of the subdomain.

In order to ensure compatibility with existing setups, this feature would obviously be turned off by default.

As part of pages rearchitecture we're moving host resolving to the rails API(https://gitlab.com/gitlab-org/gitlab/blob/a5d7d416e8f4c101120a051549f4f1c0f9db8be9/lib/api/internal/pages.rb#L27).

Also, there are a few configuration possibilities:

1. parameter in omnibus, we generally try to avoid this, as this is more complicated then tweaking the UI, but we'll need this if we add some additional parameter for gitlab-pages daemon
2. UI checkbox use path instead of subdomains in admin panel(if we don't need new parameters for pages
3. pages-daemon param itself

We need to choose between:

• implementation inside pages daemon
• implementation using nginx proxy

If we choose pages daemon implementation

I would declare this feature experimental and start merging some code, maybe some users can try this new mode in their environment. This serves a few purposes:

1. It's hard to be 100% sure that we won't find some major problems with this approach in the future. And if in that case it will be nice to have options:
   1. redesign implementation(including configuration parameters)
   2. remove the feature completely
2. it will allow us to get some early feedback from users. Since we won't enable this mode on .com, some production cases will be nice to see.

So we can devide development into 3 main phases:

Developing experimental version(we can call it MVC):

1. Finish the PoC gitlab-pages!256 (closed) and merge it
2. Test the authentication workflow and it will probably require some additional fixes
3. Omnibus MR to configure both rails and pages parameters
4. gitlab-pages MR to stop requiring wildcard certificates
5. one of:
   1. omnibus MR to create pages auth application with base url pages.example.com/projects/auth instead of projects.pages.example.com/auth
   2. or gitlab-pages MR to allow serving projects.pages.example.com in the new mode(may require additional SSL certificate)
6. very basic MR for documentation

it will have /weight 6

Everything else is outside of this MVC

Collecting some feedback from users and fixing bugs

Ask some users upvoted issue to try this feature.

Moving feature to stable status

If there will no major problems discovered by us and by first adopters, we can declare this feature stable

We'll need to:

1. Write better documentation for it, including migration from the current setup(e.g. recreating auth application to have new redirect url)
2. write more extensive test suite for this mode including:
   1. tests for auth workflow
   2. tests for artifacts proxying
3. remove all the mentions and warnings about experimental status

If we choose nginx implementation

Fill after finishing the research issue#211677

Links / references

Let's Encrypt FAQ

Reserves

This setup might have security or technical issues I do not know of. I have not been able to find the reasons behind the choice to include namespaces as subdomains, and I would be interested to know about them.