2018-05-09 11:07:11 +00:00
---
2022-05-30 00:08:35 +00:00
stage: Systems
2020-12-01 18:09:42 +00:00
group: Distribution
2020-11-26 06:09:20 +00:00
info: "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"
2018-05-09 11:07:11 +00:00
description: 'Learn how to install, configure, update, and maintain your GitLab instance.'
---
2021-01-28 06:08:59 +00:00
# Administrator documentation **(FREE SELF)**
2017-12-07 15:09:22 +00:00
2021-04-06 12:09:21 +00:00
If you use GitLab.com, only GitLab team members have access to administration tools and settings.
If you use a self-managed GitLab instance, learn how to administer it.
Only administrator users can access GitLab administration tools and settings.
## Available distributions
2017-12-07 15:09:22 +00:00
2019-02-18 09:53:38 +00:00
GitLab has two product distributions available through [different subscriptions ](https://about.gitlab.com/pricing/ ):
2018-02-22 16:13:35 +00:00
2019-09-18 14:02:45 +00:00
- The open source [GitLab Community Edition (CE) ](https://gitlab.com/gitlab-org/gitlab-foss ).
- The open core [GitLab Enterprise Edition (EE) ](https://gitlab.com/gitlab-org/gitlab ).
2019-02-18 09:53:38 +00:00
2019-07-08 22:24:54 +00:00
You can [install either GitLab CE or GitLab EE ](https://about.gitlab.com/install/ce-or-ee/ ).
2021-04-06 12:09:21 +00:00
However, the features you have access to depend on your chosen subscription.
2019-02-18 09:53:38 +00:00
2021-01-29 21:09:34 +00:00
GitLab Community Edition installations have access only to Free features.
2018-02-22 16:13:35 +00:00
2017-12-07 15:09:22 +00:00
## Installing and maintaining GitLab
Learn how to install, configure, update, and maintain your GitLab instance.
### Installing GitLab
2021-02-11 09:09:18 +00:00
- [Install ](../install/index.md ): Requirements, directory structures, and installation methods.
2020-05-14 21:07:52 +00:00
- [Reference architectures ](reference_architectures/index.md ): Add additional resources to support more users.
2022-03-30 12:09:14 +00:00
- [Installing GitLab on Amazon Web Services (AWS) ](../install/aws/index.md ): Set up GitLab on Amazon AWS.
2020-12-29 18:10:10 +00:00
- [Geo ](geo/index.md ): Replicate your GitLab instance to other geographic locations as a read-only fully operational version.
- [Disaster Recovery ](geo/disaster_recovery/index.md ): Quickly fail-over to a different site with minimal effort in a disaster situation.
2022-03-07 15:22:51 +00:00
- [Add License ](../user/admin_area/license.md ): Add a license at install time to unlock features that are in paid tiers of GitLab.
2017-12-07 15:09:22 +00:00
### Configuring GitLab
2021-09-23 22:34:10 +00:00
- [Adjust your instance's time zone ](timezone.md ): Customize the default time zone of GitLab.
2022-03-18 09:07:21 +00:00
- [System hooks ](system_hooks.md ): Notifications when users, projects and keys are changed.
2021-06-28 12:38:12 +00:00
- [Security ](../security/index.md ): Learn what you can do to further secure your GitLab instance.
2021-07-07 12:08:23 +00:00
- [Usage statistics, version check, and Service Ping ](../user/admin_area/settings/usage_statistics.md ): Enable or disable information about your instance to be sent to GitLab, Inc.
2019-03-15 03:19:04 +00:00
- [Global user settings ](user_settings.md ): Configure instance-wide user permissions.
2017-12-07 15:09:22 +00:00
- [Polling ](polling.md ): Configure how often the GitLab UI polls for updates.
- [GitLab Pages configuration ](pages/index.md ): Enable and configure GitLab Pages.
2020-12-16 00:09:58 +00:00
- [GitLab Pages configuration for GitLab source installations ](pages/source.md ):
Enable and configure GitLab Pages on [source installations ](../install/installation.md#installation-from-source ).
2019-10-28 00:06:29 +00:00
- [Uploads administration ](uploads.md ): Configure GitLab uploads storage.
2020-09-30 21:10:09 +00:00
- [Environment variables ](environment_variables.md ): Supported environment
variables that can be used to override their default values to configure
GitLab.
2021-05-19 18:10:39 +00:00
- [File hooks ](file_hooks.md ): With custom file hooks, GitLab administrators can
2020-12-16 00:09:58 +00:00
introduce custom integrations without modifying GitLab source code.
2018-04-27 14:50:33 +00:00
- [Enforcing Terms of Service ](../user/admin_area/settings/terms.md )
2022-01-07 03:14:36 +00:00
- [Customer experience improvement and third-party offers ](../user/admin_area/settings/third_party_offers.md )
2020-12-16 00:09:58 +00:00
- [Compliance ](compliance.md ): A collection of features from across the
application that you may configure to help ensure that your GitLab instance
and DevOps workflow meet compliance standards.
- [Diff limits ](../user/admin_area/diff_limits.md ): Configure the diff rendering
size limits of branch comparison pages.
- [Merge request diffs storage ](merge_request_diffs.md ): Configure merge
requests diffs external storage.
- [Broadcast Messages ](../user/admin_area/broadcast_messages.md ): Send messages
to GitLab users through the UI.
2022-06-14 18:09:25 +00:00
- [Elasticsearch ](../integration/advanced_search/elasticsearch.md ): Enable Elasticsearch to
2021-04-06 12:09:21 +00:00
empower Advanced Search. Use when you deal with a huge amount of data.
- [External Classification Policy Authorization ](../user/admin_area/settings/external_authorization.md )
2022-03-07 15:22:51 +00:00
- [Add a license ](../user/admin_area/license.md ): Add a license to unlock
2020-12-29 18:10:10 +00:00
features that are in paid tiers of GitLab.
2020-12-16 00:09:58 +00:00
- [Admin Area ](../user/admin_area/index.md ): for self-managed instance-wide
configuration and maintenance.
- [S/MIME Signing ](smime_signing_email.md ): how to sign all outgoing notification
emails with S/MIME.
- [Enabling and disabling features flags ](feature_flags.md ): how to enable and
disable GitLab features deployed behind feature flags.
2021-01-26 15:08:58 +00:00
- [Application settings cache expiry interval ](application_settings_cache.md )
2021-11-23 18:12:49 +00:00
- [Database Load Balancing ](postgresql/database_load_balancing.md ): Distribute database queries among multiple database servers.
- [Omnibus support for log forwarding ](https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only ).
2020-12-16 00:09:58 +00:00
#### Customizing GitLab appearance
2017-12-13 15:22:02 +00:00
2019-10-21 03:06:30 +00:00
- [Header logo ](../user/admin_area/appearance.md#navigation-bar ): Change the logo on all pages and email headers.
- [Favicon ](../user/admin_area/appearance.md#favicon ): Change the default favicon to your own logo.
- [Branded login page ](../user/admin_area/appearance.md#sign-in--sign-up-pages ): Customize the login page with your own logo, title, and description.
- ["New Project" page ](../user/admin_area/appearance.md#new-project-pages ): Customize the text to be displayed on the page that opens whenever your users create a new project.
2020-12-29 18:10:10 +00:00
- [Additional custom email text ](../user/admin_area/settings/email.md#custom-additional-text ): Add additional custom text to emails sent from GitLab.
2017-12-13 15:22:02 +00:00
2017-12-07 15:09:22 +00:00
### Maintaining GitLab
2021-02-11 09:09:18 +00:00
- [Rake tasks ](../raketasks/index.md ): Perform various tasks for maintenance, backups, automatic webhooks setup, and more.
2017-12-07 15:09:22 +00:00
- [Backup and restore ](../raketasks/backup_restore.md ): Backup and restore your GitLab instance.
2020-05-14 09:07:53 +00:00
- [Operations ](operations/index.md ): Keeping GitLab up and running (clean up Redis sessions, moving repositories, Sidekiq MemoryKiller, Puma).
2017-12-07 15:09:22 +00:00
- [Restart GitLab ](restart_gitlab.md ): Learn how to restart GitLab and its components.
2019-11-28 03:06:32 +00:00
- [Invalidate Markdown cache ](invalidate_markdown_cache.md ): Invalidate any cached Markdown.
2020-10-13 21:09:27 +00:00
- [Instance review ](instance_review.md ): Request a free review of your GitLab instance.
2017-12-07 15:09:22 +00:00
#### Updating GitLab
- [GitLab versions and maintenance policy ](../policy/maintenance.md ): Understand GitLab versions and releases (Major, Minor, Patch, Security), as well as update recommendations.
2021-01-27 21:09:12 +00:00
- [GitLab in maintenance mode ](maintenance_mode/index.md ): Put GitLab in maintenance mode.
2021-02-11 09:09:18 +00:00
- [Update GitLab ](../update/index.md ): Update guides to upgrade your installation to a new version.
- [Upgrading without downtime ](../update/index.md#upgrading-without-downtime ): Upgrade to a newer major, minor, or patch version of GitLab without taking your GitLab instance offline.
2017-12-07 15:09:22 +00:00
### Upgrading or downgrading GitLab
2021-04-06 12:09:21 +00:00
- [Upgrade from GitLab CE to GitLab EE ](../update/index.md#upgrading-between-editions ): Learn how to upgrade GitLab Community Edition to GitLab Enterprise Editions.
2021-02-11 09:09:18 +00:00
- [Downgrade from GitLab EE to GitLab CE ](../downgrade_ee_to_ce/index.md ): Learn how to downgrade GitLab Enterprise Editions to Community Edition.
2017-12-07 15:09:22 +00:00
### GitLab platform integrations
2021-09-16 18:11:32 +00:00
- [Mattermost ](../integration/mattermost/index.md ): Integrate with [Mattermost ](https://mattermost.com ), an open source, private cloud workplace for web messaging.
2021-04-06 12:09:21 +00:00
- [PlantUML ](integration/plantuml.md ): Create diagrams in AsciiDoc and Markdown documents
2020-04-21 15:21:10 +00:00
created in snippets, wikis, and repositories.
2021-10-30 18:12:04 +00:00
- [Web terminals ](integration/terminal.md ): Provide terminal access to your applications deployed to Kubernetes from GitLab CI/CD [environments ](../ci/environments/index.md#web-terminals-deprecated ).
2017-12-07 15:09:22 +00:00
## User settings and permissions
2019-09-10 09:24:33 +00:00
- [Creating users ](../user/profile/account/create_accounts.md ): Create users manually or through authentication integrations.
2019-10-21 03:06:30 +00:00
- [Libravatar ](libravatar.md ): Use Libravatar instead of Gravatar for user avatars.
2022-05-24 12:09:04 +00:00
- [Sign-up restrictions ](../user/admin_area/settings/sign_up_restrictions.md ): block email addresses of specific domains, or allow only specific domains.
2021-08-11 00:10:03 +00:00
- [Access restrictions ](../user/admin_area/settings/visibility_and_access_controls.md#configure-enabled-git-access-protocols ): Define which Git access protocols can be used to talk to GitLab (SSH, HTTP, HTTPS).
2021-06-28 12:38:12 +00:00
- [Authentication and Authorization ](auth/index.md ): Configure external authentication with LDAP, SAML, CAS, and additional providers.
2021-04-06 12:09:21 +00:00
- [Sync LDAP ](auth/ldap/index.md )
- [Kerberos authentication ](../integration/kerberos.md )
2019-05-05 15:21:25 +00:00
- See also other [authentication ](../topics/authentication/index.md#gitlab-administrators ) topics (for example, enforcing 2FA).
2022-03-21 18:07:23 +00:00
- [Email users ](../user/admin_area/email_from_gitlab.md ): Email GitLab users from GitLab.
2021-02-22 21:10:48 +00:00
- [User Cohorts ](../user/admin_area/user_cohorts.md ): Display the monthly cohorts of new users and their activities over time.
2021-04-06 12:09:21 +00:00
- [Audit events ](audit_events.md ): View the changes made on the GitLab server for:
2020-12-29 18:10:10 +00:00
- Groups and projects.
- Instances.
- [Auditor users ](auditor_users.md ): Users with read-only access to all projects, groups, and other resources on the GitLab instance.
2018-03-02 11:32:39 +00:00
- [Incoming email ](incoming_email.md ): Configure incoming emails to allow
2021-12-10 00:13:05 +00:00
users to [reply by email ](reply_by_email.md ), create [issues by email ](../user/project/issues/managing_issues.md#by-sending-an-email ) and
2021-07-05 18:06:54 +00:00
[merge requests by email ](../user/project/merge_requests/creating_merge_requests.md#by-sending-an-email ), and to enable [Service Desk ](../user/project/service_desk.md ).
2018-03-02 11:32:39 +00:00
- [Postfix for incoming email ](reply_by_email_postfix_setup.md ): Set up a
basic Postfix mail server with IMAP authentication on Ubuntu for incoming
emails.
2021-04-21 18:11:09 +00:00
- [Abuse reports ](../user/admin_area/review_abuse_reports.md ): View and resolve abuse reports from your users.
2020-12-29 18:10:10 +00:00
- [Credentials Inventory ](../user/admin_area/credentials_inventory.md ): With Credentials inventory, GitLab administrators can keep track of the credentials used by their users in their GitLab self-managed instance.
2017-12-07 15:09:22 +00:00
## Project settings
- [Issue closing pattern ](issue_closing_pattern.md ): Customize how to close an issue from commit messages.
2020-12-16 00:09:58 +00:00
- [Gitaly ](gitaly/index.md ): Configuring Gitaly, the Git repository storage service for GitLab.
2020-11-19 21:09:07 +00:00
- [Default labels ](../user/admin_area/labels.md ): Create labels that are automatically added to every new project.
2022-03-18 18:07:26 +00:00
- [Restrict the use of public or internal projects ](../user/public_access.md#restrict-use-of-public-or-internal-projects ): Restrict the use of visibility levels for users when they create a project or a snippet.
2020-12-29 18:10:10 +00:00
- [Custom project templates ](../user/admin_area/custom_project_templates.md ): Configure a set of projects to be used as custom templates when creating a new project.
2019-09-17 12:06:48 +00:00
## Package Registry administration
2021-02-15 03:08:58 +00:00
- [Container Registry ](packages/container_registry.md ): Configure GitLab to act as a registry for containers.
- [Package Registry ](packages/index.md ): Enable GitLab to act as a registry for packages.
2020-11-13 21:09:31 +00:00
- [Dependency Proxy ](packages/dependency_proxy.md ): Configure the Dependency Proxy, a local proxy for frequently used upstream images/packages.
2018-07-30 17:20:11 +00:00
2017-12-07 15:09:22 +00:00
### Repository settings
2021-04-06 12:09:21 +00:00
- [Repository checks ](repository_checks.md ): Check your repository for data corruption.
2017-12-07 15:09:22 +00:00
- [Repository storage paths ](repository_storage_paths.md ): Manage the paths used to store repositories.
2019-09-04 12:24:58 +00:00
- [Repository storage types ](repository_storage_types.md ): Information about the different repository storage types.
2020-03-31 12:08:09 +00:00
- [Repository storage Rake tasks ](raketasks/storage.md ): A collection of Rake tasks to list and migrate existing projects and attachments associated with it from Legacy storage to Hashed storage.
2020-12-29 18:10:10 +00:00
- [Limit repository size ](../user/admin_area/settings/account_and_limit_settings.md ): Set a hard limit for your repositories' size.
2019-07-22 14:56:40 +00:00
- [Static objects external storage ](static_objects_external_storage.md ): Set external storage for static objects in a repository.
2017-12-07 15:09:22 +00:00
2021-08-23 18:11:07 +00:00
## CI/CD settings
2017-12-07 15:09:22 +00:00
2021-08-23 18:11:07 +00:00
- [Enable or disable GitLab CI/CD ](cicd.md#disable-gitlab-cicd-in-new-projects ): Set new projects in your instance to have GitLab CI/CD enabled or disabled by default.
2021-02-16 00:09:01 +00:00
- [GitLab CI/CD administration settings ](../user/admin_area/settings/continuous_integration.md ): Enable or disable Auto DevOps site-wide and define the artifacts' max size and expiration time.
2021-04-06 12:09:21 +00:00
- [External Pipeline Validation ](external_pipeline_validation.md ): Enable, disable, and configure external pipeline validation.
2017-12-07 15:09:22 +00:00
- [Job artifacts ](job_artifacts.md ): Enable, disable, and configure job artifacts (a set of files and directories which are outputted by a job when it completes successfully).
2019-10-18 00:07:45 +00:00
- [Job logs ](job_logs.md ): Information about the job logs.
2021-06-10 12:10:09 +00:00
- [Register runners ](../ci/runners/runners_scope.md ): Learn how to register and configure runners.
2021-12-20 18:13:27 +00:00
- [Shared runners quota of CI/CD minutes ](../ci/pipelines/cicd_minutes.md ): Limit the usage of CI/CD minutes for shared runners.
2021-08-23 18:11:07 +00:00
- [Enable or disable Auto DevOps ](../topics/autodevops/index.md#enable-or-disable-auto-devops ): Enable or disable Auto DevOps for your instance.
2017-12-07 15:09:22 +00:00
2019-12-02 12:06:45 +00:00
## Snippet settings
2020-07-17 15:09:13 +00:00
- [Setting snippet content size limit ](snippets/index.md ): Set a maximum content size limit for snippets.
## Wiki settings
- [Setting wiki page content size limit ](wikis/index.md ): Set a maximum content size limit for wiki pages.
2019-12-02 12:06:45 +00:00
2017-12-07 15:09:22 +00:00
## Git configuration options
2021-02-04 09:09:30 +00:00
- [Server hooks ](server_hooks.md ): Server hooks (on the file system) for when webhooks aren't enough.
2020-04-09 06:09:30 +00:00
- [Git LFS configuration ](lfs/index.md ): Learn how to configure LFS for GitLab.
2017-12-07 15:09:22 +00:00
- [Housekeeping ](housekeeping.md ): Keep your Git repositories tidy and fast.
2018-10-17 11:52:10 +00:00
- [Configuring Git Protocol v2 ](git_protocol.md ): Git protocol version 2 support.
2017-12-07 15:09:22 +00:00
## Monitoring GitLab
2017-12-14 18:24:42 +00:00
- [Monitoring GitLab ](monitoring/index.md ):
- [Monitoring uptime ](../user/admin_area/monitoring/health_check.md ): Check the server status using the health check endpoint.
2022-05-30 18:08:57 +00:00
- [IP allowlist ](monitoring/ip_whitelist.md ): Monitor endpoints that provide health check information when probed.
2020-12-16 00:09:58 +00:00
- [Monitoring GitHub imports ](monitoring/github_imports.md ): The GitLab GitHub Importer displays Prometheus metrics to monitor the health and progress of the importer.
2017-12-07 15:09:22 +00:00
### Performance Monitoring
2017-12-14 18:24:42 +00:00
- [GitLab Performance Monitoring ](monitoring/performance/index.md ):
- [Enable Performance Monitoring ](monitoring/performance/gitlab_configuration.md ): Enable GitLab Performance Monitoring.
- [GitLab performance monitoring with Prometheus ](monitoring/prometheus/index.md ): Configure GitLab and Prometheus for measuring performance metrics.
- [GitLab performance monitoring with Grafana ](monitoring/performance/grafana_configuration.md ): Configure GitLab to visualize time series metrics through graphs and dashboards.
- [Performance Bar ](monitoring/performance/performance_bar.md ): Get performance information for the current page.
2017-12-07 15:09:22 +00:00
## Troubleshooting
- [Log system ](logs.md ): Where to look for logs.
- [Sidekiq Troubleshooting ](troubleshooting/sidekiq.md ): Debug when Sidekiq appears hung and is not processing jobs.
2019-10-01 03:05:57 +00:00
- [Troubleshooting Elasticsearch ](troubleshooting/elasticsearch.md )
2022-07-05 21:08:45 +00:00
- [Navigating GitLab via Rails console ](operations/rails_console.md )
2020-01-17 12:08:34 +00:00
- [GitLab application limits ](instance_limits.md )
2022-04-07 15:09:57 +00:00
- [Responding to security incidents ](../security/responding_to_security_incidents.md )
2019-09-05 05:21:33 +00:00
2022-07-07 00:09:59 +00:00
### Support Team Documentation
2019-09-05 05:21:33 +00:00
2021-04-06 12:09:21 +00:00
The GitLab Support Team has collected a lot of information about troubleshooting GitLab.
The following documents are used by the Support Team or by customers
2019-09-05 05:21:33 +00:00
with direct guidance from a Support Team member. GitLab administrators may find the
2021-04-06 12:09:21 +00:00
information useful for troubleshooting. However, if you are experiencing trouble with your
2019-09-05 05:21:33 +00:00
GitLab instance, you should check your [support options ](https://about.gitlab.com/support/ )
before referring to these documents.
2020-12-04 21:09:29 +00:00
WARNING:
2021-04-06 12:09:21 +00:00
The commands in the following documentation might result in data loss or
other damage to a GitLab instance. They should be used only by experienced administrators
2019-09-05 05:21:33 +00:00
who are aware of the risks.
2021-04-06 12:09:21 +00:00
- [Diagnostics tools ](troubleshooting/diagnostics_tools.md )
- [Linux commands ](troubleshooting/linux_cheat_sheet.md )
2022-07-06 00:09:36 +00:00
- [Troubleshooting Kubernetes ](https://docs.gitlab.com/charts/troubleshooting/kubernetes_cheat_sheet.html )
2019-10-15 18:06:01 +00:00
- [Troubleshooting PostgreSQL ](troubleshooting/postgresql.md )
2019-09-05 05:21:33 +00:00
- [Guide to test environments ](troubleshooting/test_environments.md ) (for Support Engineers)
2019-10-01 03:05:57 +00:00
- [GitLab Rails console commands ](troubleshooting/gitlab_rails_cheat_sheet.md ) (for Support Engineers)
2020-01-28 09:09:06 +00:00
- [Troubleshooting SSL ](troubleshooting/ssl.md )
2021-04-06 12:09:21 +00:00
- Related links:
2021-06-28 12:38:12 +00:00
- [GitLab Developer Documentation ](../development/index.md )
2019-09-05 05:21:33 +00:00
- [Repairing and recovering broken Git repositories ](https://git.seveas.net/repairing-and-recovering-broken-git-repositories.html )
2022-06-09 09:09:12 +00:00
- [Testing with OpenSSL ](https://www.feistyduck.com/library/openssl-cookbook/online/testing-with-openssl/index.html )
2020-09-04 09:08:38 +00:00
- [`strace` zine ](https://wizardzines.com/zines/strace/ )
2020-02-06 03:08:47 +00:00
- GitLab.com-specific resources:
- [Group SAML/SCIM setup ](troubleshooting/group_saml_scim.md )