with [John Northrup](https://gitlab.com/northrup), and live questions coming
in from some of our customers.
## Maturity levels
## Scaling examples
### Level 1: Single-node Omnibus installation
### Single-node Omnibus installation
This solution is appropriate for many teams that have a single server at their disposal. With automatic backup of the GitLab repositories, configuration, and the database, this can be an optimal solution if you don't have strict availability requirements.
This configuration is supported in [GitLab Starter, Premium and Ultimate](https://about.gitlab.com/pricing/).
You can also optionally configure GitLab to use an [external PostgreSQL service](../external_database.md)
or an [external object storage service](object_storage.md) for added
performance and reliability at a relatively low complexity cost.
### Omnibus installation with multiple application servers
By separating components you can see a number of advantages compared to a single-node setup. Namely, you can:
This solution is appropriate for teams that are starting to scale out when
scaling up is no longer meeting their needs. In this configuration, additional application nodes will handle frontend traffic, with a load balancer in front to distribute traffic across those nodes. Meanwhile, each application node connects to a shared file server and PostgreSQL and Redis services on the back end.
- Increase the number of users
- Enable zero-downtime upgrades
- Increase availability
Additional application nodes will handle frontend traffic, with a load balancer in front to distribute traffic across those nodes. Meanwhile, each application node connects to a shared file server and database systems on the back end. This way, if one of the application servers fails, the workflow is not interrupted.
This configuration is supported in [GitLab Starter, Premium and Ultimate](https://about.gitlab.com/pricing/).
The additional application servers adds limited fault tolerance to your GitLab
instance. As long as one application node is online and capable of handling the
instance's usage load, your team's productivity will not be interrupted. Having
multiple application nodes also enables [zero-downtime updates](https://docs.gitlab.com/omnibus/update/#zero-downtime-updates).
References:
-[High Availability Reference Architectures](#reference-architectures), without HA components
-[Configure your load balancer for GitLab](load_balancer.md)
-[Configure your NFS server to work with GitLab](nfs.md)
-[Configure packaged PostgreSQL server to listen on TCP/IP](https://docs.gitlab.com/omnibus/settings/database.html#configure-packaged-postgresql-server-to-listen-on-tcpip)
-[Setting up a Redis-only server](https://docs.gitlab.com/omnibus/settings/redis.html#setting-up-a-redis-only-server)
### Level 3: Highly Available
## High-availability examples
By adding automatic failover for database systems, we can enable higher uptime with an additional layer of complexity.
### Omnibus installation with automatic database failover
This configuration is supported in [GitLab Premium and Ultimate](https://about.gitlab.com/pricing/).
By adding automatic failover for database systems, we can enable higher uptime with an additional layer of complexity.
References:
- For PostgreSQL, we provide repmgr for server cluster management and failover
and a combination of [PgBouncer](pgbouncer.md) and [Consul](consul.md) for
database client cutover.
- For Redis, we use [Redis Sentinel](redis.md) for server failover and client cutover.
You can also optionally run [additional Sidekiq processes on dedicated hardware](sidekiq.md)
and configure individual Sidekiq processes to
[process specific background job queues](../operations/extra_sidekiq_processes.md)
if you need to scale out background job processing.
### Level 4: GitLab Geo
### GitLab Geo
GitLab Geo allows you to replicate your GitLab instance to other geographical locations as a read-only fully operational instance that can also be promoted in case of disaster.
...
...
@@ -70,12 +88,6 @@ References:
-[Geo Documentation](../geo/replication/index.md)
-[GitLab Geo with a highly available configuration](../geo/replication/high_availability.md)
## Recommended setups based on number of users
- 1 - 1000 Users: A single-node [Omnibus](https://docs.gitlab.com/omnibus/) setup with frequent backups. Refer to the [requirements page](../../install/requirements.md) for further details of the specs you will require.
- 1000 - 10000 Users: A scaled environment based on one of our [Reference Architectures](#reference-architectures), without the HA components applied. This can be a reasonable step towards a fully HA environment.
- 2000 - 50000+ Users: A scaled HA environment based on one of our [Reference Architectures](#reference-architectures) below.
## GitLab components and configuration instructions
The GitLab application depends on the following [components](../../development/architecture.md#component-diagram).
...
...
@@ -116,6 +128,12 @@ them.
In some cases, components can be combined on the same nodes to reduce complexity as well.
## Recommended setups based on number of users
- 1 - 1000 Users: A single-node [Omnibus](https://docs.gitlab.com/omnibus/) setup with frequent backups. Refer to the [requirements page](../../install/requirements.md) for further details of the specs you will require.
- 1000 - 10000 Users: A scaled environment based on one of our [Reference Architectures](#reference-architectures), without the HA components applied. This can be a reasonable step towards a fully HA environment.
- 2000 - 50000+ Users: A scaled HA environment based on one of our [Reference Architectures](#reference-architectures) below.
## Reference architectures
In this section we'll detail the Reference Architectures that can support large numbers
@@ -35,6 +35,14 @@ Read more in the [CI documentation](../ci/yaml/README.md#processing-git-pushes).
Activity history for projects and individuals' profiles was limited to one year until [GitLab 11.4](https://gitlab.com/gitlab-org/gitlab-foss/issues/52246) when it was extended to two years, and in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/33840) to three years.
## Number of embedded metrics
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/14939) in GitLab 12.7.
There is a limit when embedding metrics in GFM for performance reasons.
-**Max limit:** 100 embeds
## Number of webhooks
On GitLab.com, the [maximum number of webhooks](../user/gitlab_com/index.md#maximum-number-of-webhooks) per project, and per group, is limited.
@@ -100,12 +100,15 @@ The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its
The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown)
Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. That is,
all markup that is supported for display in the GitLab application itself. For now,
all markup supported for display in the GitLab application itself. For now,
use regular Markdown markup, following the rules in the linked style guide.
Note that Kramdown-specific markup (for example, `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help).
Hard-coded HTML is valid, although it's discouraged to be used while we have `/help`. HTML is permitted as long as:
### HTML in Markdown
Hard-coded HTML is valid, although it's discouraged from being used while we have `/help`.
HTML is permitted as long as:
- There's no equivalent markup in Markdown.
- Advanced tables are necessary.
...
...
@@ -130,7 +133,7 @@ to verify that proper capitalization and backticks are used. Words in backticks
be ignored by markdownlint.
In general, product names should follow the exact capitalization of the official names
of the products, protocols, etc.
of the products, protocols, and so on.
Some examples that will fail if incorrect capitalization is used:
...
...
@@ -138,7 +141,7 @@ Some examples that will fail if incorrect capitalization is used:
- NGINX (needs all capitals)
- runit (needs lowercase `r`)
Additionally, commands, parameters, values, filenames, etc. must be included in backticks.
Additionally, commands, parameters, values, filenames, and so on must be included in backticks.
For example:
- "Change the `needs` keyword in your `.gitlab.yml`..."
...
...
@@ -198,7 +201,7 @@ The table below shows what kind of documentation goes where.
1.`doc/user/group/` should contain all group related documentation.
1.`doc/user/profile/` should contain all profile related documentation.
Every page you would navigate under `/profile` should have its own document,
i.e. `account.md`, `applications.md`, `emails.md`, etc.
for example, `account.md`, `applications.md`, or `emails.md`.
1.`doc/user/dashboard/` should contain all dashboard related documentation.
1.`doc/user/admin_area/` should contain all admin related documentation
describing what can be achieved by accessing GitLab's admin interface
...
...
@@ -235,7 +238,7 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
### Structure within documents
- Include any and all applicable subsections as described on the [structure and template](structure.md) page.
- Structure content in alphabetical order in tables, lists, etc., unless there is
- Structure content in alphabetical order in tables, lists, and so on, unless there is
a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence).
## Language
...
...
@@ -271,9 +274,9 @@ Do not include the same information in multiple places. [Link to a SSOT instead.
- Use "may" to indicate giving permission for someone to do something, or consider using "can" instead. "You may select either option on this screen." Or, "you can select either option on this screen."
- We discourage use of Latin abbreviations, such as "e.g.," "i.e.," or "etc.,"
as even native users of English might misunderstand them.
- Instead of "i.e.", use "that is."
- Instead of "e.g.", use "for example," "such as," "for instance," or "like."
- Instead of "etc.", either use "and so on" or consider editing it out, since it can be vague.
- Instead of "i.e.," use "that is."
- Instead of "e.g.," use "for example," "such as," "for instance," or "like."
- Instead of "etc.," either use "and so on" or consider editing it out, since it can be vague.
### Contractions
...
...
@@ -332,8 +335,9 @@ as even native users of English might misunderstand them.
-[Write in Markdown](#markdown).
- Splitting long lines (preferably up to 100 characters) can make it easier to provide feedback on small chunks of text.
- Insert an empty line for new paragraphs.
- Add a new line by ending a line with two spaces. [Using a backslash](../../user/markdown.md#newlines) doesn't work in the docs site.
- Use sentence case for titles, headings, labels, menu items, and buttons.
- Insert an empty line between different markups (e.g., after every paragraph, header, list, etc). Example:
- Insert an empty line between different markups (for example, after every paragraph, header, list, and so on). Example:
```md
## Header
...
...
@@ -637,7 +641,7 @@ We include guidance for links in the following categories:
It's easier to read, review, and maintain. **Do not** use `[Text][identifier]`.
- Use [meaningful anchor texts](https://www.futurehosting.com/blog/links-should-have-meaningful-anchor-text-heres-why/).
E.g., instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
For example, instead of writing something like `Read more about GitLab Issue Boards [here](LINK)`,
write `Read more about [GitLab Issue Boards](LINK)`.
### Links to internal documentation
...
...
@@ -675,7 +679,8 @@ To link to internal documentation:
-`../../issues/tags.md`
-`../../issues/tags.md#stages`
- Use the Markdown extension for the [`/help`](index.md#gitlab-help) section of GitLab.
NOTE: **Note**:
Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help) section of GitLab.
### Links requiring permissions
...
...
@@ -721,9 +726,9 @@ To indicate the steps of navigation through the UI:
- Use the exact word as shown in the UI, including any capital letters as-is.
- Use bold text for navigation items and the char "greater than" (`>`) as separator
(e.g., `Navigate to your project's **Settings > CI/CD**` ).
(for example, `Navigate to your project's **Settings > CI/CD**` ).
- If there are any expandable menus, make sure to mention that the user
needs to expand the tab to find the settings you're referring to (e.g., `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
needs to expand the tab to find the settings you're referring to (for example, `Navigate to your project's **Settings > CI/CD** and expand **General pipelines**`).
## Images
...
...
@@ -852,7 +857,7 @@ nicely on different mobile devices.
## Code blocks
- Always wrap code added to a sentence in inline code blocks (`` ` ``).
